home *** CD-ROM | disk | FTP | other *** search
************************************************************************** * * GEMUTIL.DOC - Descriptions of the utility functions in GEMFAST. * * 05/26/90 - v1.4 * The rsc_gstrings()/rsc_sstrings() routines now support ICONs. * The following functions are new with this release: * frm_dsdial() * obj_rbselect() * obj_xtfind() * * 08/28/89 - v1.3 * Massive changes have been made to the utilty routines, and * to this document. Your best bet is to read the entire doc * over again. * * Most of the changes involve renaming routines to move toward * a consistant naming standard (which is to pave the way for * things planned for v2.0). I've done my best to cover the * name changes with #define statements in GEMFAST.H, so your * existing code should work, but you should make every effort * to convert existing and new code to the new names. Sorry, * I guess I wasn't thinking far enough ahead when I did the * first release. * * For all the renamed routines, I've put the old name in * the title bar of the new function's name. ************************************************************************** This document describes the functions in the AESUTxxx modules of the GEMFAST bindings. These are not GEM function calls, and thus are not documented in standard GEM programming guides. Within this document, the most changes will be indicated by a vertical bar and the change level (|vX.X). Definitions: NO_OBJECT - A constant defined in GEMFAST.H; it has a value of -1. This value is used by most object-related utilties to indicate that no object was found with the criteria specified in the search (eg, for objc_find(), obj_rbfind(), etc). GRECT - A graphics-type rectangle of the form x,y,w,h. A GRECT describes a screen area by defining the x/y of the upper left corner, and the width and height of the area. VRECT - A vdi-type rectangle of the form x1,y1,x2,y2. A VRECT describes a screen area by defining the upper left and lower right corners of the area in x/y coordinates. xRECT - Used to indicate that either of the above types is accepted. ;************************************************************************* ; Rectangle utilties. ;************************************************************************* ;------------------------------------------------------------------------- ; rc_copy ;------------------------------------------------------------------------- void rc_copy (xRECT *source, xRECT *dest) This function copies a rectangle. It will copy either a GRECT or VRECT type rectangle. More generally, it will copy 2 longwords from source to dest, they don't have to be rectangles at all. >> NOTE BACKWARDS ORDER OF SOURCE & DEST. Sorry, not my decision. ;------------------------------------------------------------------------- ; rc_equal ;------------------------------------------------------------------------- bool rc_equal(xRECT *rect1, xRECT *rect2) This function tests 2 rectangles for equality and returns TRUE/FALSE (1/0) accordingly. Works on GRECT or VRECT type rectangles, but both rectangles must be of the same type. More generally, this function compare 2 sets of 2 contiguous longwords. ;------------------------------------------------------------------------- ; rc_intersect ;------------------------------------------------------------------------- bool rc_intersect(GRECT *rect1, GRECT *rect2) This function computes the intersection of 2 rectangles. It works only for GRECT type rectangles. The intersection is the parts of two rectangles which overlap each other; this function is typically used in processing the AES window-update rectangle list. The result is placed into 'rect2', overlaying the original data (again, not my decision). TRUE/FALSE is returned, depending on whether the rectangles had a common intersected area or not; the values in 'rect2' are modified regardless of whether there was an intersection or not. If the rectangle representing the intersecting area has a width or height of zero, this routine will return TRUE. ;------------------------------------------------------------------------- ; rc_union ;------------------------------------------------------------------------- void rc_union(GRECT *rect1, GRECT *rect2) This function computes the union of two rectangles. The union is the single rectangle that encompases all the area defined by the individual rectangles. It works only for GRECT type rectangles. The result is placed into 'rect2'. ;------------------------------------------------------------------------- ; rc_vtog ;------------------------------------------------------------------------- void rc_vtog(VRECT *rect1, GRECT *rect2) This function converts a VRECT rectangle to a GRECT rectangle. Do not specify the same rectangle for input and output. ;------------------------------------------------------------------------- ; rc_gtov ;------------------------------------------------------------------------- void rc_gtov(GRECT *rect1, VRECT *rect2) This function converts a GRECT rectangle to a VRECT rectangle. Do not specify the same rectangle for input and output. ;------------------------------------------------------------------------- ; rc_vadjust (formerly objclv_adjust) ; rc_gadjust (formerly objclg_adjust) ;------------------------------------------------------------------------- void rc_vadjust(VRECT *rect, int h_adjust, int v_adjust); void rc_gadjust(GRECT *rect, int h_adjust, int v_adjust); These functions expand or contract a rectangle by a given amount in each axis. A positive value exands the area, a negative value contracts it. You must use rc_gadjust for GRECTs and rc_vadjust for VRECTs. |v1.3 Negative results are prevented by the adjust routines; zero will be | placed into any rectangle structure element which would have been | negative after the adjustment. ;************************************************************************* ; Object utilities. ;************************************************************************* ;------------------------------------------------------------------------- ; obj_flchange (formerly objfl_change) ;------------------------------------------------------------------------- void obj_flchange(OBJECT *tree, int object, int flagsmask, int updateflag); This function sets or resets bits in an object's ob_flags field. Depending on the setting of 'updateflag' the object is updated on the screen or not. (Update is done via objc_draw internally). If the high bit of 'flagsmask' is set, the flags bits are reset, otherwise they are set. This allows the following syntax: objfl_change(mytree, myobj, HIDETREE, TRUE); objfl_change(mytree, myobj, ~HIDETREE, FALSE); The first case will set 'myobj' to hidden and will erase it from the screen. The second case will set 'myobj' to visible, but does not update the screen. Note that you CAN use this function to hide and unhide trees visibly on the screen. When the objc_draw is called internally by this function, the draw starts at the root of the tree, but is clipped by the x/y/w/h of the object who's state is being changed. This means that a flag change to HIDETREE with update will draw the parents of the hidden object, effectively erasing it on the screen. The same holds true for setting an object to ~HIDETREE; the object will be redrawn and become visible. |v1.4 Be aware that the xywh sizes of the changed object are used in the | internal objc_draw() when redraw is requested. For window-oriented | programs, where some of the object tree might be outside a window's | work area, it is best for the calling program to request no redraw, | and then to handle the redraw itself, specifying the window's work | area as a clipping rectangle. (This is not new for v1.4, it just | hasn't been documented as such before.) ;--------- @FûÉ #KH⓪①Ññ✓✓פפ⇦⇦ii⇩⇩4œœœœœœœœœœœœœœœœœœœœœœœœœœœœœœœœœœœœœœœœœ4(∮ü©ë⌐}לעìíਥöÇÇÇÇÇÇÇÇÇÇíÖ©חŒÉ②╱ > 2⇩⓪╱ 08⇩ ! IJב⇧⇧⇧⇧⇧⇧⇧⇧⇧⇧⇧⇧⇧⇧⇧⇧⇧⇧⇧⇧⇧⇧⇧⇧⇧⇧⇧⇧⇧⇧⇧⇧⇧⇧⇧⇧⇧⇧⇧⇧⇧⇧⇧⇧⇧⇧⇧⇧⇧⇧⇧⇧⇧⇧⇧⇧⇧⇧⇧⇧⇧⇧⇧⇧⇧⇧⇧⇧⇧⇧⇧⇧⇧⇧IJבIJא⇩ ✓'> 2⇩ ⓪╱08⇩ !@rB`p◆?⇩╱② !◆>✓⇩◆> 2⇩ 0◆◆>✓⇩◆>⓪╱8╱ 8⓪⇧◆>✓⇩◆> &8╱ "╱8! ⇧IJבIJב???????>╱✓╱@כΩץהΦפ∧ץ@µטΦµ@∧Σ@ΣטµטΦµ@גפΦµ@פץ@אץ@∧גקטהΦNµ@e to the new names. Sorry, * I guess I wasn't thinking far enough ahead when I did the * first release. * * For all the renamed routines, I've put the old name in * the title bar of the new function's name. ************************************************************************** This document describes the functions in the AESUTxxx modules of the GEMFAST bindings. These are not GEM function calls, and thus are not documented in standard GEM programming guides. Within this document, the most changes will be indicated by a vertical bar and the change level (|vX.X). Definitions: NO_OBJECT - A constant defined in GEMFAST.H; it has a value of -1. This value is used by most object-related utilties to indicate that no object was found with the criteria specified in the search (eg, for objc_find(), obj_rbfind(), etc). GRECT - A graphics-type rectangle of the form x,y,w,h. A GRECT describes a screen area by defining the x/y of the upper left corner, and the width and height of the area. VRECT - A vdi-type rectangle of the form x1,y1,x2,y2. A VRECT describes a screen area by defining the upper left and lower right corners of the area in x/y coordinates. xRECT - Used to indicate that either of the above types is accepted. ;************************************************************************* ; Rectangle utilties. ;************************************************************************* ;------------------------------------------------------------------------- ; rc_copy ;------------------------------------------------------------------------- void rc_copy (xRECT *source, xRECT *dest) This function copies a rectangle. It will copy either a GRECT or VRECT type rectangle. More generally, it will copy 2 longwords from source to dest, they don't have to be rectangles at all. >> NOTE BACKWARDS ORDER OF SOURCE & DEST. Sorry, not my decision. ;------------------------------------------------------------------------- ; rc_equal ;------------------------------------------------------------------------- bool rc_equal(xRECT *rect1, xRECT *rect2) This function tests 2 rectangles for equality and returns TRUE/FALSE (1/0) accordingly. Works on GRECT or VRECT type rectangles, but both rectangles must be of the same type. More generally, this function compare 2 sets of 2 contiguous longwords. ;------------------------------------------------------------------------- ; rc_intersect ;------------------------------------------------------------------------- bool rc_intersect(GRECT *rect1, GRECT *rect2) This function computes the intersection of 2 rectangles. It works only for GRECT type rectangles. The intersection is the parts of two rectangles which overlap each other; this function is typically used in processing the AES window-update rectangle list. The result is placed into 'rect2', overlaying the original data (again, not my decision). TRUE/FALSE is returned, depending on whether the rectangles had a common intersected area or not; the values in 'rect2' are modified regardless of whether there was an intersection or not. If the rectangle representing the intersecting area has a width or height of zero, this routine will return TRUE. ;------------------------------------------------------------------------- ; rc_union ;------------------------------------------------------------------------- void rc_union(GRECT *rect1, GRECT *rect2) This function computes the union of two rectangles. The union is the single rectangle that encompases all the area defined by the individual rectangles. It works only for GRECT type rectangles. The result is placed into 'rect2'. ;------------------------------------------------------------------------- ; rc_vtog ;------------------------------------------------------------------------- void rc_vtog(VRECT *rect1, GRECT *rect2) This function converts a VRECT rectangle to a GRECT rectangle. Do not specify the same rectangle for input and output. ;------------------------------------------------------------------------- ; rc_gtov ;------------------------------------------------------------------------- void rc_gtov(GRECT *rect1, VRECT *rect2) This function converts a GRECT rectangle to a VRECT rectangle. Do not specify the same rectangle for input and output. ;------------------------------------------------------------------------- ; rc_vadjust (formerly objclv_adjust) ; rc_gadjust (formerly objclg_adjust) ;------------------------------------------------------------------------- void rc_vadjust(VRECT *rect, int h_adjust, int v_adjust); void rc_gadjust(GRECT *rect, int h_adjust, int v_adjust); These functions expand or contract a rectangle by a given amount in each axis. A positive value exands the area, a negative value contracts it. You must use rc_gadjust for GRECTs and rc_vadjust for VRECTs. |v1.3 Negative results are prevented by the adjust routines; zero will be | placed into any rectangle structure element which would have been | negative after the adjustment. ;************************************************************************* ; Object utilities. ;************************************************************************* ;------------------------------------------------------------------------- ; obj_flchange (formerly objfl_change) ;------------------------------------------------------------------------- void obj_flchange(OBJECT *tree, int object, int flagsmask, int updateflag); This function sets or resets bits in an object's ob_flags field. Depending on the setting of 'updateflag' the object is updated on the screen or not. (Update is done via objc_draw internally). If the high bit of 'flagsmask' is set, the flags bits are reset, otherwise they are set. This allows the following syntax: objfl_change(mytree, myobj, HIDETREE, TRUE); objfl_change(mytree, myobj, ~HIDETREE, FALSE); The first case will set 'myobj' to hidden and will erase it from the screen. The second case will set 'myobj' to visible, but does not update the screen. Note that you CAN use this function to hide and unhide trees visibly on the screen. When the objc_draw is called internally by this function, the draw starts at the root of the tree, but is clipped by the x/y/w/h of the object who's state is being changed. This means that a flag change to HIDETREE with update will draw the parents of the hidden objec----------------------------- ; obj_parent ;------------------------------------------------------------------------- int obj_parent(OBJECT *tree, int curentobj); This function returns the index of the parent object of the specified object. By definition, the root object in a tree has no parent, 0 will be returned (as if the root were its own parent). This function is useful for things like building your own radio button handler using evnt_multi(). ;------------------------------------------------------------------------- ; obj_xtfind ;------------------------------------------------------------------------- int obj_xtfind(OBJECT *tree, int parent, int xtype); This function returns the index of the child object within 'parent' which has the specified extended object type. The extended object type is encoded within the high byte of the ob_type field, and is useful for categorizing objects by function, or for connecting objects to array elements by using the extended type as an index. If no object with the given type is found, NO_OBJECT is returned. |v1.4 This function is new with this release. It is the functional | equivelent of the old find_exttype() routine from the 'canned | source' library. ;************************************************************************* ; Resource utilties. ;************************************************************************* ;-------------------------------- @FûÉ #KH⓪①Ññ✓✓פפפפפפפפפפפפפפפפפפפפפפפפפפססúØ◆'65≈77G&ûµw0סúØפפפפפפפפפפפפפפפפפפפפפפפפפפפפפפפפפפפפפפפפפפפפפפפפפפפפפפפפפפפפפפפפפפפפפפפפססáסºf÷ûB◆'65≈77G&ûµw2ä⌠$ñT5B⇩ºG&VRא סó⇩⇩⇩⇩⇩⇩⇩⇩⇩⇩⇩⇩⇩⇩⇩⇩⇩⇩⇩╱ûτB╱÷&ú②ה6å⑦"⇩º◆G#②ijסó⇩⇩⇩⇩⇩⇩⇩⇩⇩⇩⇩⇩⇩⇩⇩⇩⇩⇩⇩❎À÷&ú"ו◆G#"א⇩ΓΓΓ╱÷&ªΓו◆G&Γדססó⇩⇩⇩⇩⇩⇩⇩⇩⇩⇩⇩⇩⇩⇩⇩⇩⇩⇩⇩⇩צ②ôãסó⇩⇩⇩⇩⇩⇩⇩⇩⇩⇩⇩⇩⇩⇩⇩⇩ סó⇩⇩⇩⇩⇩⇩⇩❎Fåù2╱gVµ7Fû÷Γ◆6WG2╱÷µR╱≈"╱ש≈&R◆7G&ûµr◆╱÷ûτFW'2◆vùFåûΓ╱⑥Γ╱÷&ªV7@סó⇩⇩⇩⇩⇩⇩⇩◆G&VRΓ⇩⇦ùB◆VµFW'7F⑥µG2◆FåR╱FûffW&Vµ6R╱&WGvVVΓ❎5E$öΣrא⇦%UED⌠Γא╱⑥µ@סó⇩⇩⇩⇩⇩⇩⇩❎DUàB╱÷&ªV7 describes a screen area by defining the x/y of the upper left corner, and the width and height of the area. VRECT - A vdi-type rectangle of the form x1,y1,x2,y2. A VRECT describes a screen area by defining the upper left and lower right corners of the area in x/y coordinates. xRECT - Used to indicate that either of the above types is accepted. ;************************************************************************* ; Rectangle utilties. ;************************************************************************* ;------------------------------------------------------------------------- ; rc_copy ;------------------------------------------------------------------------- void rc_copy (xRECT *source, xRECT *dest) This function copies a rectangle. It will copy either a GRECT or VRECT type rectangle. More generally, it will copy 2 longwords from source to dest, they don't have to be rectangles at all. >> NOTE BACKWARDS ORDER OF SOURCE & DEST. Sorry, not my decision. ;------------------------------------------------------------------------- ; rc_equal ;------------------------------------------------------------------------- bool rc_equal(xRECT *rect1, xRECT *rect2) This function tests 2 rectangles for equality and returns TRUE/FALSE (1/0) accordingly. Works on GRECT or VRECT type rectangles, but both rectangles must be of the same type. More generally, this function compare 2 sets of 2 contiguous longwords. ;------------------------------------------------------------------------- ; rc_intersect ;------------------------------------------------------------------------- bool rc_intersect(GRECT *rect1, GRECT *rect2) This function computes the intersection of 2 rectangles. It works only for GRECT type rectangles. The intersection is the parts of two rectangles which overlap each other; this function is typically used in processing the AES window-update rectangle list. The result is placed into 'rect2', overlaying the original data (again, not my decision). TRUE/FALSE is returned, depending on whether the rectangles had a common intersected area or not; the values in 'rect2' are modified regardless of whether there was an intersection or not. If the rectangle representing the intersecting area has a width or height of zero, this routine will return TRUE. ;------------------------------------------------------------------------- ; rc_union ;------------------------------------------------------------------------- void rc_union(GRECT *rect1, GRECT *rect2) This function computes the union of two rectangles. The union is the single rectangle that encompases all the area defined by the individual rectangles. It works only for GRECT type rectangles. The result is placed into 'rect2'. ;------------------------------------------------------------------------- ; rc_vtog ;------------------------------------------------------------------------- void rc_vtog(VRECT *rect1, GRECT *rect2) This function converts a VRECT rectangle to a GRECT rectangle. Do not specify the same rectangle for input and output. ;------------------------------------------------------------------------- ; rc_gtov ;------------------------------------------------------------------------- void rc_gtov(GRECT *rect1, VRECT *rect2) This function converts a GRECT rectangle to a VRECT rectangle. Do not specify the same rectangle for input and output. ;------------------------------------------------------------------------- ; rc_vadjust (formerly objclv_adjust) ; rc_gadjust (formerly objclg_adjust) ;------------------------------------------------------------------------- void rc_vadjust(VRECT *rect, int h_adjust, int v_adjust); void rc_gadjust(GRECT *rect, int h_adjust, int v_adjust); These functions expand or contract a rectangle by a given amount in each axis. A positive value exands the area, a negative value contracts it. You must use rc_gadjust for GRECTs and rc_vadjust for VRECTs. |v1.3 Negative results are prevented by the adjust routines; zero will be | placed into any rectangle structure element which would have been | negative after the adjustment. ;************************************************************************* ; Object utilities. ;************************************************************************* ;------------------------------------------------------------------------- ; obj_flchange (formerly objfl_change) ;------------------------------------------------------------------------- void obj_flchange(OBJECT *tree, int object, int flagsmask, int updateflag); This function sets or resets bits in an object's ob_flags field. Depending on the setting of 'updateflag' the object is updated on the screen or not. (Update is done via objc_draw internally). If the high bit of 'flagsmask' is set, the flags bits are reset, otherwise they are set. This allows the following syntax: objfl_change(mytree, myobj, HIDETREE, TRUE); objfl_change(mytree, myobj, ~HIDETREE, FALSE); The first case will set 'myobj' to hidden and will erase it from the screen. The second case will set 'myobj' to visible, but does not update the screen. Note that you CAN use this function to hide and unhide trees visibly on the screen. When the objc_draw is called internally by this function, the draw starts at the root of the tree, but is clipped by the x/y/w/h of the object who's state is being changed. This means that a flag change to HIDETREE with update will draw the parents of the hidden objec " ", /* 1 blank line between text & buttons */ ""}; /* NULL string terminates the list */ char help1_buttons[] = { "NEXT", "DONE", """}; /* NULL string terminates the list */ int btn; btn = frm_dsdial(help1_screen, help1_buttons, TRUE); if (btn == 0) { /* show second help screen */ } While this routine can be incredibly useful in handling help text, it should be noted that it is rather large. After linking, it will add about 1.5k to the size of your application (making it the largest entity in the GEMFAST system). |v1.4 This routine is new with this release. ;************************************************************************* ; Graphics Utilities. ; These utilties are NOT available in C source code form, as they use ; the Line-A TOS interface, which must be accessed via assembler code. ;************************************************************************* ;------------------------------------------------------------------------- ; gra_qonmouse (formerly graqon_mouse) ; gra_qofmouse (formerly graqof_mouse) ;------------------------------------------------------------------------- void graqon_mouse(); void graqof_mouse(); These routines turn the mouse pointer on and off quickly (using the Line-A HideMouse/ShowMouse routines). They will execute much faster than the equivelant graf_mouse() calls, and they behave |v1.3 in a similar manner. Specifically, the graf_mouse() calls track | the number of Hide/Show calls and if you 'hide' the mouse 3 times, | you must use the 'show' call 3 times before the mouse reappears. | These routines will behave in the same way (as of v1.3). ;------------------------------------------------------------------------- ; gra_qmstate (formerly graq_mstate) ;------------------------------------------------------------------------- graq_mstate(int *mousex, int *mousey, int *mousebtns); This routine returns the mouse x/y location and button state quickly, using the Line-A variable structure as the source of information. It is much faster than the graf_mkstate() call, and it does not return the keyboard state information. If you have an application full of graf_mkstate() calls that don't use the keystate info, you can code #define graf_mkstate(a,b,c,d) graq_mstate((a),(b),(c)) at the top of your program and instantly convert to the faster routine. (Caveat: This routine is NOT well-tested in v1.0). |v1.3 (NOTE: I've had problems with using this routine in conjunction | with evnt_mouse and evnt_multi type calls. It seems that if you | use the AES graf_mkstate() call it will (maybe?) clear some flag | indicating a mouse-related event is pending. When you use this | Line-A routine, the event is left pending, and the next evnt_???? | call doesn't work as you'd expect. I know, I know, I'm not being | very clear; that's only because I haven't looked into it too | closely. All I can say for sure is that some well-tested code | broke when I #defined graf_mkstate to invoke this routine, and when | I put it back, the code started working again. Other code, however | works just fine with graf_mkstate #define'd to this routine.- Ian) ;************************************************************************* ;* End of doc. ;************************************************************************* 
