home *** CD-ROM | disk | FTP | other *** search
/ Millennium Time Capsule / AC2000.BIN / disks / ac16disk / articles / features / prog_gem / prog_gem.asc < prev   
Encoding:
Text File  |  1999-10-06  |  5.3 KB  |  119 lines

  1. Our Little GEM
  2.  
  3. Mark Wherry takes the first step on a guided tour of the unknown...
  4.  
  5.  
  6. One thing that all Atari programmers will eventually have to face is GEM. 
  7. The Graphics Environment Manager provides support for four modules, the 
  8. AES, the VDI, the BIOS and GEMDOS.  In these articles we will be focusing 
  9. upon the AES and the VDI.
  10.  
  11. The Application Environment Services handles windows, icons, resource 
  12. files, dialogues, alert boxes, file selectors, menus and graphical based 
  13. inputs (eg. moving a window).  When we talk about AES replacements, the 
  14. above are the operations that are rewritten. If you're interested in how 
  15. the AES is written, why not take a look at the source code for XaAES or 
  16. oAESis.
  17.  
  18. The VDI (Virtual Device Interface) provides a set of graphics functions 
  19. that are independent of physical hardware and enable you to create a 
  20. virtual workstation, in which you can define and output graphics to a 
  21. device.  The popular utility NVDI (New Virtual Device Interface) replaces 
  22. the original VDI with faster, superior code that is a dramatic 
  23. improvement. If you are an NVDI user (and if not why not?!), you don't 
  24. have to worry about compatibility because, the way NVDI is accessed by GEM 
  25. is exactly the same as the real VDI.
  26.  
  27. For these articles, I'm going to use the high-level language 'C'; for many 
  28. reasons.  I like 'C' (!), it's popular and ideally suited to the task.  In 
  29. my opinion GEM programming is more difficult in something like GFA Basic! 
  30. However, Pascal or Modula-2 programmers shouldn't have too much difficulty 
  31. in adapting the listings.
  32.  
  33. The first thing we must do at the start of our program is to initialise 
  34. the AES and the VDI.  Remember also, to include the relevant header files, 
  35. eg. <aes.h> and <vdi.h>.  For the AES, simply include the statement:
  36. ap_id=appl_init(); where ap_id is an integer that will contain an 
  37. identifier given to your application by the AES.
  38.  
  39. To initialise the VDI is slightly more complicated.  We start by using the 
  40. graf_handle function, which returns an id number for the screen which is 
  41. being used by the AES. This is known as the physical handle:
  42. vhandle=graf_handle(&char_height,&char_width,&cell_height,&cell_width);
  43. The shorts char_height and char_width return the height and width of each 
  44. character, while cell_width and cell_height return the size of the 
  45. rectangular box it occupies.  Usually this information isn't needed, so we 
  46. can call the function like this:
  47. vhandle=graf_handle(&junk,&junk,&junk,&junk);
  48.  
  49. As you know, most GEM programs work happily in any resolution, but, this 
  50. is only because of a special function, called v_opnvwk (open virtual 
  51. screen workstation).  This automatically finds out the size of the screen 
  52. and how many colours can be displayed on it.  v_opnvwk uses arrays of 
  53. integers which are usually called work_in, and work_out, and should be 
  54. defined at the start of your program as:
  55. int work_in[11]={1,1,1,1,1,1,1,1,1,1,1,2};
  56. int work_out[57];
  57. We will look at what these numbers mean later on, but if you're desperate, 
  58. try looking in your compiler's manual.  But finally, we call v_opnvwk like 
  59. this:
  60. v_opnvwk(work_in,&vhandle,work_out);
  61.  
  62.  
  63. Now that wasn't so bad, was it?  Well, now for something really clever, 
  64. let's define a window.  For this, the following identifiers will need to 
  65. be defined as follows:
  66. int whandle;
  67. int wx,wy,ww,wh;
  68. short gx,gy,gw,gh;
  69. char *title;
  70.  
  71.  
  72. First of all, we need to create a new window in the AES, this will not 
  73. appear on screen just yet though.  To do this we use the wind_create 
  74. function, which returns a handle.  This handle has nothing to do with the 
  75. physical (VDI) handle (or even a GEMDOS handle).  The returned window 
  76. handle uniquely identifies our window from any other currently managed by 
  77. the AES:
  78. whandle=wind_create(PROPERTIES,wx,wy,ww,wh);
  79. PROPERTIES can include any of the following:
  80. NAME, title bar with title.
  81. CLOSE, a close box.
  82. FULL, a full box.
  83. MOVE, the window can be moved.
  84. INFO, an information line below the title bar.
  85. SIZE, a sizer box.
  86. UPARROW, an up arrow.
  87. DNARROW, a down arrow.
  88. VSLIDE, a vertical slider.
  89. LFARROW, a left arrow.
  90. RTARROW, a right arrow.
  91. HSLIDE, a horizontal slider.
  92.  
  93. So, for example, to define a moveable window with a titlebar and closer, 
  94. you would do this:
  95. whandle=wind_create(NAME|CLOSE|MOVE,wx,wy,ww,wh);
  96. If you haven't already guessed, the integers wx,wy,ww and wh define the x 
  97. and y coordinates, and the width and height of the window.  It's good 
  98. practice to do this as oppose to using values directly, as you will only 
  99. get tangled up later!
  100.  
  101. Before we finally open the window we must first set the title for our 
  102. window, and this is achieved by the wind_set command:
  103. wind_set(whandle,WF_NAME,ADDR(title),0,0);
  104. WF_NAME is the request sent to the wind_set function.  There are many 
  105. other requests you can send to wind_set to set other window parameters 
  106. which we will cover later. The title address character pointer must be 
  107. split into the high and low words.  Don't worry about this though, you can 
  108. simply use the ADDR macro as shown.
  109.  
  110. After all this, we can finally open the window like this:
  111. wind_open(whandle,wx,wy,ww,wh);
  112.  
  113. .....and that's all there is to it!
  114.  
  115. And that's how to put a window on the screen.  There is however one thing 
  116. that might surprise you when you run this program, and that's what we'll 
  117. look at next time, see you then.  A complete listing is on the reader disk 
  118. (hopefully), if you run into any problems.
  119.