home *** CD-ROM | disk | FTP | other *** search
/ Dream 48 / Amiga_Dream_48.iso / Atari / c / libs / gemfast / gemfut15.lzh / GEMUTIL.DOC < prev    next >
Text File  |  1990-06-29  |  28KB  |  558 lines
  1.  
  2. **************************************************************************
  3. *
  4. * GEMUTIL.DOC - Descriptions of the utility functions in GEMFAST.
  5. *
  6. *  05/26/90 - v1.4
  7. *             The rsc_gstrings()/rsc_sstrings() routines now support ICONs.
  8. *             The following functions are new with this release:
  9. *               frm_dsdial()
  10. *               obj_rbselect()
  11. *               obj_xtfind()
  12. *
  13. *  08/28/89 - v1.3
  14. *             Massive changes have been made to the utilty routines, and
  15. *             to this document.  Your best bet is to read the entire doc
  16. *             over again.
  17. *
  18. *             Most of the changes involve renaming routines to move toward
  19. *             a consistant naming standard (which is to pave the way for
  20. *             things planned for v2.0).  I've done my best to cover the
  21. *             name changes with #define statements in GEMFAST.H, so your
  22. *             existing code should work, but you should make every effort
  23. *             to convert existing and new code to the new names.  Sorry,
  24. *             I guess I wasn't thinking far enough ahead when I did the
  25. *             first release.
  26. *             
  27. *             For all the renamed routines, I've put the old name in
  28. *             the title bar of the new function's name.
  29. **************************************************************************
  30.  
  31. This document describes the functions in the AESUTxxx modules of the
  32. GEMFAST bindings.  These are not GEM function calls, and thus are not
  33. documented in standard GEM programming guides.
  34.  
  35. Within this document, the most changes will be indicated by a vertical bar 
  36. and the change level (|vX.X).
  37.  
  38. Definitions:
  39.  
  40. NO_OBJECT - A constant defined in GEMFAST.H; it has a value of -1.  This
  41.             value is used by most object-related utilties to indicate that
  42.             no object was found with the criteria specified in the search
  43.             (eg, for objc_find(), obj_rbfind(), etc).
  44.  
  45. GRECT     - A graphics-type rectangle of the form x,y,w,h.  A GRECT
  46.             describes a screen area by defining the x/y of the upper left
  47.             corner, and the width and height of the area.
  48.  
  49. VRECT     - A vdi-type rectangle of the form x1,y1,x2,y2.  A VRECT
  50.             describes a screen area by defining the upper left and lower
  51.             right corners of the area in x/y coordinates.
  52.  
  53. xRECT     - Used to indicate that either of the above types is accepted.
  54.  
  55. ;*************************************************************************
  56. ; Rectangle utilties.
  57. ;*************************************************************************
  58.  
  59. ;-------------------------------------------------------------------------
  60. ; rc_copy
  61. ;-------------------------------------------------------------------------
  62.  
  63. void rc_copy (xRECT *source, xRECT *dest)
  64.  
  65.         This function copies a rectangle.  It will copy either a GRECT or
  66.         VRECT type rectangle.  More generally, it will copy 2 longwords
  67.         from source to dest, they don't have to be rectangles at all.
  68.          >> NOTE BACKWARDS ORDER OF SOURCE & DEST.  Sorry, not my decision.
  69.  
  70. ;-------------------------------------------------------------------------
  71. ; rc_equal
  72. ;-------------------------------------------------------------------------
  73.  
  74. bool rc_equal(xRECT *rect1, xRECT *rect2)
  75.         
  76.         This function tests 2 rectangles for equality and returns TRUE/FALSE
  77.         (1/0) accordingly.  Works on GRECT or VRECT type rectangles, but
  78.         both rectangles must be of the same type.  More generally, this
  79.         function compare 2 sets of 2 contiguous longwords.
  80.  
  81. ;-------------------------------------------------------------------------
  82. ; rc_intersect
  83. ;-------------------------------------------------------------------------
  84.      
  85. bool rc_intersect(GRECT *rect1, GRECT *rect2)
  86.  
  87.         This function computes the intersection of 2 rectangles.  It works
  88.         only for GRECT type rectangles.  The intersection is the parts of 
  89.         two rectangles which overlap each other; this function is typically
  90.         used in processing the AES window-update rectangle list.  The result
  91.         is placed into 'rect2', overlaying the original data (again, not my
  92.         decision).  TRUE/FALSE is returned, depending on whether the 
  93.         rectangles had a common intersected area or not; the values in 
  94.         'rect2' are modified regardless of whether there was an intersection or not.
  95.         If the rectangle representing the intersecting area has a width or
  96.         height of zero, this routine will return TRUE.
  97.  
  98. ;-------------------------------------------------------------------------
  99. ; rc_union
  100. ;-------------------------------------------------------------------------
  101.  
  102. void rc_union(GRECT *rect1, GRECT *rect2)
  103.  
  104.         This function computes the union of two rectangles.  The union is 
  105.         the single rectangle that encompases all the area defined by the 
  106.         individual rectangles.  It works only for GRECT type rectangles.  
  107.         The result is placed into 'rect2'.
  108.  
  109. ;-------------------------------------------------------------------------
  110. ; rc_vtog
  111. ;-------------------------------------------------------------------------
  112.      
  113. void rc_vtog(VRECT *rect1, GRECT *rect2)
  114.  
  115.         This function converts a VRECT rectangle to a GRECT rectangle.
  116.         Do not specify the same rectangle for input and output.
  117.  
  118. ;-------------------------------------------------------------------------
  119. ; rc_gtov
  120. ;-------------------------------------------------------------------------
  121.         
  122. void rc_gtov(GRECT *rect1, VRECT *rect2)
  123.  
  124.         This function converts a GRECT rectangle to a VRECT rectangle.
  125.         Do not specify the same rectangle for input and output.
  126.  
  127. ;-------------------------------------------------------------------------
  128. ; rc_vadjust            (formerly objclv_adjust)
  129. ; rc_gadjust            (formerly objclg_adjust)
  130. ;-------------------------------------------------------------------------
  131.         
  132. void rc_vadjust(VRECT *rect, int h_adjust, int v_adjust);
  133. void rc_gadjust(GRECT *rect, int h_adjust, int v_adjust);
  134.  
  135.         These functions expand or contract a rectangle by a given amount
  136.         in each axis. A positive value exands the area, a negative
  137.         value contracts it.  You must use rc_gadjust for GRECTs and
  138.         rc_vadjust for VRECTs.  
  139.         
  140. |v1.3   Negative results are prevented by the adjust routines; zero will be 
  141. |       placed into any rectangle structure element which would have been 
  142. |       negative after the adjustment.
  143.         
  144. ;*************************************************************************
  145. ; Object utilities.
  146. ;*************************************************************************
  147.  
  148. ;-------------------------------------------------------------------------
  149. ; obj_flchange          (formerly objfl_change)
  150. ;-------------------------------------------------------------------------
  151.  
  152. void obj_flchange(OBJECT *tree, int object, int flagsmask, int updateflag);
  153.  
  154.         This function sets or resets bits in an object's ob_flags field.
  155.         Depending on the setting of 'updateflag' the object is updated 
  156.         on the screen or not. (Update is done via objc_draw internally).
  157.         If the high bit of 'flagsmask' is set, the flags bits are reset,
  158.         otherwise they are set.  This allows the following syntax:
  159.            objfl_change(mytree, myobj,  HIDETREE, TRUE);
  160.            objfl_change(mytree, myobj, ~HIDETREE, FALSE);
  161.         The first case will set 'myobj' to hidden and will erase it from
  162.         the screen.  The second case will set 'myobj' to visible, but does
  163.         not update the screen.
  164.         
  165.         Note that you CAN use this function to hide and unhide trees
  166.         visibly on the screen.  When the objc_draw is called internally
  167.         by this function, the draw starts at the root of the tree, but is
  168.         clipped by the x/y/w/h of the object who's state is being changed.
  169.         This means that a flag change to HIDETREE with update will draw
  170.         the parents of the hidden object, effectively erasing it on the
  171.         screen.  The same holds true for setting an object to ~HIDETREE;
  172.         the object will be redrawn and become visible.
  173.  
  174. |v1.4   Be aware that the xywh sizes of the changed object are used in the 
  175. |       internal objc_draw() when redraw is requested.  For window-oriented
  176. |       programs, where some of the object tree might be outside a window's
  177. |       work area, it is best for the calling program to request no redraw,
  178. |       and then to handle the redraw itself, specifying the window's work
  179. |       area as a clipping rectangle.  (This is not new for v1.4, it just
  180. |       hasn't been documented as such before.)
  181.         
  182. ;-------------------------------------------------------------------------
  183. ; obj_stchange          (formerly objst_change)
  184. ;-------------------------------------------------------------------------
  185.  
  186. void obj_stchange(OBJECT *tree, int object, int statemask, int updateflag);
  187.  
  188.         This function sets or resets bits in an object's ob_state field.
  189.         Depending on the setting of 'updateflag' the object is updated 
  190.         on the screen or not. (Update is done via objc_draw internally).
  191.         If the high bit of 'statemask' is set, the state bits are reset,
  192.         otherwise they are set.  This allows the following syntax:
  193.            objst_change(mytree, myobj,  SELECTED, TRUE);
  194.            objst_change(mytree, myobj, ~SELECTED, FALSE);
  195.         The first case will set 'myobj' to SELECTED and show it that way
  196.         on the screen.  The second case will set 'myobj' to non-selected,
  197.         and will not update the screen.
  198.  
  199. |v1.4   Be aware that the xywh sizes of the root object are used in the 
  200. |       internal objc_draw() when redraw is requested.  For window-oriented
  201. |       programs, where some of the object tree might be outside a window's
  202. |       work area, it is best for the calling program to request no redraw,
  203. |       and then to handle the redraw itself, specifying the window's work
  204. |       area as a clipping rectangle.  (This is not new for v1.4, it just
  205. |       hasn't been documented as such before.)
  206.         
  207. ;-------------------------------------------------------------------------
  208. ; obj_xywh              (formerly objc_xywh)
  209. ;-------------------------------------------------------------------------
  210.  
  211. void obj_xywh(OBJECT *tree, int object, GRECT *rect);
  212.  
  213.         Returns an object's x/y/w/h values into a GRECT rectangle.  Note
  214.         that the x/y values are NOT automatically adjusted to screen 
  215.         coordinates, they are copied directly from the object tree 
  216.         structure.  (Thus, if the object index is 0 (R_TREE) the rectangle 
  217.         will reflect screen coordinates, for any child object it will not.)
  218.  
  219. ;-------------------------------------------------------------------------
  220. ; obj_offxywh
  221. ;-------------------------------------------------------------------------
  222.  
  223. void obj_offxywh( OBJECT *tree, int object, GRECT *rect);
  224.  
  225.         Returns any object's screen-adjusted x/y/w/h values into a GRECT 
  226.         rectangle.  This is a shortcut to calling objc_offset() then
  227.         copying the object's w/h data into the GRECT structure.
  228.  
  229. ;-------------------------------------------------------------------------
  230. ; objcl_calc            (THIS ROUTINE IS BEING PHASED OUT!)
  231. ;-------------------------------------------------------------------------
  232.  
  233. void objcl_calc(OBJECT *tree, int object, {GRECT *r1|NULL}, {VRECT *r2|NULL});
  234.  
  235. |v1.3   THIS ROUTINE IS BEING PHASED OUT, DO NOT RELY ON IT!  It will be
  236. |       rewritten someday, but will have a new name (obj_clipcalc).
  237.  
  238.         This routine does clipping calculations for an object. It calculates
  239.         both GRECT and VRECT clipping rectangle simulataneously; if you
  240.         specify a null pointer for one of the rectangle types those values
  241.         won't be returned.  This function will handle OUTLINED and SHADOWED
  242.         objects, and will return the proper clipping rectangle to be passed
  243.         to objc_draw() or vs_clip().  Typical usage might be:
  244.          To redraw an object after changing ob_state or ob_flags...
  245.             objcl_calc(mytree, refreshobj, &cliprect, 0L);
  246.             objc_draw(mytree, refreshobj, MAX_DEPTH, cliprect);
  247.          To outline an object with a VDI rounded rectangle...  
  248.             objcl_calc(mytree, refreshobj, 0L, &boxrect);
  249.             v_rbox(vdi_handle, &boxrect);
  250.  
  251. ;-------------------------------------------------------------------------
  252. ; obj_rbfind            (formerly objxrb_which)
  253. ;-------------------------------------------------------------------------
  254.  
  255. int  obj_rbfind(OBJECT *tree, int parentobj, int state);
  256.  
  257.         This function returns the index of the first child object of the
  258.         specified parent which is in the desired state, or -1 if no child
  259.         objects are in that state.  Note that the state test is done via
  260.         bit-wise AND. As an example, it is possible to find an object which is
  261.         either SELECTED *OR* CROSSED, but it is not possible to limit the
  262.         search to only for objects which are *both* SELECTED *AND* CROSSED.
  263.  
  264. ;-------------------------------------------------------------------------
  265. ; objrb_which           (old name, which will be dropped eventualy)
  266. ; obj_rbwhich           (old name, which will be dropped eventualy)
  267. ;-------------------------------------------------------------------------
  268.  
  269. int  objrb_which(OBJECT *tree, int parentobj);
  270.  
  271.         This function returns the index of the first child object of the
  272.         specified parent which has the SELECTED bit set, or -1 if no child
  273.         objects are selected.  It is most useful in determining which 
  274. |v1.3   radio button in a group has been selected.  This function is
  275. |       supported via a #define in the GEMFAST.H file, and actually 
  276. |       generates a call to obj_rbfind(), passing a state of SELECTED.
  277. |
  278. |       This function is being phased out, it is recommended that you use
  279. |       obj_rbfind(tree, parent, SELECTED) to perform this function.
  280.  
  281. ;-------------------------------------------------------------------------
  282. ; obj_rbselect
  283. ;-------------------------------------------------------------------------
  284.  
  285. int  obj_rbselect(OBJECT *tree, int object, int state);
  286.  
  287.         This function logically de-selects the current object in a group
  288.         of radio buttons and selects the specified object.  The return 
  289.         value is the index of the object that was selected before the
  290.         function was called.  Rules for the 'state' value are as described
  291.         under the obj_rbfind function.
  292.         
  293.         This function can handle the situation where there is no object in
  294.         the radio button group which is currently selected; the new object
  295.         is set to the specified state.  This function *assumes* that the
  296.         new object is a radio button type object, and that all other objects
  297.         in the new object's parent are also radio button type objects.
  298.         This does not have to be the case, but the routine can break down
  299.         under extreme conditions (eg, don't try to specify the root as the
  300.         new object.)
  301.  
  302.         Note that this function DOES NOT REDRAW either of the objects
  303.         which are changed, it only changes the ob_state values in the
  304.         object array.  This function is primarily designed to pre-set
  305.         radio buttons to a known state before calling a dialog handler.
  306.         If redraw is needed as well, use a sequence such as:
  307.         
  308.             oldobj = obj_rbselect(ptree, newobj, SELECTED);
  309.             if (oldobj > R_TREE)       
  310.                 objc_draw(ptree, oldobj, MAX_DEPTH, cliprect);
  311.             objc_draw(ptree, newobj, MAX_DEPTH, cliprect);
  312.  
  313.         Alternatively, a single objc_draw() can be used, specifying the
  314.         parent of the radio button group.  (This works fine for small 
  315.         groups of radio buttons, but the speed of redraw can be a factor
  316.         for a large group of buttons.)
  317.         
  318. |v1.4   This function is new with this version.
  319.  
  320. ;-------------------------------------------------------------------------
  321. ; obj_parent
  322. ;-------------------------------------------------------------------------
  323.  
  324. int  obj_parent(OBJECT *tree, int curentobj);
  325.  
  326.         This function returns the index of the parent object of the
  327.         specified object.  By definition, the root object in a tree has
  328.         no parent, 0 will be returned (as if the root were its own parent).
  329.         This function is useful for things like building your own radio
  330.         button handler using evnt_multi().
  331.  
  332. ;-------------------------------------------------------------------------
  333. ; obj_xtfind
  334. ;-------------------------------------------------------------------------
  335.  
  336. int  obj_xtfind(OBJECT *tree, int parent, int xtype);
  337.  
  338.         This function returns the index of the child object within 'parent'
  339.         which has the specified extended object type.  The extended object
  340.         type is encoded within the high byte of the ob_type field, and is
  341.         useful for categorizing objects by function, or for connecting
  342.         objects to array elements by using the extended type as an index.
  343.         If no object with the given type is found, NO_OBJECT is returned.
  344.         
  345. |v1.4   This function is new with this release.  It is the functional 
  346. |       equivelent of the old find_exttype() routine from the 'canned
  347. |       source' library.
  348.  
  349. ;*************************************************************************
  350. ; Resource utilties.
  351. ;*************************************************************************
  352.  
  353. ;-------------------------------------------------------------------------
  354. ; rsc_sstrings
  355. ;-------------------------------------------------------------------------
  356.  
  357. void rsc_sstrings(OBJECT *tree, 
  358.                     int obj1,char *ptr1,
  359.                     [obj2,ptr2, ... objn,ptrn,]
  360.                     -1);
  361.                  
  362.         This function sets one or more string pointers within an object
  363.         tree.  It understands the difference between STRING, BUTTON, and
  364.         TEXT object types, and sets the appropriate pointer fields (ob_spec
  365.         or te_ptext).  Any number of object/pointer pairs may be specified,
  366.         the list is terminated by a negative object number.  The purpose
  367.         of this function is to replace all the lines of code looking like...
  368.             *((TEDINFO *)(tree[object].ob_spec))->te_ptext = pointer;
  369.         with the simpler construct...
  370.             rsc_strings(tree, str1obj,pstr1, 
  371.                               txt1obj,ptxt1, 
  372.                               /* etc */ 
  373.                               -1);
  374.  
  375. |v1.3   This routine understands objects with the INDIRECT flag set, and 
  376. |       will use the ob_spec field as an indirect pointer if appropriate.
  377. |v1.4   This routine now handles ICON objects.
  378.  
  379. ;-------------------------------------------------------------------------
  380. ; rsc_gstrings
  381. ;-------------------------------------------------------------------------
  382.  
  383. void rsc_gstrings(OBJECT *tree, 
  384.                     int obj1,char **ptr1,
  385.                     [obj2,**ptr2, ... objn,**ptrn,]
  386.                     -1);
  387.                  
  388.         This function gets one or more string pointers from within an object
  389.         tree.  It understands the difference between TEXT/nonTEXT object
  390.         types, and gets the appropriate fields (ob_spec or te_ptext). 
  391.         Any number of object/pointer pairs may be specified, the list is
  392.         terminated by a negative object number.  This is a provided as a 
  393.         shortcut to doing a long series of rsrc_gaddr() calls to get the
  394.         string/text pointers from a tree.  Note that this function is not
  395.         as flexible as rsrc_gaddr()...if the object type is one of the
  396.         text objects, it will return a te_ptext pointer, otherwise the
  397.         ob_spec value is returned.  When used with strings/text, the 
  398.         ob_spec field will be a string pointer.
  399.  
  400.           example() {
  401.           char *string1;
  402.           char *text2;
  403.                     
  404.           rsrc_gaddr(R_TREE, MYTREE, &mytree);
  405.           rsc_gstrings(mytree, MYSTR1,&string1,
  406.                                MYTXT2,&text2,
  407.                                -1);
  408.           }
  409.  
  410. |v1.3   This routine understands objects with the INDIRECT flag set, and 
  411. |       will use the ob_spec field as an indirect pointer if appropriate.
  412. |       Unlike previous releases, this routine has now been tested.
  413. |v1.4   This routine now understands ICON objects.
  414.         
  415. ;-------------------------------------------------------------------------
  416. ; rsc_treefix
  417. ;-------------------------------------------------------------------------
  418.           
  419. void rsc_treefix(OBJECT *tree);
  420.         
  421.         This function performs an rsrc_obfix() call for all objects in
  422.         a tree.  It's handy when using resource trees imbedded as source
  423.         code within your program, which require manual x/y fixup.  
  424.         
  425.         NOTE:  This functions uses the LASTOB bit in ob_flags to determine
  426.         when it has hit the end of the tree.  When coding your resource
  427.         tree, please be careful to set the LASTOB bit in the last object 
  428.         in the array.  Note that this is NOT a routine to provide a full
  429.         fixup of .RSH-type code emmitted by a resource construction editor;
  430.         this routine does only x/y/w/h fixup on a single tree, and does 
  431. |v1.4   not resolve cross-structure pointers.  (The C source code files
  432. |       RSHFIXUP.C and RS2FIXUP.C will provide the full runtime support for
  433. |       embedded resource files.  These are distributed separately from
  434. |       the GEMFAST package.)
  435.  
  436. ;*************************************************************************
  437. ;* Forms utilities.
  438. ;*************************************************************************
  439.  
  440. ;-------------------------------------------------------------------------
  441. ; frm_dsdial
  442. ;-------------------------------------------------------------------------
  443.  
  444. int  frm_dsdial(char *pstrings[], char *pbuttons[], int graphicsflag);
  445.                  
  446.         This function dynamically builds a dialog box around some
  447.         boilerplate text and displays it.  It is particularly useful for
  448.         displaying help screens, or for explaining a situation to the
  449.         user and providing a list of up to 5 choices/actions to be selected
  450.         via buttons (like a mega-sized alert box).
  451.         
  452.         The dialog box will be dynamically sized to hold as many as 20 lines
  453.         of text, and will adjust itself to the widest text line.  Up to 5
  454.         buttons may be specified, and the buttons will be centered at the
  455.         bottom of the dialog box.  The rightmost button (the last one 
  456.         specified) will always be the DEFAULT button.  It is the caller's
  457.         responsibility to insure that the widest text line (or the combined
  458.         length of the buttons) doesn't cause the dialog box to be wider 
  459.         than the current screen.  (EG, no auto-word-wrap here!)
  460.         
  461.         The routine returns the index of the button used to exit (first
  462.         button == 0, etc).
  463.         
  464.         To specify the text lines and buttons, the caller passes pointers
  465.         to arrays of pointers to strings.  (This is not as complex as it
  466.         sounds, see the example below.)  A pointer to a NULL string (not
  467.         a NULL pointer!) terminates the lists of text and buttons.
  468.         
  469.         The caller also passes a TRUE/FALSE value for 'graphicsflag', to 
  470.         indicate whether FMD_GROW and FMD_SHRINK graphics should be done 
  471.         as part of the dialog processing.
  472.  
  473.         The following example shows setting up and calling this routine:
  474.         
  475.         char    *help1_screen[] = {
  476.             "            Help Screen 1",   /* title line, hand-centered */
  477.             "This is the first in a series of",
  478.             "help screens which tell you basically",
  479.             "nothing of true interest.  If you are",
  480.             "foolish enough to select the 'NEXT'",
  481.             "button, below, you will see even more",
  482.             "screens full of worthless information."
  483.             " ",                    /* 1 blank line between text & buttons */
  484.             ""};                    /* NULL string terminates the list     */
  485.             
  486.         char    help1_buttons[] = {
  487.             "NEXT",
  488.             "DONE", 
  489.             """};                   /* NULL string terminates the list     */
  490.         int     btn;
  491.         
  492.         btn = frm_dsdial(help1_screen, help1_buttons, TRUE);
  493.         if (btn == 0) {
  494.             /* show second help screen */
  495.         } 
  496.  
  497.         While this routine can be incredibly useful in handling help text,
  498.         it should be noted that it is rather large.  After linking, it will
  499.         add about 1.5k to the size of your application (making it the largest
  500.         entity in the GEMFAST system).  
  501.  
  502. |v1.4   This routine is new with this release.
  503.  
  504. ;*************************************************************************
  505. ; Graphics Utilities.
  506. ;  These utilties are NOT available in C source code form, as they use
  507. ;  the Line-A TOS interface, which must be accessed via assembler code.
  508. ;*************************************************************************
  509.  
  510. ;-------------------------------------------------------------------------
  511. ; gra_qonmouse          (formerly graqon_mouse)
  512. ; gra_qofmouse          (formerly graqof_mouse)
  513. ;-------------------------------------------------------------------------
  514.  
  515. void graqon_mouse();
  516. void graqof_mouse();
  517.  
  518.         These routines turn the mouse pointer on and off quickly (using
  519.         the Line-A HideMouse/ShowMouse routines).  They will execute much
  520.         faster than the equivelant graf_mouse() calls, and they behave
  521. |v1.3   in a similar manner.  Specifically, the graf_mouse() calls track 
  522. |       the number of Hide/Show calls and if you 'hide' the mouse 3 times, 
  523. |       you must use the 'show' call 3 times before the mouse reappears.  
  524. |       These routines will behave in the same way (as of v1.3).  
  525.  
  526. ;-------------------------------------------------------------------------
  527. ; gra_qmstate           (formerly graq_mstate)
  528. ;-------------------------------------------------------------------------
  529.  
  530. graq_mstate(int *mousex, int *mousey, int *mousebtns);
  531.  
  532.         This routine returns the mouse x/y location and button state
  533.         quickly, using the Line-A variable structure as the source of 
  534.         information.  It is much faster than the graf_mkstate() call, and
  535.         it does not return the keyboard state information.  If you have
  536.         an application full of graf_mkstate() calls that don't use the
  537.         keystate info, you can code 
  538.           #define graf_mkstate(a,b,c,d) graq_mstate((a),(b),(c))
  539.         at the top of your program and instantly convert to the faster
  540.         routine.  (Caveat:  This routine is NOT well-tested in v1.0).
  541.         
  542. |v1.3   (NOTE:  I've had problems with using this routine in conjunction
  543. |       with evnt_mouse and evnt_multi type calls.  It seems that if you
  544. |       use the AES graf_mkstate() call it will (maybe?) clear some flag
  545. |       indicating a mouse-related event is pending.  When you use this
  546. |       Line-A routine, the event is left pending, and the next evnt_????
  547. |       call doesn't work as you'd expect.  I know, I know, I'm not being
  548. |       very clear; that's only because I haven't looked into it too 
  549. |       closely.  All I can say for sure is that some well-tested code
  550. |       broke when I #defined graf_mkstate to invoke this routine, and when
  551. |       I put it back, the code started working again.  Other code, however
  552. |       works just fine with graf_mkstate #define'd to this routine.- Ian)
  553.  
  554. ;*************************************************************************
  555. ;* End of doc.
  556. ;*************************************************************************
  557.  
  558.