home *** CD-ROM | disk | FTP | other *** search
/ No Fragments Archive 10: Diskmags / nf_archive_10.iso / MAGS / ST_USER / 1990 / USERJL90.MSA / TEXT_GEM.DOC < prev    next >
Text File  |  1990-05-15  |  12KB  |  218 lines
  1.                                 All at C?
  2.  
  3.                    Roland Waddilove provides a guiding hand
  4.                   through the tangled GEM programming jungle
  5.  
  6. WELCOME to the first part of a new series exploring GEM from a programmer's
  7. viewpoint. If you have ever wondered how dialog and alert boxes pop up and
  8. windows zoom out and fill the desktop, and wanted to produce these objects
  9. yourself, then read on. This series is for you.
  10.     I'll make the programming examples as simple as possible, but inevitably
  11. there will be some quite complex looking functions and devious code. This will
  12. be kept to a minimum and thoroughly explained as we progress and build up our
  13. GEM programming knowledge.
  14.     Ideally you'll have a C compiler ready to hand when following this series,
  15. but don't despair if you are a Pascal programmer, Forth fanatic or even a BASIC
  16. boffin as the GEM functions we'll be using have the same names and use the same
  17. parameters whatever the language.
  18.     I'll be writing most of the example programs using Digital Wizdom C, and
  19. also providing corresponding HiSoft BASIC listings, too. This month in the
  20. LISTINGS folder you'll find GEM1.C and GEM1.BAS - two programs that perform
  21. identical tasks, one written in C and the other in BASIC. Let's see how they
  22. work.
  23.     GEM can be split up into two parts, the AES and the VDI. The AES
  24. (applications environment services) is responsible for creating, displaying and
  25. manipulating windows, dialog boxes and menu bars. The VDI (virtual device
  26. interface) has the task of handling all the graphic output for GEM. Of the two,
  27. the VDI is the easiest to use so that is where we will start our journey
  28. through the tangled jungle of GEM functions. Once we have mastered the VDI then
  29. we'll move on to the AES and create windows and dialog boxes.
  30.     GEM is capable of an amazing variety of graphic and text output - just
  31. think of a paint package like Degas Elite or a DTP Package like Fleet Street
  32. Publisher. Dozens of fill patterns, line types, text styles and point sizes can
  33. easily be output to the screen so GEM needs to keep track of what effects are
  34. currently in use and their settings. This information is stored in five integer
  35. arrays and you'll find them at the start of most C programs:
  36.  
  37. short    control[12],
  38.          intin[128],
  39.          ptsin[128],
  40.          intout[128],
  41.          ptsout[128];
  42.  
  43.     These arrays need to be defined, but you shouldn't need to access them from
  44. a high level language. Just define them, then forget about them. Once these
  45. have been defined your application (program) can ask GEM to initialise them by
  46. calling the appl_init() function. This returns an application identification
  47. number which you may need later on so it's a good idea to remember it:
  48.  
  49. short app_id;
  50. app_id = appl_init();
  51.  
  52.     When a program has finished and you want to go back to the desktop you must
  53. tell GEM by calling the appl_exit() function. This performs some tidying up
  54. operations, releases the memory reserved for the arrays and so on.
  55.     Two more arrays need to be defined and these tell GEM whether you are using
  56. a monitor or printer, solid lines or dashes, patterned or solid fills and so
  57. on. The vast majority of programs use the following startup code:
  58.  
  59. short    work_in[11],
  60.          work_out[57];
  61.  
  62. short    i;
  63.  
  64. for ( i=0; i<10; ++i )
  65.      work_in[i] = 1;
  66. work_in[10] = 0;
  67.  
  68.     This sets the various parameters GEM requires to suitable default values.
  69. Here is a list of the work_in[11] array's functions and the possible values
  70. each item may take (notice that a value of one is useually a good default):
  71.  
  72. ------------------------------------------------------------------------------
  73. work_in[0]    Device id number:   1 = screen          11 = plotter
  74.                                  21 = printer         31 = metafile
  75.                                  41 = camera          51 = tablet
  76. ------------------------------------------------------------------------------
  77. work_in[1]    Linetype:           1 = solid            2 = long dashes
  78.                                   3 = dots             4 = dashes+dots
  79.                                   5 = short dashes     6 = dash, dot, dot
  80.                                   7 = user defined    >7 = device dependent
  81. ------------------------------------------------------------------------------
  82. work_in[2]    Polyline color      0 = white            8 = white
  83.                                   1 = black            9 = black
  84.                                   2 = red             10 = light red
  85.                                   3 = green           11 = light green
  86.                                   4 = blue            12 = light blue
  87.                                   5 = cyan            13 = light cyan
  88.                                   6 = yellow          14 = light yellow
  89.                                   7 = magenta         15 = light magenta
  90. ------------------------------------------------------------------------------
  91. work_in[3]    Marker type         1 = dot              5 = diagonal cross
  92.                                   2 = plus sign        6 = diamond
  93.                                   3 = asterisk         7 = device dependent
  94.                                   4 = square
  95. ------------------------------------------------------------------------------
  96. work_in[4]    Polymarker colour   See Polyline colour
  97. ------------------------------------------------------------------------------
  98. work_in[5]    Text face
  99. ------------------------------------------------------------------------------
  100. work_in[6]    Text colour         See polyline colour
  101. ------------------------------------------------------------------------------
  102. work_in[7]    Fill interior style 0 = hollow           1 = solid
  103.                                   2 = patterned        3 = cross hatched
  104.                                   4 = user defined
  105. ------------------------------------------------------------------------------
  106. work_in[8]    Fill style index    (37 different fill styles)
  107. ------------------------------------------------------------------------------
  108. work_in[9]    Fill colour         See Polyline colour
  109. ------------------------------------------------------------------------------
  110. work_in[10]   Coordinate system   0 = map normalised device coordinates to
  111.                                       raster coordinates
  112.                                   1 = reserved
  113.                                   2 = use raster coordinates
  114. ------------------------------------------------------------------------------
  115.  
  116.     Unfortunately, I haven't the space here to list the contents of the 57
  117. work_out[] array elements so you'll need a reference manual if you're
  118. interested in the information in that array. It contains data like the number
  119. of colours available, the width and height of characters, the number of fill
  120. patterns on offer and so on.
  121.     Fortunately, you can forget work_out[57] for the moment and simply set
  122. work_in[0] to work_in[9] to one and work_in[10] to zero. Once this has been
  123. done you then ask GEM to open a virtual workstation.
  124.     A VDI graphic environment is called a workstation which has an associated
  125. number called a handle. The GEM Desktop opens a workstation for the screen and
  126. since all programs are run from the Desktop a program can't open another
  127. workstation for the screen as only one is allowed for each device. The problem
  128. is solved by opening a virtual workstation that inherits all the features of
  129. the currently open workstation. A new handle is returned for the virtual
  130. workstation. Here is the function to open it:
  131.  
  132. v_opnvwk(work_in, &handle, work_out);
  133.  
  134.     It requires the address of the work_in[] and work_out[] arrays and also the
  135. address of a variable in which it can store the virtual workstation handle.
  136.     Now that we have initialised the various GEM arrays, got our application id
  137. and opened a virtual workstation what can we do now? The first task is to clear
  138. the screen and this is performed by the v_clrwk(handle) function. Notice that
  139. it requires the handle of the virtual workstation to clear as there can be more
  140. than one at a time.
  141.     It would be nice to display a simple message on the screen and we can
  142. easily do this with v_gtext(x,y,string) like:
  143.  
  144. v_gtext(handle, 16, 16,"This is a test...");
  145. v_gtext(handle, 16, 48,"Click the mouse button...");
  146.  
  147.     Again, notice that the handle is passed as the first parameter. Then comes
  148. the x and y coordinates and the text string. The origin (0,0) is in the top
  149. left corner of the screen and y increases down the screen and x increases
  150. across the screen.
  151.     We need time to read the message we are displaying so let's wait until the
  152. mouse button is pressed. The function vq_mouse() reports the coordinates of the
  153. mouse and the state of its buttons:
  154.  
  155. short x, y, button;
  156. do {
  157.     vq_mouse(handle, &button, &x, &y);
  158. } while ( button==0 );
  159.  
  160.     The value of button is one if the left mouse button is pressed, two if the
  161. right button is pressed and three if both are pressed. This do{ ... } while()
  162. loop waits until any or both buttons are pressed.
  163.     When the program has finished the virtual workstation must be closed down
  164. with v_clsvwk(handle) before calling appl_exit() to tell GEM we've finished.
  165.  
  166.     That is quite enough for one month as there is a lot of information here to
  167. get to grips with. Part two of this series will be on the August Atari ST User
  168. Cover Disc and will document some useful VDI functions. Don't miss it!
  169.  
  170. ------------------------------------------------------------------------------
  171. A:\LISTINGS\GEM1.C      (HiSoft BASIC version - A:\LISTINGS\GEM1.BAS)
  172. ------------------------------------------------------------------------------
  173. /* Using the VDI: Program I */
  174. /*     By R.A.Waddilove     */
  175. /*     Digital Wizdom C     */
  176.  
  177. /* short is a 16-bit integer and is    */
  178. /* equivalent to most C compilers' int */
  179.  
  180. short    control[12],             /* These arrays are used by  */
  181.          intin[128],              /* GEM and you don't need to */
  182.          ptsin[128],              /* worry about them. Define  */
  183.          intout[128],             /* them, then forget them.   */
  184.          ptsout[128];
  185.  
  186. short    handle,                  /* virtual workstation handle */
  187.          app_id;                  /* application's id number */
  188.  
  189. short    work_in[12],        /* holds various parameters which set the */
  190.          work_out[57];       /* line type, fill pattern, text style etc. */
  191.  
  192. main()
  193. {
  194.      short i;                     /* loop counter, nothing important */
  195.      app_id = appl_init();        /* initialise GEM AES arrays, return id */
  196.      for ( i=0; i<10; ++i )       /* set line type, text style, fill style */
  197.           work_in[i] = 1;         /* text style and other parameters */
  198.      work_in[10] = 0;             /* raster coordinates ie. pixels */
  199.      v_opnvwk(work_in, &handle, work_out);  /* open virtual workstation */
  200.  
  201.      v_clrwk(handle);             /* clear the screen */
  202.      v_gtext(handle, 16, 16,"This is a test..."); /* print some text */
  203.      v_gtext(handle, 16, 32,"Click the mouse button..."); /* more text */
  204.      wait();                      /* wait for mouse click */
  205.  
  206.      v_clsvwk(handle);            /* close virtual workstation */
  207.      appl_exit();                 /* tell GEM we've finished */
  208. }
  209.  
  210. wait()
  211. {
  212.      short x, y, button;
  213.      do {
  214.           vq_mouse(handle, &button, &x, &y); /* get mouse x,y,button state */
  215.      } while ( button==0 );       /* wait until a button is pressed */
  216. }
  217. ------------------------------------------------------------------------------
  218.