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.) ;------------------------------------------------------------------------- ; obj_stchange (formerly objst_change) ;------------------------------------------------------------------------- ÃœØ⓪7õ5/¨´1œ0Ã3Øö'í%"í¬⓪⑤:92ØÇτIJ @τij╱@D╱ ατIJ @τא ו ג ◆⇩ τIJ @τij⇨גו ג⇦@ו⇦! 88x8gτττττττijIJIJ⇩'ג@ F IJ gא⇦ א ץêÖ\ך]יπ Çê╱ûΓ╱⑥Γ╱÷&ªV7Bw2╱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⓪①Ññ ק j4Œ⇧⇧əZ@Çì---------------------------- ; rsc_sstrings ;--------------------------------------------------------------------- @Fûåà╱à;7œØ⓪99õ»¨¨´94Ã3¨ö'í%"í¬⓪⑤:92Øû⓪╱à⓪⓪⓪⓪⓪⓪⓪⓪⓪⓪⓪⓪⓪⓪⓪⓪⓪⓪⓪⓪4Ã:⓪7õ5⑧û1œ0¨⓪⑤8:9⑧û╱à⓪⓪⓪⓪⓪⓪⓪⓪⓪⓪⓪⓪⓪⓪⓪⓪⓪⓪⓪⓪-Ãõ5⑨⑥8:9⑨⑥⓪⑦⑦⑦⓪7õ57⑥8:97⑥.åà⓪⓪⓪⓪⓪⓪⓪⓪⓪⓪⓪⓪⓪⓪⓪⓪⓪⓪⓪⓪⑥ÿö¥åà⓪⓪⓪⓪⓪⓪⓪⓪⓪⓪⓪⓪⓪⓪⓪⓪⓪╱à⓪⓪⓪⓪⓪⓪⓪⓪*44¨É3:Ã1´4ÃÃ⓪9Ø´9É7Ã2É7¨⓪6è2É9´94Ã3É87œÃ:2¨9É;œ´44Ã⓪0Ã⓪7õ52õ´╱à⓪⓪⓪⓪⓪⓪⓪⓪:92Øù⓪⓪! τij Dג⇩B ו Dא'ijIJג'גIJ⇦DD⇩D F⇦'הD ij⇦⇦ gא אI✓L τמ@ ijז✓`τו D°8gτττττττijכ⇧ijτij╱@D╱ 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 
