home *** CD-ROM | disk | FTP | other *** search
/ No Fragments Archive 10: Diskmags / nf_archive_10.iso / MAGS / CHOSNECK / CHOS2.ZIP / CHOSNECK.2ND / STUFF / DATAS.ZIP / ART52.SCR < prev    next >
Encoding:
Text File  |  1989-06-08  |  8.2 KB  |  163 lines
  1. <head>
  2. <title="...forever...">
  3. <font=monaco10.fnt>
  4. <font=newy36.fnt>
  5. <font=time24.fnt>
  6. <image=back.raw w=256 h=256 t=-1>
  7. <buf=2302>
  8. <bgcolor=-1>
  9. <background=0> 
  10. <link_color=000>
  11. <module=console.mod>
  12. <pal=back.pal>
  13. colors:
  14. 251 - black
  15. </head>
  16. <body>
  17. <frame x=0 y=0 w=640 h=2302 b=-1 c=-1>
  18.  
  19.  
  20.                - -- -- -------------------------------------- 
  21.  <f1><c000>         .: GEM in one pill :. <f0>
  22.                ----------------------------------------- - --   
  23.   
  24.                compiled by Saulot / Nokturnal / Chosneck TEAM
  25.                                  1.11.2003 
  26.                
  27.  
  28. 1) Introduction
  29. ---------------------
  30. The  GEMcandy  competition is near. So I thought is a good moment to remove the 
  31. layer   of  dust  from  the  long  forgotten  and  ancient  wisdom  called  GEM 
  32. programming.  I haven't found many sources of information in one concrete piece 
  33. that could show how to start. You can find numerous function references in many 
  34. books and text files scattered on the web, but how to use them? Well, I managed 
  35. to  compile  the  information  from  various  sources (mainly from really great 
  36. Jonathan  White's  and Tim Oren's tutorials which are more or less complete) to 
  37. show  how GEM applications can be done, discussing various topics, how to fully 
  38. manage  them  in  step by step manner. In this tutorial you will not be able to 
  39. find  the  complete  references  to  system  functions (no time, no space). You 
  40. should  look at the better resources like "Atari Compedium" or another one. The 
  41. second  reason  was  that  at  this  moment  there are several really great GEM 
  42. libraries,  but without good knowlege about how the functions work and what for 
  43. they exist you will not be able to do anything. 
  44.  
  45. Before I start, I would like to excuse for omissions or eventual errors. If you 
  46. find  something  very  offensive, some fatal errors or you simply want to point 
  47. out  what is still missing mail me. The handling of more modern OS'es like MiNT 
  48. or  Magic  is  not  covered here also protocols like OLGA, VA_START, DRAG&DROP, 
  49. BUBBLEGEM  and  various  system extensions ,because I haven't much resources on 
  50. this  topic,  but you should be prepared to see it in the near future revisions 
  51. of  this tutorial. I would like also to see some feedback on the tutorials that 
  52. I  wrote (or still writing). I really need it. I know that for now the audience 
  53. of  Chosneck  is  quite  small  (lack  of ST/E shell, ST-RAM hunger and several 
  54. incompatibilities),  but  it  should  be fixed now from several reasons. One of 
  55. this  reasons  is  a  website  done  by  me  about  16/32 bit Atari programming 
  56. (http://www.republika.pl/nokturnal). There you should find most of my articles, 
  57. (hopefully) download Chosneck magazine and maybe read all the articles online. 
  58.  
  59. 2) So we start!
  60. ----------------------
  61. At the beginning and end of every GEM program several steps should be taken:
  62. - the initialisation of AES (if error then quit)
  63. - the initialisation of VDI and opening of the virtual workstation (if error 
  64.   occurs then program can run, but this is not recommended)
  65. - loading of RSC resource file (if not possible then quit)
  66.  
  67. RSC file considerations 
  68.  
  69. With resource files we have two considerations. We can load them during program 
  70. start  or embed them directly in our program. The best is of course the loading 
  71. the resource file from the external file. This has several advantages: 
  72. the  resource  can  be translated to another languages without your involvement 
  73. (and hacking your program to pieces), the resource isn't included each time you 
  74. compile the program (time is a precious thing), the adding new features is much 
  75. easier  (you  include the new feature and you add some code into you program to 
  76. detect this new RSC feature). 
  77.  
  78. AES initialisation 
  79.  
  80. Firstly   we  are  calling  appl_init()  function,  which  returns  the  global 
  81. application  identifier.  If appl_init() returns -1 then AES cannot be used and 
  82. we must terminate the program. 
  83. If  this  condition  not occured then we can read from the global array and get 
  84. some information about the system with app_getinfo(). 
  85. If appl_init() worked ok then we can use graf_handle() function (the info about 
  86. the  size  of  system  fonts  -  it  returns  id  of screen, which is needed to 
  87. initialise the VDI). 
  88.  
  89. VDI initialisation
  90.  
  91. We  are  initialising  VDI  with  v_opnvwk(),  which needs as an input an array 
  92. (called  WORK_IN  further in this article) with some settings and another array 
  93. (called  WORK_OUT) for holding the returned values. Moreover v_opnvwk() returns 
  94. the  handle which is needed to displaying graphics and text on the screen. This 
  95. number  is  set  in  the  beginning on the value returned by graf_handle(), but 
  96. after calling of earlier mentioned function, it's value is changing (after that 
  97. it  holds  handle of VDI workstation). Because AES handle can be helpful in the 
  98. future  (it  holds  handle of physical screen), it's wise to store it somewhere 
  99. (separate  variable).  
  100. WARNING!  This  function  opens  virtual workstation (that's because the system 
  101. needs  the  screen make it accessible to another applications and filters every 
  102. output).  For  example  during  printing  document  via printer, the GDOS opens 
  103. printer  as  a  workstation  (with v_opnvwk()), that's because two applications 
  104. cannot print simultanously. 
  105.  
  106. The  content  of  arrays  WORK_IN  and WORK_OUT are containing informations for 
  107. example  how  many coulours can be displayed/printed by device and which system 
  108. drawing functions can be used (more about it later) and much more. 
  109. WORK_IN  is  important, that's because it tells if the system will be using the 
  110. actual  screen  coordinates  or  normalized  device  coordinates (NDC). The NDC 
  111. system treats the screen as a device which can display 32767*32767 points. This 
  112. means,  that  no matter what resolution we have, the square 16384*16384 will be 
  113. always  covering  the  1/4  of the screen area. This system is very useful with 
  114. creating  WYSIWYG  (What  You  See  Is  What  You  Get)  applications. The same 
  115. coordinates can be used for screen and printer for example. GEM manages scaling 
  116. (on the output) pretty well, but scaling ratio isn't handled at all. 
  117.  
  118. Next  function  used during VDI initialisation is vq_extend(). This one returns 
  119. further informations about the device with given VDI handle. 
  120. If  v_opnvwk()  returns 0, we can't use VDI at all, something went wrong and we 
  121. must quit immadiately. We can possibly show the dialog window with error number 
  122. that informs the user about VDI non-availability and possible cause. 
  123.  
  124. Loading the resource file 
  125.  
  126. The  resource  file  is  that part of our program, which presents itself to the 
  127. user.  This  is  a set of standard structures which are defined in AES.H header 
  128. file  and  are  called  OBJECTS. Each dialog box is an object, equally as menu. 
  129. Each resource file can have several types of objects. 
  130. To include resource file in our program we simply call rsrc_load() function. As 
  131. parameters we give the name of our rsc file(NULL terminated string). 
  132. Function  returns 0 if RSC file wasn't found (it isn't in the current directory 
  133. with  the  executable). We can of course give the full path and specify another 
  134. storing  place  of  resource  file,  but it is very unpractical and it can make 
  135. problems with installation of your application. 
  136. Good practice is to give the resource file the same name as in executable file. 
  137. The function performs all the needed memory allocation and if everything was ok 
  138. it should return the pointer to the beginning RSC tree structure. 
  139.    
  140. Freeing the resource file
  141.  
  142. We  are  releasing the previously loaded RSC file with rsrc_free() function. It 
  143. returns  0  if  the  allocated  memory  cannot  be  freed (tell about it to the 
  144. application user !). 
  145.    
  146. Closing of the VDI workstation
  147.  
  148. We  are  calling  v_clsvwk()  with  VDI  handle  returned  in  the beginning by 
  149. v_opnvwk() passed as a parameter. 
  150.    
  151. Exit the application
  152.  
  153. Use appl_exit(). That's all !
  154.  
  155. This  is  basically what should perform every GEM application. If you are lucky 
  156. you  should at this stage see a green (or another) desktop and quit gracefully. 
  157. Now we are ready to do... 
  158.  
  159. <link=art52b.scr>Go to PART #2</l>
  160. </frame>
  161. </body>
  162.  
  163.