GEMini Atari

home *** CD-ROM | disk | FTP | other *** search

/ GEMini Atari / GEMini_Atari_CD-ROM_Walnut_Creek_December_1993.iso / files / program / graphx11 / gemfst17.lzh / GEMUTIL.DOC < prev next >

Wrap

Text File | 1992-07-15 | 27.8 KB | 559 lines

************************************************************************** * * GEMUTIL.DOC - Descriptions of the utility functions in GEMFAST. * * 05/26/90 - v1.4 * The rsc_gstrings()/rsc_sstrings() routines now support ICONs. * * The frm_dsdial() function has been added. * * 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) ;------------------------------------------------------------------------- void obj_stchange(OBJECT *tree, int object, int statemask, int updateflag); This function sets or resets bits in an object's ob_state 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 'statemask' is set, the state bits are reset, otherwise they are set. This allows the following syntax: objst_change(mytree, myobj, SELECTED, TRUE); objst_change(mytree, myobj, ~SELECTED, FALSE); The first case will set 'myobj' to SELECTED and show it that way on the screen. The second case will set 'myobj' to non-selected, and will not update the screen. |v1.4 Be aware that the xywh sizes of the root 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_xywh (formerly objc_xywh) ;------------------------------------------------------------------------- void obj_xywh(OBJECT *tree, int object, GRECT *rect); Returns an object's x/y/w/h values into a GRECT rectangle. Note that the x/y values are NOT automatically adjusted to screen coordinates, they are copied directly from the object tree structure. (Thus, if the object index is 0 (R_TREE) the rectangle will reflect screen coordinates, for any child object it will not.) ;------------------------------------------------------------------------- ; obj_offxywh ;------------------------------------------------------------------------- void obj_offxywh( OBJECT *tree, int object, GRECT *rect); Returns any object's screen-adjusted x/y/w/h values into a GRECT rectangle. This is a shortcut to calling objc_offset() then copying the object's w/h data into the GRECT structure. ;------------------------------------------------------------------------- ; objcl_calc (THIS ROUTINE IS BEING PHASED OUT!) ;------------------------------------------------------------------------- void objcl_calc(OBJECT *tree, int object, {GRECT *r1|NULL}, {VRECT *r2|NULL}); |v1.3 THIS ROUTINE IS BEING PHASED OUT, DO NOT RELY ON IT! It will be | rewritten someday, but will have a new name (obj_clipcalc). This routine does clipping calculations for an object. It calculates both GRECT and VRECT clipping rectangle simulataneously; if you specify a null pointer for one of the rectangle types those values won't be returned. This function will handle OUTLINED and SHADOWED objects, and will return the proper clipping rectangle to be passed to objc_draw() or vs_clip(). Typical usage might be: To redraw an object after changing ob_state or ob_flags... objcl_calc(mytree, refreshobj, &cliprect, 0L); objc_draw(mytree, refreshobj, MAX_DEPTH, cliprect); To outline an object with a VDI rounded rectangle... objcl_calc(mytree, refreshobj, 0L, &boxrect); v_rbox(vdi_handle, &boxrect); ;------------------------------------------------------------------------- ; obj_rbfind (formerly objxrb_which) ;------------------------------------------------------------------------- int obj_rbfind(OBJECT *tree, int parentobj, int state); This function returns the index of the first child object of the specified parent which is in the desired state, or -1 if no child objects are in that state. Note that the state test is done via bit-wise AND. As an example, it is possible to find an object which is either SELECTED *OR* CROSSED, but it is not possible to limit the search to only for objects which are *both* SELECTED *AND* CROSSED. ;------------------------------------------------------------------------- ; objrb_which (old name, which will be dropped eventualy) ; obj_rbwhich (old name, which will be dropped eventualy) ;------------------------------------------------------------------------- int objrb_which(OBJECT *tree, int parentobj); This function returns the index of the first child object of the specified parent which has the SELECTED bit set, or -1 if no child objects are selected. It is most useful in determining which |v1.3 radio button in a group has been selected. This function is | supported via a #define in the GEMFAST.H file, and actually | generates a call to obj_rbfind(), passing a state of SELECTED. | | This function is being phased out, it is recommended that you use | obj_rbfind(tree, parent, SELECTED) to perform this function. ;------------------------------------------------------------------------- ; obj_rbselect ;------------------------------------------------------------------------- int obj_rbselect(OBJECT *tree, int object, int state); This function logically de-selects the current object in a group of radio buttons and selects the specified object. The return value is the index of the object that was selected before the function was called. Rules for the 'state' value are as described under the obj_rbfind function. This function can handle the situation where there is no object in the radio button group which is currently selected; the new object is set to the specified state. This function *assumes* that the new object is a radio button type object, and that all other objects in the new object's parent are also radio button type objects. This does not have to be the case, but the routine can break down under extreme conditions (eg, don't try to specify the root as the new object.) Note that this function DOES NOT REDRAW either of the objects which are changed, it only changes the ob_state values in the object array. This function is primarily designed to pre-set radio buttons to a known state before calling a dialog handler. If redraw is needed as well, use a sequence such as: oldobj = obj_rbselect(ptree, newobj, SELECTED); if (oldobj > R_TREE) objc_draw(ptree, oldobj, MAX_DEPTH, cliprect); objc_draw(ptree, newobj, MAX_DEPTH, cliprect); Alternatively, a single objc_draw() can be used, specifying the parent of the radio button group. (This works fine for small groups of radio buttons, but the speed of redraw can be a factor for a large group of buttons.) |v1.4 This function is new with this version. ;------------------------------------------------------------------------- ; 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. ;************************************************************************* ;------------------------------------------------------------------------- ; rsc_sstrings ;------------------------------------------------------------------------- void rsc_sstrings(OBJECT *tree, int obj1,char *ptr1, [obj2,ptr2, ... objn,ptrn,] -1); This function sets one or more string pointers within an object tree. It understands the difference between STRING, BUTTON, and TEXT object types, and sets the appropriate pointer fields (ob_spec or te_ptext). Any number of object/pointer pairs may be specified, the list is terminated by a negative object number. The purpose of this function is to replace all the lines of code looking like... *((TEDINFO *)(tree[object].ob_spec))->te_ptext = pointer; with the simpler construct... rsc_strings(tree, str1obj,pstr1, txt1obj,ptxt1, /* etc */ -1); |v1.3 This routine understands objects with the INDIRECT flag set, and | will use the ob_spec field as an indirect pointer if appropriate. |v1.4 This routine now handles ICON objects. ;------------------------------------------------------------------------- ; rsc_gstrings ;------------------------------------------------------------------------- void rsc_gstrings(OBJECT *tree, int obj1,char **ptr1, [obj2,**ptr2, ... objn,**ptrn,] -1); This function gets one or more string pointers from within an object tree. It understands the difference between TEXT/nonTEXT object types, and gets the appropriate fields (ob_spec or te_ptext). Any number of object/pointer pairs may be specified, the list is terminated by a negative object number. This is a provided as a shortcut to doing a long series of rsrc_gaddr() calls to get the string/text pointers from a tree. Note that this function is not as flexible as rsrc_gaddr()...if the object type is one of the text objects, it will return a te_ptext pointer, otherwise the ob_spec value is returned. When used with strings/text, the ob_spec field will be a string pointer. example() { char *string1; char *text2; rsrc_gaddr(R_TREE, MYTREE, &mytree); rsc_gstrings(mytree, MYSTR1,&string1, MYTXT2,&text2, -1); } |v1.3 This routine understands objects with the INDIRECT flag set, and | will use the ob_spec field as an indirect pointer if appropriate. | Unlike previous releases, this routine has now been tested. |v1.4 This routine now understands ICON objects. ;------------------------------------------------------------------------- ; rsc_treefix ;------------------------------------------------------------------------- void rsc_treefix(OBJECT *tree); This function performs an rsrc_obfix() call for all objects in a tree. It's handy when using resource trees imbedded as source code within your program, which require manual x/y fixup. NOTE: This functions uses the LASTOB bit in ob_flags to determine when it has hit the end of the tree. When coding your resource tree, please be careful to set the LASTOB bit in the last object in the array. Note that this is NOT a routine to provide a full fixup of .RSH-type code emmitted by a resource construction editor; this routine does only x/y/w/h fixup on a single tree, and does |v1.4 not resolve cross-structure pointers. (The C source code files | RSHFIXUP.C and RS2FIXUP.C will provide the full runtime support for | embedded resource files. These are distributed separately from | the GEMFAST package.) ;************************************************************************* ;* Forms utilities. ;************************************************************************* ;------------------------------------------------------------------------- ; frm_dsdial ;------------------------------------------------------------------------- int frm_dsdial(char *pstrings[], char *pbuttons[], int graphicsflag); This function dynamically builds a dialog box around some boilerplate text and displays it. It is particularly useful for displaying help screens, or for explaining a situation to the user and providing a list of up to 5 choices/actions to be selected via buttons (like a mega-sized alert box). The dialog box will be dynamically sized to hold as many as 20 lines of text, and will adjust itself to the widest text line. Up to 5 buttons may be specified, and the buttons will be centered at the bottom of the dialog box. The rightmost button (the last one specified) will always be the DEFAULT button. It is the caller's responsibility to insure that the widest text line (or the combined length of the buttons) doesn't cause the dialog box to be wider than the current screen. (EG, no auto-word-wrap here!) The routine returns the index of the button used to exit (first | button == 0, etc), or -1 on error. (Right now, the only way to | get -1 is to pass a NULL array pointer.) To specify the text lines and buttons, the caller passes pointers to arrays of pointers to strings. (This is not as complex as it | sounds, see the example below.) A pointer to a empty string or | a NULL pointer terminate the lists of text and buttons. (The | use of a NULL pointer in an array slot as a terminator was added | in v1.7). The caller also passes a TRUE/FALSE value for 'graphicsflag', to indicate whether FMD_GROW and FMD_SHRINK graphics should be done as part of the dialog processing. The following example shows setting up and calling this routine: char *help1_screen[] = { " Help Screen 1", /* title line, hand-centered */ "This is the first in a series of", "help screens which tell you basically", "nothing of true interest. If you are", "foolish enough to select the 'NEXT'", "button, below, you will see even more", "screens full of worthless information." " ", /* 1 blank line between text & buttons */ ""}; /* empty string terminates the list */ char help1_buttons[] = { "NEXT", "DONE", NULL}; /* NULL pointer 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. ;*************************************************************************