Frozen Fish 1: Amiga

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

/ Frozen Fish 1: Amiga / FrozenFish-Apr94.iso / bbs / alib / d9xx / d911 / gadoutline.lha / GadOutline / Programmer / programmer.lha / Includes / GadOutline.doc next >

Wrap

Text File | 1993-07-28 | 151KB | 3,911 lines

TABLE OF CONTENTS gadoutline.library/AllocGadOutlineA gadoutline.library/command_hooks gadoutline.library/DestroyGadOutlineA gadoutline.library/DimenGadOutlineA gadoutline.library/DrawGadOutlineA gadoutline.library/FreeGadOutline gadoutline.library/GO_AllocMem gadoutline.library/GO_AttachHotKey gadoutline.library/GO_BeginRefresh gadoutline.library/GO_CallCmdHookA gadoutline.library/GO_CallTransHookA gadoutline.library/GO_CloseLibrary gadoutline.library/GO_CloseScreen gadoutline.library/GO_CloseWindow gadoutline.library/GO_CmdAtPointA gadoutline.library/GO_ContCmdHookA gadoutline.library/GO_ContTransHookA gadoutline.library/GO_DupGOIMsg gadoutline.library/GO_EndRefresh gadoutline.library/GO_FilterGOIMsg gadoutline.library/GO_FreeMem gadoutline.library/GO_GetBoxAttr gadoutline.library/GO_GetCmdAttr gadoutline.library/GO_GetCmdAttrsA gadoutline.library/GO_GetCmdInfo gadoutline.library/GO_GetErrorCode gadoutline.library/GO_GetErrorObject gadoutline.library/GO_GetErrorText gadoutline.library/GO_GetGOFromGOIMsg gadoutline.library/GO_GetGOFromIMsg gadoutline.library/GO_GetGOIMsg gadoutline.library/GO_GetObjAttr gadoutline.library/GO_GetObjAttrsA gadoutline.library/GO_InterpretTypedSize gadoutline.library/GO_OpenLibrary gadoutline.library/GO_OpenScreenA gadoutline.library/GO_OpenWindowA gadoutline.library/GO_ParseGOIMsgA gadoutline.library/GO_ParseTypedSizeListA gadoutline.library/GO_PostFilterGOIMsg gadoutline.library/GO_ReplyGOIMsg gadoutline.library/GO_SetCmdAttrsA gadoutline.library/GO_SetCmdGrpAttrsA gadoutline.library/GO_SetErrorA gadoutline.library/GO_SetObjAttrsA gadoutline.library/GO_SetObjGrpAttrsA gadoutline.library/GO_ShowErrorA gadoutline.library/GO_UndupGOIMsg gadoutline.library/HookGadOutlineA gadoutline.library/RebuildGadOutlineA gadoutline.library/ResizeGadOutlineA gadoutline.library/translation_hooks gadoutline.library/UnhookGadOutlineA gadoutline.library/UpdateGadOutlineA gadoutline.library/AllocGadOutlineA gadoutline.library/AllocGadOutlineA 15 Jul 1993 04:39:42 NAME AllocGadOutlineA -- Create a new GadOutline. SYNOPSIS GadOutline = AllocGadOutlineA(Outline, TagList) A0 A1 struct GadOutline *AllocGadOutlineA(ULONG *, struct TagItem *) FUNCTION Allocates and initializes a new GadOutline based on the given Outline array. This array is formatted as sequence of ULONG command codes, each of which can have 0 to 7 ULONG parameters and 0 to 3 tag lists immediately following it. The entire ULONG command code is divided into a number of fields, including the number of parameters and tag lists which follow it, the command class, code, and subcode. See <libraries/gadoutline.h> for the definitions of these fields and macros which supply an abstraction from the actual creation of the command data. The Outline array is terminated by the special command code GO_ENDOUTLINE(). The library first allocates and initializes a GadOutline structure and then calls UpdateGadOutlineA() with the given tag list. Then, for each command code in the outline, the library will allocate a CmdInfo structure, fill in the parameters supplied in the outline and create copies of all of the supplied tag lists and attach them to the CmdInfo. All unspecified parameters will be set to 0, and all unspecified tag lists will be initialized to a tag list containing a single TAG_END. The library will then look for a GOCT_SetUserHook tag in the command's first ("command") tag list and, if it exists, send a CHM_TRANSCMDHOOK to the GadOutline's Translation Hook, attach it to the command as the highest level hook, initialize ci_UserHookData to either the value in GOCT_SetUserHookData or 0, and set ci_UserHookState to 0. The library will then send to the highest-level hook attached to the command the messages CHM_INITIALIZE, CHM_INITCMDATTR, CHM_INITOBJATTR, in that order. This is the only time the library will ever send these messages, and the hook is expected to perform any initialization/allocation of resources and an initial parsing of its tag lists when it recieves the respective messages. There are a couple of commands which get special treatment. When the command GO_OUTLINETAGS() is encountered in the outline, its second ("object") tag list is passed to UpdateGadOutlineA() before any of its hooks are called. The command GO_COMMANDTAGS() will cause evey command following it to have the tags in its object tag list to be added to their command tag list if they are not already in it. If this command is specified multiple times, it overrides the previous occurance. Finally, DimenGadOutline is called with the completed GadOutline. INPUTS Outline - (ULONG *) List of commands to create outline. TagList - (struct TagItem *) Global (GOA_*) outline tags. RESULT GadOutline - (struct GadOutline *) The freshly created GadOutline. TAGS Command tags - GOCT_SetUserHook - Provide custom hook for command. GOCT_SetUserHookData - Initialize ci_UserHookData field. GOCT_SetHotKey - Attach a hotkey to the command. GOCT_SetHotKeyCmd - Provide StdID of command which will receive hotkey events attached to this command. EXAMPLE See example3.c NOTES A user command hook must always pass through the messages CHM_INITIALIZE, CHM_INITCMDATTR, CHM_INITOBJATTR and CHM_TERMINATE to the library's internal hooks using GO_ContCmdHookA(). While currently the tag list supplied in the CHM_INITCMDATTR and CHM_INITOBJATTR messages are simply the identical tag lists within the CmdInfo structure (ci_CmdTags and ci_ObjectTags), this may change in the future. The order that the global tags are parsed is: first the list passed directly to AllocGadOutlineA(), then any from the GO_OUTLINETTAGS() commands, in the order that they appear in the outline. When DimenGadOutlineA() is called with the completed GadOutline, it is passed an empty tag list. If an error occurs during DimenGadOutlineA(), the outline will be free'd and a NULL will be returned. This is important if you are specifying a displaymode, screen or window within the initial tag list -- if the layout will not fit, DimenGadOutlineA() will fail and you will simply receive a NULL. To avoid this, don't specify these in AllocGadOutlineA() and instead call DimenGadOutlineA() afterwards with these tags. Normally, errors in layout, allocating memory, etc. will result in the library displaying a requester through GO_ShowError. You can turn off all errors by passing the tag { GOCT_ErrorReportLevel,0 } to AllocGadOutlineA(). Putting this tag in an initial GO_OUTLINETAGS() command within the outline will not work, as the library has aleady allocated a large part of its resources by the time this command is parsed. If you use GOA_BaseName to put the name of your program in the library's error requesters, this name will not appear if the library is unable to allocate the initial GadOutline structure. BUGS . SEE ALSO FreeGadOutline(), DimenGadOutlineA(), UpdateGadOutlineA(), GO_GetCmdInfo() gadoutline.library/command_hooks gadoutline.library/command_hooks 18 Jul 1993 14:42:12 NAME command_hooks -- Information on GadOutline command hooks. SYNOPSIS Result = command_hooks(Hook, Command, Message) A0 A2 A1 static ULONG command_hooks(struct Hook *, struct CmdInfo *, struct CmdHookMsg *) FUNCTION The command hook provides an abstract interface between the library and the actual creation and manipulation of the display's gadgets and associated objects. It is based on the standard utility.library hook structure and the CmdHookMsg structure as defined in gadoutline.h. The following messages must be sent to the standard hook with GO_ContCmdHookA() before being processed: CHM_INITIALIZE - sent to the hook during the initial allocation and initialization of all commands. When sent, the library has already allocated a CmdInfo structure, and BoxAttr if needed, and the hook is expected to do any initialization it may need. This may involve such things as initializing its command's state tags or allocating a block of memory and attaching it to ci_UserData. CHM_INITCMDATTR - provides the hook with a look at the initial command tag list supplied in the outline. Don't expect ci_CmdTags to be valid until after this messages has been processed with GO_ContCmdHookA(). CHM_INITOBJATTR - provides the hook with a look at the initial object tag list supplied in the outline. Don't expect the secondary tag list to be valid until after this messages has been processed with GO_ContCmdHookA(). The following message must be sent to the standard hooks with GO_ContCmdHookA() after being processed: CHM_TERMINATE - sent while a GadOutline is being deallocated. The hook should free any resources allocated in CHM_INITIALIZE. [Although any memory allocated with GO_AllocMem() will automatically be free'd by the library.] The following messages will almost always need to be processed by the library with GO_ContCmdHookA() so that the command's tag lists will remain updated: CHM_SETCMDATTR - update from the command tags supplied in the tag list pointed to by the first argument. After being processed by the library, ci_CmdTags will have been updated to reflect the new values and you may check for any user tags you have defined. CHM_SETOBJATTR - update from the object tags supplied in the tag list pointed to by the first argument. After being processed by the library, the secondary tag list will have been updated to reflect the new values. The user hook's processing of this tag will typically involve something like calling SetAttrsA() with the tag list sent by the message. Note that when updating a gadget's tags, you should use go_HookedWin and NOT go_Window to find the window that the gadget is attached to, so that you will correctly handle things like the gadget being temporarily detached from the GadOutline's window. Be ready for this message to be sent when the gadget is attached to the window, when the gadget is created but not attached, and when the gadget isn't created at all. CHM_GETCMDATTR - fill in the tags supplied in the tag list pointed to by the first argument with the current state of the command tags. After being processed by the library, the tags in ci_CmdTags will have been copied to the tag list. CHM_GETOBJATTR - fill in the tags supplied in the tag list pointed to by the first argument with the current state of the secondary tags. After being processed by the library, the tags in the secondary tag list will have been copied to the message's tag list and you may update them from there. This will normally involve calling something like GetAttr() for each tag in the list. The following are messages commonly processed completely by the user hook: CHM_GETMINDIMENS - used by the library to query for the gadget's standard dimensions during a layout. This message is sent only to group and box commands; you are expected to fill in the GODimensInfo structure pointed to by the first argument with your desired dimensions. Note that these dimensions may be modified using command tags in the outline. CHM_CREATEOBJ - ask hook to create its object. The first argument points to a NewGadget structure from which the hook may get its dimension information, although looking at its BoxAttr is also permissible. What actually happens here is entirely up to the hook; the only thing the library cares about is the value in ci_Object; a non-NULL value indicates something was created, NULL means nothing was created. NULL is not a failure however; the hook is expected to report its own failures and should set go_LastReqReturn to GORET_FAIL if it really wants to stop everything with an error. A special ci_Object value of ~0 indicates that the hook didn't really create an object, but it would like to be informed of CHM_DRAWSELF and other events. Note that you must _always_ give a gadget you create the ng_GadgetID and ng_UserData values found in the NewGadget structure; these are used internally by the library. To add a gadget to the window, it must be linked to one of the GadOutline's gadget lists. GadTools gadgets should always be attached to the last GadTools gadget pointed to by go_LastGTools, and then set go_LastGTools to now point to the new gadget; this list will be automatically free'd by the library. All other gadgets should attach after the gadget pointed to by go_LastBoopsi and then set themselves as the new last gadget. CHM_DESTROYOBJ - deallocate an object created with CHM_CREATEOBJ. When receiving this message, you should deallocate anything created during CHM_CREATEOBJ and save any final state information from the object that you need to keep for a subsequent CHM_CREATEOBJ. You should always set ci_Object to NULL when receiving this command. Be prepared to receive this message even if your object is not created. Any GadTools gadget added to the go_GToolsList will be automatically free'd by the library after this message is sent and should not be deallocated by the user hook - the hook should just set its ci_Object to NULL. CHM_RESIZEOBJ and CHM_PRERESIZE - support for resizing objects which do not have to be fully destroyed/created. These are currently not fully implemented and should always perform the identical operation as CHM_CREATEOBJ and CHM_DESTROYOBJ, respectively. CHM_HOOKOBJ and CHM_UNHOOKOBJ - sent to inform hook of the attaching a removal of the gadget lists from the window. CHM_MADELINK - sent to a hook after another object has been created which has a TagLink to this one. Typically used to reset any of the object's state which may have been affected by the link. CHM_UPDATESTATE - sent to a hook when its gadget has been pressed or released, or an event has occured between the gadget down and up events. The GOIMsg that occured is in the first argument; you may modify this any way you please. This message is typically used to track the state of a gadget so that it is correctly reflected in the command's object tag list. CHM_HOTKEY - perform hotkey operation for the command. Sent when an IDCMP_RAWKEY or IDCMP_VANILLAKEY event has occured which is attached to the hook's command. The hook should perform whatever action the gadget should take for hotkeys and update the GOIMsg pointed to by the first argument, which contains the event which triggered the hotkey, to reflect the event that the gadget performed, ie a gadget up event. CHM_DRAWSELF - sent when the hook needs to redraw its imagery. This message will only be sent when the command's ci_Object is non-NULL. INPUTS Hook - (struct Hook *) Your hook. Command - (struct CmdInfo *) The command being sent the message. Message - (struct CmdHookMsg *) The operation to perform. RESULT Result - (static ULONG) Message-dependant return value. SEE ALSO GO_CallCmdHookA(), GO_ContCmdHookA() LIBRARY HOOKS These are the operations implemented by the library's built-in hooks: COMMANDS: ~~~~~~~~ CHM_INITCMDATTR: CHM_SETCMDATTR: Updates command state tags from list. Parses the following tags: GOCT_SetUserHook, GOCT_SetUserHookData, GOCT_SetHotKey, GOCT_SetHotKeyCmd. CHM_GETCMDATTR: Copies the current command tags into the supplied tag list. CHM_INITOBJATTR: CHM_SETOBJATTR: Updates the current object tags from the given tag list. CHM_GETOBJATTR: Copies the current object state tags to the supplied tag list. BOX/IMAGE COMMANDS all COMMANDS operations plus: ~~~~~~~~~ CHM_INITIALIZE: Nothing. CHM_TERMINATE: Frees any previously allocated BoxPosInfo. CHM_INITCMDATTR: CHM_SETCMDATTR: Updates flags from all box tags GOCT_IgnoreMinDimen, GOCT_IgnoreFinDimen, GOCT_IgnoreCreation. Sets pointer for GOCT_BoxPosInfo; allocates the structure if the tag's ti_Data is ~0. CHM_GETCMDATTR: Should parse above flags, but doesn't. :) GADTOOLS BOX COMMANDS all BOX COMMANDS operations plus: ~~~~~~~~~~~~~~~~~~~~~ CHM_INITIALIZE: All kinds - Translate GadTools label, sets ci_ObjIDCMP flags. STRING_KIND - Allocate a memory buffer to hold string. CHM_TERMINATE: STRING_KIND - Free the previously allocated buffer. CHM_RESIZEOBJ and CHM_CREATEOBJ: All kinds - Calls GadTools CreateGadgetA() to create the gadget; adds it to GadOutline.go_LastGadTools. Points ci_Object to the newly created gadget. Except for TEXT_KIND and NUMBER_KIND, Makes sure size is at least 4 x 2 pixels. LISTVIEW_KIND - Modifies body size if there is a hooked string gad and sets GTLV_Top to GTLV_Selected. MX_KIND - Adjusts border to only include radio buttons. STRING_KIND - Sets activation flags under v37. INTEGER_KIND - Sets activation flags under v37. CHM_PRERESIZE and CHM_DESTROYOBJ: All kinds - Sets GadAttr.ga_Object to NULL STRING_KIND - Copies current gadget string to buffer and points GTST_String to the buffer. INTEGER_KIND - Updates GTIN_Number from gadget's buffer. CHECKBOX_KIND - Updates GTCB_Checked from gadget. CHM_UPDATESTATE: Unless otherwise noted, all kinds only update on IDCMP_GADGETDOWN and IDCMP_GADGETUP events. CHECKBOX_KIND - Toggles GTCB_Checked. STRING_KIND - Copies current gadget string to buffer and points GTST_String to the buffer. INTEGER_KIND - Updates GTIN_Number from gadget's buffer. MX_KIND - Updates GTMX_Active from IntuiMessage.Code. CYCLE_KIND - Updates GTCY_Active from IntuiMessage.Code. SLIDER_KIND - Updates GTSL_Level from IntuiMessage.Code. Also updates from IDCMP_MOUSEMOVE if this is the active cmd. SCROLLER_KIND - Updates GTSC_Top from IntuiMessage.Code. Also updates from IDCMP_MOUSEMOVE if this is the active cmd. LISTVIEW_KIND - Updates GTLV_Selected from IntuiMessage.Code. PALETTE_KIND - Updates GTPA_Color from IntuiMessage.Code. CHM_HOTKEY: All kinds - Ignores all upkey events and every event if the gadget is disabled. BUTTON_KIND - Modifies GOIMSG to look like a GADGETUP event. STRING_KIND - Activates the gadget. INTEGER_KIND - Activates the gadget. MX_KIND - Increments/decrements GTMX_Active with wrap-around & modifies the GOIMsg to look like a GADGETDOWN event. All of these modify the GOIMsg to look like a GADGETUP event: CHECKBOX_KIND - Toggles value of GTCB_Checked. CYCLE_KIND - Increments/decrements GTCY_Active w/wrap-around. SLIDER_KIND - Increments/decrements GTSL_Level w/wrap-around. SCROLLER_KIND - Increments/decrements GTSC_Top w/wrap-around. LISTVIEW_KIND - Inc/dec GTLV_Selected w/wrap-around. PALETTE_KIND - Increments/decrements GTPA_Color w/wrap-around. CHM_INITOBJATTR: All kinds - Translates GTST_EditHook, if it is supplied. If GOCT_SetHotKey is in the command list with a zero for the low byte, and the gadget's label has an underline, set correct hotkey. STRING_KIND - Translates GTST_String. MX_KIND - Translates array in GTMX_Labels. CYCLE_KIND - Translates array in GTCY_Labels. SLIDER_KIND - Translates string in GTSL_LevelFormat. TEXT_KIND - Translates string in GTTX_Text. SLIDER_KIND - Translates string in GTSL_LevelFormat. CHM_SETOBJATTR: All kinds - Updates the current tags from the given tag list, then sends that tag list to GO_SetGadgetAttrs(). LISTVIEW_KIND - Sets GTLV_Top to GTLV_Selected, if GTLV_Top is included in the update tag list with a ti_Data of ~0. CHM_GETOBJATTR: All kinds - Copies the current state tags into the supplied tag list. STRING_KIND - Copies current gadget string to buffer and points GTST_String, if supplied, to buffer. INTEGER_KIND - Updates GTIN_Number, if supplied, from gadget string. CHM_GETMINDIMENS: All kinds - Determines the gadget's minimum dimens, based on the position and text of any labels. Gives def. body height of text height + 2 pixels for borders. STRING_KIND - Body height of text height + 4 pix for border. INTEGER_KIND - Body height of text height + 4 pix for border. TEXT_KIND - Reduces size if there is no border. NUMBER_KIND - Reduces size if there is no border. MX_KIND - Enlarges body to fit width and height of current labels; Removes all pad space from body. CHECKBOX_KIND - Makes sure body is at least 26 x 11. LISTVIEW_KIND - Makes sure body is at least one char width + 8 pixels + the width of the scroll bar. Makes height at least two lines and 4 pixels, three lines and 6 pixels if GTLV_ShowSelected. PALETTE_KIND - Makes sure body is at least 4+(1 char width) x 4+(1 char height), plus the indicator size. SCROLLER_KIND - Makes sure body is 8+(1 char width) or 4+(1 char height), plus space for arrows. SLIDER_KIND - If GTSL_MaxLabelLen, adds in that times a numeric character width. CYCLE_KIND - Makes sure all labels fit. CHM_MADELINK: STRING_KIND - Restores string from local buffer. BOOPSI BOX COMMANDS all BOX COMMANDS operations plus: ~~~~~~~~~~~~~~~~~~~ CHM_INITIALIZE: Translates the BOOPSI class name and private class. CHM_RESIZEOBJ and CHM_CREATEOBJ: Calls NewObject() with the command's box text and value. If the subcode is GOSB_Image, GOSB_Gadget or GOSB_AddGad, the following tags will automatically be filled in: IA_Left = ba_BodyLeft, IA_Top = ba_BodyTop, IA_Width = ba_BodyWidth, IA_Height = ba_BodyHeight, IA_Pens = go_DrI->dri_Pens, IA_Resolution = (go_DrI->X << 16) | go_DrI->Y, SYSIA_DrawInfo = go_DrI GA_ID = GETSTDID(ci_CmdID), GA_Left = ba_BodyLeft, GA_Top = ba_BodyTop, GA_Width = ba_BodyWidth, GA_Height = ba_BodyHeight, GA_UserData = private, GA_Previous = go_LastBoospsi, GA_DrawInfo = go_DrI If the subcode is GODB_AddGad, the resulting object will be added to the BOOPSI gadget list. CHM_PRERESIZE and CHM_DESTROYOBJ: Calls DestroyObject() on the gadget. CHM_HOTKEY: propgclass - Increments/decrements PGA_Top with wrap-around and modifies the GOIMsg to look like a GADGETUP event. strgclass - Activates the gadget. buttongclass - Modifies GOIMSG to look like a GADGETUP event. frbuttonclass - Modifies GOIMSG to look like a GADGETUP event. CHM_INITOBJATTR: Translates STRINGA_EditHook, if it is supplied. CHM_SETOBJATTR: Updates the current tags from the given tag list and then sends that same tag list to SetGadgetAttrs() if the subcode is GOSB_AddGad, else sends them to SetAttrs(). CHM_GETOBJATTR: Copies the current state tags into the supplied tag list and then calls GetAttr() for each tag in the list. DRAW BOX COMMANDS all BOX COMMANDS operations plus: ~~~~~~~~~~~~~~~~~ CHM_INITIALIZE: If the subcode is GOSD_BoopsiIm or GOSD_BoopsiGad, creates a vector drawing image. CHM_TERMINATE: Free previously allocated image. CHM_RESIZEOBJ and CHM_CREATEOBJ: If the subcode is GOSD_Normal, set ci_Object to ~0 If the subcode is GOSD_Button, create a generic GadTools kind and make it a button. If the subcode is GOSD_BoopsiIm, set the previously created image's to the position and size of the command's box and point ci_Object to it. If the subcode is GOSD_BoopsiGad, set the image's size to the command's size and create a BOOPSI buttongclass, attach it to the image and add it to the BOOPSI tag list. NOTE: Standard GadTools and BOOPSI tags are not supported, in particular GA_Disabled and GT_Underscore. To get a button which will disable itself, use a GOSD_BoopsiIm subcode and create a BOOPSI box with a button which points to the image. CHM_PRERESIZE: CHM_DESTROYOBJ: Set Object to null, free BOOPSI gadget. CHM_INITOBJATTR: Translates GODT_DrawText* commands and the ti_Data of the tag pointed to by GODT_DrawText*Tag commands. CHM_SETOBJATTR: If subcode is GOSD_Normal or GOSD_Button, sends itself a CHM_DRAWSELF message. If subcode is GOSD_BoopsiGad, redraws the gadget. CHM_HOTKEY: If subcode is GOSD_Button or GOSD_BoopsiGad, turn key event into a button up. CHM_DRAWSELF: If subcode is GOSD_Normal or GOSD_Button, creates a drawing environment based on its command box size and executes the drawing commands in its object tag list. GROUP COMMANDS all BOX COMMANDS operations plus: ~~~~~~~~~~~~~~ CHM_INITIALIZE: Sets group to same type as parent, or GOCT_FrameGroup if none. CHM_RESIZEOBJ and CHM_CREATEOBJ: Sets ci_Object to ~0. CHM_PRERESIZE and CHM_DESTROYOBJ: Sets ci_Object to NULL. CHM_INITCMDATTR and CHM_SETCMDATTR: Updates flags from all box tags plus GOCT_EvenDistGroup, GOCT_FrameGroup, GOCT_FitToGroup, GOCT_AutoDistExtra. CHM_GETCMDATTRS: Should parse above flags, but doesn't. CHM_INITOBJATTR: Translates GODT_DrawText* object tags and the ti_Data of the tag pointed to by GODT_DrawText*Tag commands. CHM_SETOBJATTR: Sends itself a CHM_DRAWSELF message. CHM_DRAWSELF: Creates a drawing environment with boundaries initialized to its space frame size and executes the drawing commands in its object tag list. gadoutline.library/DestroyGadOutlineA gadoutline.library/DestroyGadOutlineA 16 Jul 1993 08:00:01 NAME DestroyGadOutlineA -- Destroy all created objects. SYNOPSIS DestroyGadOutlineA(GadOutline, TagList) A0 A1 void DestroyGadOutlineA(struct GadOutline *, struct TagItem *) FUNCTION Calls UpdateGadOutlineA() with the given tag list, unhooks the gadgets using UnhookGadOutlineA() and then sends CHM_DESTROYOBJ to all commands in the GadOutline. This leaves the GadOutline in a state where it is completely detached from its window, but note that this does not in any way mean that you a free to do anything with the window. The only legal way to detach a window or screen is to set { GOA_WindowAddr, NULL } or { GOA_ScreenAddr, NULL } or to call GO_CloseWindowA() or GO_CloseScreenA(). The window's original font will be restored if it had been changed by RebuildGadOutlineA(). INPUTS GadOutline - (struct GadOutline *) Previously allocated GadOutline. TagList - (struct TagItem *) Global (GOA_*) outline tags, parsed before the actual unhook/destroy is performed. RESULT Nothing returned from the function. go_LastReqReturn is non-zero if an error occured. (If an empty tag list is passed, an error should never be returned.) TAGS EXAMPLE NOTES You should never need to call this function. BUGS . SEE ALSO UnhookGadOutlineA(), UpdateGadOutlineA() gadoutline.library/DimenGadOutlineA gadoutline.library/DimenGadOutlineA 15 Jul 1993 05:38:25 NAME DimenGadOutlineA -- Perform a full layout of a GadOutline. SYNOPSIS DimenGadOutlineA(GadOutline, TagList) A0 A1 void DimenGadOutlineA(struct GadOutline *, struct TagItem *) FUNCTION This is the primary part of the layout engine. This routine will try to find a layout of the gadgets that will fit within the current bounds. The only outline commands that are involved in this layout are the groups and boxes that occur between the first group command within the outline (GO_VERTGRP(), GO_HORIZGRP()) and its associated GO_ENDGRP(). Each of these will be sent the message CHM_GETMINDIMENS, with this data being used to find the minimum size that the layout can be. If a box or group has its GOCT_IGNOREMINDIMENS tag set, it will still be layed out, but its resulting dimensions will be ignored when computing its parent group's dimensions - the group or box that follows it will essentially be treated as if it had a width and height of zero. The total dimensions of a box or group is divided into 10 different areas, 5 each in both the horizontal vertical directions. These are called: SpaceLeft, TextLeft, BodyWidth, TextRight and SpaceRight, and SpaceAbove, TextAbove, BodyHeight, TextBelow and SpaceBelow. The space areas are the spacing to put between congruent boxes and groups, the text areas are the spacing needed by anything outside the actual body [ie, GadTools labels], and the body is the actual size of the gadget. These areas are further divided into three components each, called Standard, Padding, and Variable (STD, PAD, VAR). The standard component is the amount of space that area must contain, the padding component is any extra space it would like to have but can be removed if needed to make the layout fit, and the variable area is where extra space needed to expand the box is put. DimenGadOutline takes care of the STD and PAD components, but ignores the VAR component, which is handled by RebuildGadOutlineA(). Before laying out the gadgets, UpdateGadOutlineA() is called with the given tag list and DestroyGadOutline() is called to unhook and deallocate any previously created gadgets. In addition, all GOCT_CopyFromTSize ... GOCT_CopyTSizeToTag command pairs are executed to initialize the command's object tag list. To perform a layout, the list of boxes and groups within a group is walked, and the minimum dimensions for each is computed. The minimum dimensions of a box are found by sending the box a CHM_GETMINDIMENS and then parsing the TypedSize tags within the box's command taglist to allow the outline to modify these defaults. The minimum dimensions for the group is now based on the total of the dimensions of each of the boxes and groups within a group and the layout modes of the group. There are two basic modes in the group's static dimension [ie, the vertical dimension of a horizontal group], body and strict, and two modes in the running dimension - even distribution on and off. In body mode, the space used by all of the areas of the child boxes and groups is assigned to the parent group's body size - ie, the BodyHeight of a horizontal group is the maximum of the total height of each box within it, and you are only guaranteed that all of the boxes will be the same height; there is no guarantee that their bodies will line up in any way. In strict mode, the maximum of each individual area is taken, so that all boxes and groups have the same SpaceAbove, TextAbove, BodyHeight, TextBelow and SpaceBelow. When even distribution is off, the width of a horizontal group will simply be the sum of the minimum size of each of the boxes and groups within it. When even distribution is on, all of the boxes and groups are forced to be the same size as the largest within the group. The static dimension mode is controlled with three command tags. These tags are mutually exclusive; setting one TRUE makes the others FALSE. GOCT_FitToGroup - If true, turn on strict mode. GOCT_AutoDistExtra - If true, turn on strict mode, but don't expand boxes to group size until RebuildGadOutlineA(). GOCT_FrameGroup - If true, turn on body mode and reserve the space area around the group to itself. [By default this area will be set to zero; this is normally used to reserve area around it to draw a border.] There is one tag that controls the running dimension mode - GOCT_EvenDistGroup. Set to TRUE to turn on even distribution. After the group's initial minimum size is found, the TypedSize tags within the command tag list are parsed to allow them to be modified. These are usually used to specify the size of the frame needed around a GOCT_FrameGroup using the GOCT_SizeSpace* tags. Once the layout's minimum dimensions have been found, they are compared with the current layout bounds [ie, the size of the screen or window.] If the layout is too big, the library will try various things to make it fit, first attempting to use a smaller font size, then trying to remove padding from the boxes and groups, and finally falling back to the screen default font, the system default font, and lastly topaz 8. If none of these work, an error will be reported; you can find out about this by checking for a non-zero value in go_LastReqReturn, as usual. If the layout is successful and a window or screen is attached to the GadOutline, RebuildGadOutlineA() is called with an empty tag list. INPUTS GadOutline - (struct GadOutline *) Previously allocated GadOutline. TagList - (struct TagItem *) Global (GOA_*) outline tags, parsed before the actual layout is performed. RESULT Nothing returned from the function. go_LastReqReturn is non-zero if an error occured. TAGS Command tags - GOCT_IgnoreMinDimens - ignore box's size when computing parent's minimum size. GOCT_FrameGroup - reserve group's space area to itself GOCT_FitToGroup - make every area of children boxes match GOCT_AutoDistExtra - same as GOCT_FitToGroup, but extra space not distributed until RebuildGadOutlineA(). GOCT_EvenDistGroup - make all boxes same size in running dimension. EXAMPLE NOTES If the library needs to remove padding from the layout, the PAD component of the GOCT_SizeUser1 and GOCT_SizeUser2 variables will be scaled by the same amount as the amount of scaling in the box's width and height, respectively. BUGS . SEE ALSO RebuildGadOutlineA(), UpdateGadOutlineA(), DestroyGadOutline() gadoutline.library/DrawGadOutlineA gadoutline.library/DrawGadOutlineA 16 Jul 1993 08:12:56 NAME DrawGadOutlineA -- Tell all commands to draw themselves. SYNOPSIS DrawGadOutlineA(GadOutline, TagList) A0 A1 void DrawGadOutlineA(struct GadOutline *, struct TagItem *) FUNCTION Calls UpdateGadOutlineA() with the given tag list and then sends CHM_DRAWSELF messages to all commands with a non-NULL ci_Object. If a command doesn't actually create an object but still wants to receive messages, it should set ci_Object to ~0 when it receives a CHM_CREATEOBJ/CHM_RESIZEOBJ and to NULL when it gets a CHM_DESTROYOBJ/CHM_PRERESIZE. INPUTS GadOutline - (struct GadOutline *) Previously allocated GadOutline. TagList - (struct TagItem *) Global (GOA_*) outline tags, parsed before the actual drawing is performed. RESULT Nothing returned from the function. go_LastReqReturn is non-zero if an error occured. TAGS EXAMPLE NOTES . BUGS . SEE ALSO UpdateGadOutlineA() gadoutline.library/FreeGadOutline gadoutline.library/FreeGadOutline 15 Jul 1993 04:10:30 NAME FreeGadOutline -- Deallocate an entire GadOutline. SYNOPSIS FreeGadOutline(GadOutline) A0 void FreeGadOutline(struct GadOutline *) FUNCTION Closes window, port and screen, and frees everything associated with a GadOutline. All memory attached to this GadOutline through GO_AllocMem() will be free'd. If a window has been opened with GO_OpenWindowA(), it will be closed. Depending on the current state of the outline, the messages CHM_UNHOOKOBJ and CHM_DESTROYBJ will be sent to the command hooks. CHM_TERMINATE will always be sent to the hooks. This routine should be safe to call, and properly cleanup resources, no matter what state the GadOutline is in. INPUTS GadOutline - (struct GadOutline *) A previously allocated GadOutline. RESULT nothing. EXAMPLE NOTES . BUGS . SEE ALSO AllocGadOutlineA(), GO_AllocMem() gadoutline.library/GO_AllocMem gadoutline.library/GO_AllocMem 16 Jul 1993 15:03:59 NAME GO_AllocMem -- Allocate memory and attach it to a GadOutline. SYNOPSIS Address = GO_AllocMem(GadOutline, ErrReport, Size, Flags) A0 D0 D1 D2 void *GO_AllocMem(struct GadOutline *, GOERR, ULONG, ULONG) FUNCTION Allocates a block of memory of the given size and attaches it to the given GadOutline to be tracked and automatically deallocated when the GadOutline is free'd in FreeGadOutline(). If NULL is supplied for the GadOutline, it will not be tracked. ErrReport specifies what to do if the memory can not be allocated. If it is 0, the library will simply return NULL. Otherwise, it is interpreted as a standard error code and the library will call GO_SetError() with the given error if unable to allocate the memory. If the selected error has a RETRY choice, the library will attempt to allocate the memory again if it is selected; if it is then able to get it, the caller will never know there was a problem. A shortcut is provided in specifying the error. If the error type field is zero, the library will interpret the code field as the type and automatically use the memory code - ie, GO_MAKEERR(GETERRCODE(ErrReport),GOCODE_MEMORY). INPUTS GadOutline - (struct GadOutline *) Allocated GadOutline or NULL. ErrReport - (GOERR) Error to report if the allocation fails. Size - (ULONG) Number of bytes to allocate. Flags - (ULONG) Standard Exec memory flags. RESULT Address - (void *) Start address of the memory block or NULL. go_LastReqReturn is non-zero if an error occured. TAGS EXAMPLE NOTES . BUGS . SEE ALSO GO_SetErrorA(), GO_ShowErrorA(), FreeGadOutline(), GO_FreeMem() gadoutline.library/GO_AttachHotKey gadoutline.library/GO_AttachHotKey 18 Jul 1993 10:40:46 NAME GO_AttachHotKey -- Connects a hot key to a specific command. SYNOPSIS GO_AttachHotKey(GadOutline, KeyCode, CmdID) A0 D0 D1 void GO_AttachHotKey(struct GadOutline *, ULONG, CMDID) FUNCTION Attaches the given CmdID to the requested hotkey, so that CHM_HOTKEY messages will automatically be sent to the command whenever the corresponding IDCMP_VANILLAKEY or IDCMP_RAWKEY event occurs. The key that this command will be attached to is not directly specified by 'KeyCode.' Rather, this ULONG code is sent to the global translation hook using CHM_TRANSHOTKEY, and the resulting ASCII code is the actual key which is used. This message is sent multiple times so that the code may be translated into more than one actual hotkey; this allows you to, for example, attach the command to both the shifted and unshifted ASCII code. The standard translation hook interprets the lower byte of the code as the desired ASCII character and the upper bits are used as flags to control the translation. See GOCT_SetHotKey in <libraries/gadoutline.h> for more details. INPUTS GadOutline - (struct GadOutline *) Allocated GadOutline. KeyCode - (ULONG) Code to be translated with CHM_TRANSHOTKEY. CmdID - (CMDID) Command to attach to hotkey. RESULT Nothing returned. go_LastReqReturn is non-zero if there was an error. TAGS EXAMPLE NOTES To clear all hotkeys, do GO_AttachHotKey(GadOutline,0,0). This routine will report a level-2 notice if there is already a command attached to the given hotkey. To keep this from happening, you must first clear the hotkey by setting it to a CmdID of 0 before setting it to the actual key you want. Attaching multiple commands to one hotkey using a GrpID is not currently supported. BUGS . SEE ALSO <libraries/gadoutline.h> gadoutline.library/GO_BeginRefresh gadoutline.library/GO_BeginRefresh 18 Jul 1993 14:33:40 NAME GO_BeginRefresh -- Start library-compatible window refreshing. SYNOPSIS GO_BeginRefresh(GadOutline) A0 void GO_BeginRefresh(struct GadOutline *) FUNCTION Begins window refreshing using GT_BeginRefresh and performs redrawing operations needed by the GadOutline. This essentially involves calling DrawGadOutlineA() to send CHM_DRAWSELF messages to all of the commands. INPUTS GadOutline - (struct GadOutline *) Allocated GadOutline. RESULT nothing. go_LastReqReturn is non-zero if there was an error. TAGS EXAMPLE NOTES . BUGS . SEE ALSO GO_EndRefresh(), DrawGadOutlineA(), gadtools/GT_BeginRefresh() gadoutline.library/GO_CallCmdHookA gadoutline.library/GO_CallCmdHookA 16 Jul 1993 08:50:20 NAME GO_CallCmdHookA -- Send a message to a command. SYNOPSIS Result = GO_CallCmdHookA(Command, Message) A0 A1 ULONG GO_CallCmdHookA(struct CmdInfo *, struct CmdHookMsg *) FUNCTION Send a message to the hook(s) attached to the given command. Command is a standard CmdInfo structure retrieved using GO_GetCmdInfo(). If the command has a user hook attached to it, it will be sent there; otherwise, it will be sent to the command's default hook. Currently defined messages: CHM_INITIALIZE - initialize command. Sent during AllocGadOutlineA(). CHM_INITCMDATTR - set initial command tag values. CHM_INITOBJATTR - set initial object tag values. CHM_INITIALIZE - quit/free resources. Sent during FreeGadOutline(). CHM_GETMINDIMENS - query for object's minimum dimensions. CHM_CREATEOBJ - create command's object - set ci_Object. CHM_MADELINK - inform command that another command has linked to it. CHM_DESTROYOBJ - deallocate current object. CHM_HOOKOBJ - connect object to window. CHM_UNHOOKOBJ - detach object from window. CHM_PRERESIZE - get ready to resize current object. CHM_RESIZEOBJ - resize object. CHM_DRAWSELF - draw all visuals not connected to a gadget. CHM_UPDATESTATE - update internal tags/state from the given GOIMsg. CHM_SETCMDATTR - change command tags / refresh imagery if needed. CHM_GETCMDATTR - copy current state of command tags into tag list. CHM_SETOBJATTR - change object tags / refresh imagery if needed. CHM_GETOBJATTR - copy current state of object tags into tag list. CHM_HOTKEY - perform action for hotkey event. See <libraries/gadoutline.h> and supplemental command documentation under command_hooks() for more specific information on these messages. INPUTS Command - (struct CmdInfo *) Command to send message to. Message - (struct CmdHookMsg *) Message to send. RESULT Result - (ULONG) Hook's return code. Meaning is message dependant. go_LastReqReturn is non-zero if an error occured. TAGS EXAMPLE /* Send our own CmdHookMsg to simulate a hot key event */ ULONG do_hotkey(struct GadOutline *go,struct CmdInfo *cmd) { ULONG ret = 0; struct CmdHookMsg msg; struct GOIMsg *event; if( (event = GO_DupGOIMsg(go,NULL)) != NULL ) { /* The standard hook will take anything that is IDCMP_VANILLAKEY, so we can just set the Class field. */ event->StdIMsg.Class = IDCMP_VANILLAKEY; /* Initialize the message. */ msg->chm_Message = CHM_HOTKEY; msg->chm_NumArgs = 0; /* Always set to zero */ msg->chm_KeyGOIMsg = event; ret = GO_CallCmdHookA(cmd,msg) /* You can now examine the modified message */ GO_UndupGOIMsg(event); } return ret; } NOTES The given message structure MUST be able to be modified. This is no problem if you call the varargs version as it will automatically be created on the stack, but if you are passing a pointer to your own CmdHookMsg, it is a good idea to create it on the stack and fill it in. If you absolutely must use a global structure, make sure you initialize _every_ field in it EACH TIME before using it. The default command hook will send any messages that it doesn't understand to the GadOutline's global translation hook by calling GO_CallTransHook(ci->ci_GadOutline,msg). This routine will repeatedly clear the GadOutline's error state and send the message until the hook returns without a go_LastReqReturn value of GORET_RETRY. BUGS . SEE ALSO GO_CallTransHookA(), GO_ContCmdHookA(), <libraries/gadoutline.h> gadoutline.library/GO_CallTransHookA gadoutline.library/GO_CallTransHookA 16 Jul 1993 14:21:13 NAME GO_CallTransHookA -- Send message to global translation hook. SYNOPSIS Result = GO_CallTransHookA(GadOutline, Message) A0 A1 ULONG GO_CallTransHookA(struct GadOutline *, struct CmdHookMsg *) FUNCTION Sends a translation message to the global translation hook(s) attached to the given GadOutline. This is very similar to GO_CallCmdHookA() - see the notes there about restrictions on how the given message may be passed. This hook is primarily used by the library to translate the text strings and other pointers within an outline while first allocating a GadOutline, although it is also used to translate hotkey codes. CHM_TRANSHOTKEY is the only translation message that will be sent by the library after the initial allocation of the GadOutline, but you are free to send other messages to do your own translations. Currently defined translation messages: CHM_TRANSCMDHOOK - return pointer to hook to attach to a CmdInfo CHM_TRANSEDITHOOK - return pointer to an intuition-style edit hook. CHM_TRANSTEXTPTR - return pointer to a null-terminated string. CHM_TRANSTEXTARRAY - return pointer to a null-terminated array of strings. CHM_TRANSTEXTFMT - return pointer to a null-terminated formatting string (ie, a standard C-style format specification). CHM_TRANSPUBCLASS - return a pointer to a string containing the name of a public BOOPSI class. CHM_TRANSPRIVCLASS - return a pointer to an actual instance of a BOOPSI private class. CHM_TRANSHOTKEY - return an ASCII character to use as a hotkey. INPUTS GadOutline - (struct GadOutline *) Previously allocated GadOutline. Message - (struct CmdHookMsg *) The message to send. RESULT Result - (ULONG) The result of the translation; message dependant. go_LastReqReturn is non-zero if an error occured. TAGS EXAMPLE NOTES See GO_CallCmdHookA() for message restrictions. Most of the translation messages that library sends are first sent to a command using GO_CallCmdHookA() and ultimately reach the global translation hook when they enter the root hook, which sends all messages it doesn't understand to the translation hook using GO_CallTransHookA(). This means that the translation hook will receive much more than just translation commands, and is allowed to do something with them, if it is able to without having the information about the CmdInfo they are intended for. This routine will repeatedly clear the GadOutline's error state and send the message until the hook returns without a go_LastReqReturn value of GORET_RETRY. BUGS . SEE ALSO GO_CallCmdHookA(), GO_ContTransHookA(), <libraries/gadoutline.h> translation_hooks() gadoutline.library/GO_CloseLibrary gadoutline.library/GO_CloseLibrary 16 Jul 1993 15:47:11 NAME GO_CloseLibrary -- Close a library opened with GO_OpenLibrary(). SYNOPSIS GO_CloseLibrary(GadOutline, LibBase) A0 A1 void GO_CloseLibrary(struct GadOutline *, struct Library *) FUNCTION Closes the given library which was previously opened with GO_OpenLibrary(). GadOutline must be exactly the same as what was supplied to GO_OpenLibrary(). INPUTS GadOutline - (struct GadOutline *) Same as during GO_OpenLibrary(). LibBase - (struct Library *) Base return by GO_OpenLibrary(). RESULT nothing. TAGS EXAMPLE NOTES ONLY use this with a library that was opened with GO_OpenLibrary(). BUGS . SEE ALSO GO_OpenLibrary() gadoutline.library/GO_CloseScreen gadoutline.library/GO_CloseScreen 18 Jul 1993 04:34:02 NAME GO_CloseScreen -- Detach current screen from GadOutline. SYNOPSIS GO_CloseScreen(GadOutline) A0 void GO_CloseScreen(struct GadOutline *) FUNCTION Detaches the current screen from the given GadOutline. If this screen was opened with GO_OpenScreenA(), it will automatically be closed. If the library has any locks on it, they will be released. This is used by UpdateGadOutlineA() when a screen or window tag is specified which changes the GadOutline's screen. INPUTS GadOutline - (struct GadOutline *) Allocated GadOutline. RESULT nothing. TAGS EXAMPLE NOTES GO_CloseWindowA() will be called if there is a window attached to the GadOutline. BUGS . SEE ALSO GO_OpenScreenA(), GO_CloseWindow() gadoutline.library/GO_CloseWindow gadoutline.library/GO_CloseWindow 18 Jul 1993 08:37:26 NAME GO_CloseWindow -- Close / detach any window connected to GadOutline. SYNOPSIS GO_CloseWindow(GadOutline) A0 void GO_CloseWindow(struct GadOutline *) FUNCTION Disassociates given GadOutline from any window currently attached to it. If the window was opened using GO_OpenWindowA(), it will be detached from any menu strip and custom user port, have its position saved if GOA_SaveWinDimens is TRUE, and be closed. This called by UpdateGadOutlineA() when GOA_WindowAddr is specified with a different address than the current window. INPUTS GadOutline - (struct GadOutline *) Allocated GadOutline. RESULT nothing. TAGS EXAMPLE NOTES . BUGS . SEE ALSO GO_OpenWindowA(), GO_CloseScreen() gadoutline.library/GO_CmdAtPointA gadoutline.library/GO_CmdAtPointA 18 Jul 1993 12:03:13 NAME GO_CmdAtPointA -- Determine command(s) covering a certain point SYNOPSIS Command = GO_CmdAtPointA(GadOutline, Message, PrevCmd, TagList) A0 A1 A2 A3 struct CmdInfo *GO_CmdAtPointA(struct GadOutline *, struct GOIMsg *, struct CmdInfo *, struct TagItem *) FUNCTION Finds the commands whose boxes cover the given point within the message's MouseX and MouseY fields. The operation is similar to GO_GetCmdInfo(), except that the x and y coordinates are used to filter the messages rather than a CmdID search pattern. NULL is returned after all of the commands have been searched. The only fields which are looked at in the message are MouseX and MouseY, so you can do a search without already having a message by allocating a new message with GO_DupGOIMsg(GadOutline,NULL) and filling in those two fields with the point you wish to search for. INPUTS GadOutline - (struct GadOutline *) Allocated GadOutline. Message - (struct GOIMsg *) Message to take coordinates from. PrevCmd - (struct CmdInfo *) Previously returned command. TagList - (struct TagItem *) Control tags. No tags defined. RESULT Command - (struct CmdInfo *) Command found at the point. go_LastReqReturn is non-zero if there was an error. TAGS EXAMPLE NOTES All commands which have a BoxAttr will be returned; this currently includes boxes, groups and images. You will need to do more filtering yourself if you only want to look at specific kinds. BUGS . SEE ALSO GO_GetCmdInfo(), GO_GetBoxAttr(), GO_DupGOIMsg() gadoutline.library/GO_ContCmdHookA gadoutline.library/GO_ContCmdHookA 16 Jul 1993 09:39:23 NAME GO_ContCmdHookA -- Continue a message within a hook. SYNOPSIS Result = GO_ContCmdHookA(Command, Message) A0 A1 ULONG GO_ContCmdHookA(struct CmdInfo *, struct CmdHookMsg *) FUNCTION Passes the processing of a message to the command's hook below the caller. You will normally want to allow the standard message processing to occur by calling this function. INPUTS Command - (struct CmdInfo *) Command to send message to. Message - (struct CmdHookMsg *) Message to send. RESULT Result - (ULONG) Hook's return code. Meaning is message dependant. go_LastReqReturn is non-zero if an error occured. TAGS EXAMPLE NOTES This function should only be called within a user hook. Never modify any of the fields within the message; you must pass the exact message that your hook received. BUGS . SEE ALSO GO_CallCmdHookA(), <libraries/gadoutline.h> gadoutline.library/GO_ContTransHookA gadoutline.library/GO_ContTransHookA 16 Jul 1993 14:52:09 NAME GO_ContTransHookA -- Continue a message within a translation hook. SYNOPSIS Result = GO_ContTransHookA(GadOutline, Message) A0 A1 ULONG GO_ContTransHookA(struct GadOutline *, struct CmdHookMsg *) FUNCTION Passes the processing of a message to the library's builtin translation hook. You will usually only need to do this for messages that you do not understand or for which you are happy with the standard handling of the message. INPUTS GadOutline - (struct GadOutline *) A previously allocated GadOutline. Message - (struct CmdHookMsg *) Message to send. RESULT Result - (ULONG) Hook's return code. Meaning is message dependant. go_LastReqReturn is non-zero if an error occured. TAGS EXAMPLE NOTES This function should only be called within a user hook. Never modify any of the fields within the message; you must pass the exact message that your hook received. BUGS . SEE ALSO GO_CallTransHookA(), <libraries/gadoutline.h> gadoutline.library/GO_DupGOIMsg gadoutline.library/GO_DupGOIMsg 18 Jul 1993 10:12:49 NAME GO_DupGOIMsg -- Duplicate a GOIMsg or IntuiMessage. SYNOPSIS NewMessage = GO_DupGOIMsg(GadOutline, Message) A0 A1 struct GOIMsg *GO_DupGOIMsg(struct GadOutline *, struct GOIMsg *) FUNCTION Allocates a new GOIMsg and copies the given message into it. There are three distinct operations that can be performed: If 'Message' is a GOIMsg, a direct copy will be performed. If 'Message' is an IntuiMessage, all of the IntuiMessage fields will be copied into the corresponding fields in the GOIMsg. If 'Message' is NULL, a brand new GOIMsg will be allocated and initialized. You currently should not count on any of the fields of the new GOIMsg being set to sane values. INPUTS GadOutline - (struct GadOutline *) An allocated GadOutline. Message - (struct GOIMsg *) Message to duplicate. RESULT NewMessage - (struct GOIMsg *) The newly allocated message or NULL if unable to allocate any memory. go_LastReqReturn is non-zero if there was an error. TAGS EXAMPLE NOTES The ExecMessage within the IntuiMessage part of the GOIMsg is reserved for private use by the library and should not touched or looked at in any way. This message is attached to the supplied GadOutline and will be free'd at the time that the GadOutline is free'd. Supplying a NULL GadOutline will result in first trying to use any GadOutline attached to the given message (ie, calling GO_GetGOFromGOIMsg) and, if that fails, not attaching it to any GadOutline. ReplyMsg() should never be called with a duplicated message. BUGS . SEE ALSO GO_UndupGOIMsg(), GO_GetGOFromGOIMsg() gadoutline.library/GO_EndRefresh gadoutline.library/GO_EndRefresh 18 Jul 1993 14:38:01 NAME GO_EndRefresh -- Finishes window refreshing. SYNOPSIS GO_EndRefresh(GadOutline, Complete) A0 D0 void GO_EndRefresh(struct GadOutline *, BOOL) FUNCTION Calls GT_EndRefresh() to finish window refreshing mode and does all special operations needed by library. INPUTS GadOutline - (struct GadOutline *) Allocated GadOutline. Complete - (BOOL) TRUE if this is really the end. RESULT nothing. go_LastReqReturn is non-zero if there was an error. TAGS EXAMPLE NOTES . BUGS . SEE ALSO GO_BeginRefresh(), DrawGadOutline(), gadtools/GT_EndRefresh() gadoutline.library/GO_FilterGOIMsg gadoutline.library/GO_FilterGOIMsg 18 Jul 1993 13:19:16 NAME GO_FilterGOIMsg -- Send message to library for special processing. SYNOPSIS NewMsg = GO_FilterGOIMsg(GadOutline, Message) A0 A1 struct GOIMsg *GO_FilterGOIMsg(struct GadOutline *, struct IntuiMessage *) FUNCTION Performs library-specific filtering and massaging of a raw IntuiMessage before being ready for the application to look at. This includes executing hot keys, tracking the gadgets' states, and watching for window resizing and resize verify events. Extended message information is supplied in the GOIMsg structure, in addition to that already provided by Intuition and GadTools. If the message is a IDCMP_RAWKEY or IDCMP_VANILLAKEY event, the KeyPress field will contain the translated key event. For IDCMP_VANILLAKEY this is just a string with a single character corresponding to the message's code. IDCMP_RAWKEY events will be translated using MapRawKey(), with the resulting string stored in KeyPress. The high bit of the raw key codes is cleared before mapping so that both key down and up events will have a KeyPress. The UserData field of the message is free to be used by the user's custom hook or whatever else. The returned message may be NULL if the library ate it, in which case you will still need to call GO_PostFilterGOIMsg() to retrieve the original message. After you have called GO_PostFilterGOIMsg(), you should call GO_FilterGOIMsg() with a NULL message to retrieve any additional messages that have been generated, and then release them with GO_PostFilterGOIMsg(). This is similar to GadTools' GT_FilterIMsg(). INPUTS GadOutline - (struct GadOutline *) . Message - (struct IntuiMessage *) . RESULT NewMsg - (struct GOIMsg *) The message you should use. go_LastReqReturn is non-zero if there was an error. TAGS EXAMPLE NOTES This function does not call GT_FilterIMsg(). You will need to do that before calling it. BUGS . SEE ALSO GO_PostFilterGOIMsg(), GO_GetGOIMsg(), gadtools/GT_FilterIMsg() gadoutline.library/GO_FreeMem gadoutline.library/GO_FreeMem 16 Jul 1993 15:23:09 NAME GO_FreeMem -- Free a block of memory allocated with GO_AllocMem(). SYNOPSIS GO_FreeMem(Address) A0 void GO_FreeMem(void *) FUNCTION Frees the memory located at the given address and unlinks it if it was attached to a GadOutline. INPUTS Address - (void *) Memory base address returned by GO_AllocMem(). RESULT nothing. TAGS EXAMPLE NOTES ONLY use this with memory that was allocated with GO_AllocMem(). BUGS . SEE ALSO GO_AllocMem() gadoutline.library/GO_GetBoxAttr gadoutline.library/GO_GetBoxAttr 17 Jul 1993 02:52:53 NAME GO_GetBoxAttr -- Find the given BoxAttr structure. SYNOPSIS Box = GO_GetBoxAttr(GadOutline, SearchID, PrevBox) A0 D0 A1 struct BoxAttr *GO_GetBoxAttr(struct GadOutline *, CMDID, struct BoxAttr *) FUNCTION This is identical to GO_GetCmdInfo() except that it limits the search to commands whose ci_CmdData points to a BoxAttr. This currently includes all groups, boxes and images. See GO_GetCmdInfo() for more information. INPUTS GadOutline - (struct GadOutline *) Allocated GadOutline. SearchID - (CMDID) ID code(s) to search for. PrevBox - (struct BoxAttr *) Previous box that was found. RESULT Box - (struct BoxAttr *) The box that was found. TAGS EXAMPLE /* Get only commands of type GOK_Box with the given size */ struct BoxAttr *get_boxes(struct GadOutline *go, WORD width, WORD height, struct BoxAttr *prev) { while( (prev = GO_GetBoxAttr(go,0,prev)) != NULL ) { if( prev->ba_BoxWidth == width && prev->ba_BoxHeight == height ) { if( GETCMDKIND(prev->ba_CmdInfo) == GOK_Box ) { return prev; } } } return NULL; } NOTES . BUGS . SEE ALSO GO_GetCmdInfo() gadoutline.library/GO_GetCmdAttr gadoutline.library/GO_GetCmdAttr 18 Jul 1993 09:26:57 NAME GO_GetCmdAttr -- Get the value of a single command tag. SYNOPSIS Value = GO_GetCmdAttr(GadOutline, StdID, Flags, GetTag, DefaultValue) A0 D0 D1 D2 D3 ULONG GO_GetCmdAttr(struct GadOutline *, CMDID, ULONG, Tag, ULONG) FUNCTION Calls GO_GetCmdAttrsA() to retrieve the given tag. INPUTS GadOutline - (struct GadOutline *) Allocated GadOutline. StdID - (CMDID) ID of command to retrieve from. Flags - (ULONG) Reserved. Always set to zero. GetTag - (Tag) Tag to retrieve. DefaultValue - (ULONG) Default value to supply if not found. RESULT Value - (ULONG) Value in tag or DefaultValue if it doesn't exist. go_LastReqReturn is non-zero if there was an error. TAGS EXAMPLE NOTES . BUGS . SEE ALSO GO_SetCmdAttrsA() gadoutline.library/GO_GetCmdAttrsA gadoutline.library/GO_GetCmdAttrsA 18 Jul 1993 09:15:20 NAME GO_GetCmdAttrsA -- Retrieve the given command tags from a command. SYNOPSIS GO_GetCmdAttrsA(GadOutline, StdID, Flags, TagList) A0 D0 D1 A1 void GO_GetCmdAttrsA(struct GadOutline *, CMDID, ULONG, struct TagItem *) FUNCTION Fills in the given tag list with the current command tag state of the command which has the given ID. This essentially involves finding the command using GO_GetCmdInfo() and sending it a CHM_GETCMDATTR message with the given tag list. While the actual action performed is command-dependant, the standard hook will fill in the given tag list from its local command tags and then fill in any tags it understands with its current state information. INPUTS GadOutline - (struct GadOutline *) Allocated GadOutline. StdID - (CMDID) The ID of a single command to get tags from. Flags - (ULONG) Reserved. Always set to zero. TagList - (struct TagItem *) Tags to retrieve. RESULT No return value. go_LastReqReturn is non-zero if there was an error. TAGS EXAMPLE NOTES None of the standard hooks currently copy their state into the supplied tags, so the only values you will get are what is in the command's tag list. This means that you must supply all tags whose state you want to track when you allocate the GadOutline. BUGS . SEE ALSO GO_GetCmdAttr(), GO_SetCmdAttrsA(), GO_GetCmdInfo() gadoutline.library/GO_GetCmdInfo gadoutline.library/GO_GetCmdInfo 16 Jul 1993 15:56:17 NAME GO_GetCmdInfo -- Find the CmdInfo structure with the given CmdID. SYNOPSIS Command = GO_GetCmdInfo(GadOutline, SearchID, PrevCmd) A0 D0 A1 struct CmdInfo *GO_GetCmdInfo(struct GadOutline *, CMDID, struct CmdInfo *) FUNCTION This is the only defined way to extract a CmdInfo from a GadOutline. It can be used to find either a single command, or a group of commands with simlar IDs. A CmdID is a long-word quantity divided into 2 fields. The lower 12 bits are the StdID, an ID number unique to this single command. The upper 20 bits are the GrpID, which is used to describe groupings between similar commands and is itself divided into 2 parts, an 8 bit CODE field and a 12 bit MASK. All commands must have a unique StdID, except for the special value of 0, which means "don't care." The StdID is the primary method used to refer to commands, so any commands with an ID of 0 will be unable to be the object of TagLinks, hot keys, etc. The exact meaning placed on the GrpID is program-dependant. Typically, it will be used to do things like assign a MASK bit to commands that need to be disabled at the same time, so that this can be accomplished with a single call to GO_SetObjGrpAttrsA(). When extracting a single CmdInfo from a GadOutline, this function is called with the ID value in SearchID and a NULL PrevCmd. The StdID and MASK and CODE GrpIDs within the SearchID are each treated as independant search components; a zero in any of them is given the special meaning "match anything" and will be ignored during the search. For a complete match to occur, ALL non-zero fields must identically match the command's assigned CmdID. [Note that in this case each bit of the GrpID MASK is treated as a separate field.] So, to find a command assigned to a StdID, the SearchID will simply be the StdID; the GrpID portion of the search will be 0 to ignore whatever the command's GrpID may be. When searching for multiple commands, this function is first called with PrevCmd NULL, and then repetatively called with PrevCmd set to the value the previous call returned. A NULL will be returned when all of the matching commands have been found. In this case, you will likely want to set the StdID to 0; otherwise, you will only be returned the single StdID that matches the given SearchID. When searching for multiple commands using the GrpIDs, the CODE field behaves identically to a StdID, except that multiple commands may have the same CODE and all of those that match will be returned. The MASK field is a little bit different; each bit in the SearchID can be set or cleared to identify which bits you want to look for This, a SearchID with GO_GRPID_A will match commands with GrpIDs of GO_GRPID_A, GO_GRPID_A | GO_GRPID_B, etc. INPUTS GadOutline - (struct GadOutline *) Allocated GadOutline. SearchID - (CMDID) ID code(s) to search for. PrevCmd - (struct CmdInfo *) Previous command that was found. RESULT Command - (struct CmdInfo *) The command that was found. TAGS EXAMPLE Assuming you have three commands in your GadOutline assigned: Cmd1: GO_CMDID( 0, 1 ) Cmd2: GO_CMDID( GO_GRPID_A, 2 ) Cmd3: GO_CMDID( GO_GRPID_A | GO_GRPID_B, 3 ) Cmd4: GO_CMDID( GO_GRPID_A | 100, 4 ) Cmd5: GO_CMDID( GO_GRPID_B | 100, 5 ) Cmd6: GO_CMDID( GO_GRPID_A | GO_GRPID_B | 100, 6 ) Cmd7: GO_CMDID( 0, 0 ) A SearchID of 1 will return only Cmd1, of 2 only Cmd2, etc. A SearchID of GO_CMDID(GO_GRPID_B,0) will return Cmd3, Cmd5, Cmd6. GO_CMDID(GO_GRPID_A|GO_GRPID_A,0) will return Cmd3 and Cmd6. GO_CMDID(GO_GRPID_A|100,0) will return Cmd4 and Cmd6. GO_CMDID(0,0) will return all commands, including Cmd7. /* Tell every command to draw itself. */ void draw_all(struct GadOutline *go) { struct CmdInfo *ci; ci = NULL; while( (ci = GO_GetCmdInfo(go,0,ci)) != NULL ) { GO_CallCmdHook(ci,CHM_DRAWSELF,0); } } NOTES If multiple commands within the GadOutline have the same StdID, this function's behaviour is undefined and will likely change. The order that multiple commands are returned to you is currently not defined; do not depend on getting them in any particular order. Never change the SearchID you are using in the middle of finding a group of commands. When a CmdInfo is returned, it will be set as the current command for GO_InterpretTypedSize() and GO_ParseTypedSizeListA(). BUGS . SEE ALSO GO_GetBoxAttr() gadoutline.library/GO_GetErrorCode gadoutline.library/GO_GetErrorCode 17 Jul 1993 04:06:22 NAME GO_GetErrorCode -- Get GadOutline's current error code. SYNOPSIS Error = GO_GetErrorCode(GadOutline) A0 GOERR GO_GetErrorCode(struct GadOutline *) FUNCTION Extracts the current ErrorCode from the given GadOutline and returns it. INPUTS GadOutline - (struct GadOutline *) An allocated GadOutline. RESULT Error - (GOERR) The current error. TAGS EXAMPLE NOTES . BUGS . SEE ALSO GO_SetErrorA(), GO_GetErrorText(), GO_GetErrorObject(), GO_ShowErrorA() gadoutline.library/GO_GetErrorObject gadoutline.library/GO_GetErrorObject 17 Jul 1993 04:11:39 NAME GO_GetErrorObject -- Returns the object of the current error code. SYNOPSIS Object = GO_GetErrorObject(GadOutline) A0 void *GO_GetErrorObject(struct GadOutline *) FUNCTION Returns the object attached to the GadOutline's current error code. What this value actual is depends on the error code; The currently defined codes are: GOCODE_MEMORY - (ULONG) - the memory size needed. GOCODE_OPENLIB - (UBYTE *) - the name of the library. GOCODE_OPENFONT - (struct TextAttr *) - font trying to open. GOCODE_INTERR - (ULONG) - Internal error identifier. Private. GOCODE_BADARGS - (ULONG) - Internal error identifier. Private. GOCODE_OUTBOUNDS - (ULONG) - Offset from start of outline array. GOCODE_MALFORMED - (struct CmdInfo *) - Pointer to current command. GOCODE_NOBOXGROUP - (struct CmdInfo *) - Pointer to current command. GOCODE_UNKNOWNCMD - (struct CmdInfo *) - Pointer to current command. GOCODE_BADENDGRP - (struct CmdInfo *) - Pointer to current command. GOCODE_NOGROUPS - (struct CmdInfo *) - Pointer to current command. GOCODE_EXTRAROOTGRP - (struct CmdInfo *) - Pointer to current cmd. GOCODE_BADGROUP - (struct CmdInfo *) - Pointer to current command. GOCODE_BADHKCMD - (struct CmdInfo *) - Pointer to current command. GOCODE_CREATEOBJ - (struct CmdInfo *) - Pointer to current command. GOCODE_BADCMDID - (CMDID) - The given CmdID. GOCODE_DUPSTDID - (CMDID) - The given CmdID. GOCODE_NOCMDID - (CMDID) - The given CmdID. GOCODE_DUPHOTKEY - (UBYTE) - The requested hot key. GOCODE_BADTYPEDSIZE - (TYPEDSIZE) - The given TypedSize. GOCODE_OPENPUBSCRN - (UBYTE *) - Name of the public screen. GOCODE_VISUALINFO - (struct Screen *) - Screen tried to get from. GOCODE_DRAWINFO - (struct Screen *) - Screen tried to get from. GOCODE_OPENWIN - (struct TagItem *) - Window's tag list. INPUTS GadOutline - (struct GadOutline *) An allocated GadOutline. RESULT Object - (void *) Object attached to the current error. TAGS EXAMPLE NOTES . BUGS . SEE ALSO GO_SetErrorA(), GO_GetErrorCode(), GO_GetErrorText(), GO_ShowErrorA() gadoutline.library/GO_GetErrorText gadoutline.library/GO_GetErrorText 17 Jul 1993 04:08:20 NAME GO_GetErrorText -- Get GadOutline's current error text. SYNOPSIS Description = GO_GetErrorText(GadOutline) A0 UBYTE *GO_GetErrorText(struct GadOutline *) FUNCTION Returns a string describing the current error code of the given GadOutline. This is the string that is printed in the second line of an error requester, without the trailing '.'. INPUTS GadOutline - (struct GadOutline *) An allocate GadOutline. RESULT Description - (UBYTE *) A string descriping the current error. TAGS EXAMPLE NOTES . BUGS . SEE ALSO GO_SetErrorA(), GO_GetErrorCode(), GO_GetErrorObject(), GO_ShowErrorA() gadoutline.library/GO_GetGOFromGOIMsg gadoutline.library/GO_GetGOFromGOIMsg 18 Jul 1993 10:00:14 NAME GO_GetGOFromGOIMsg -- Find the GadOutline this message belongs to. SYNOPSIS MsgGO = GO_GetGOFromGOIMsg(Message) A0 struct GadOutline *GO_GetGOFromGOIMsg(struct GOIMsg *) FUNCTION Returns the GadOutline that owns this message, ie the one that allocated it using GO_DupGOIMsg(). Note that this may not be the GadOutline that the original IntuiMessage is associated with, although this situation should be avoided and the library will never create a message like this without being explicately told to. Passing this function an IntuiMessage rather than an actual GOIMsg is allowed and will result in it falling back to GO_GetGOFromImsg(). INPUTS Message - (struct GOIMsg *) A valid GadOutline message. RESULT MsgGO - (struct GadOutline *) The message's GadOutline. TAGS EXAMPLE NOTES . BUGS . SEE ALSO GO_GetGOFromIMsg(), GO_DupGOIMsg(), GO_GetGOIMsg() gadoutline.library/GO_GetGOFromIMsg gadoutline.library/GO_GetGOFromIMsg 18 Jul 1993 09:55:21 NAME GO_GetGOFromIMsg -- Find the GadOutline associated with this message. SYNOPSIS MsgGO = GO_GetGOFromIMsg(Message) A0 struct GadOutline *GO_GetGOFromIMsg(struct IntuiMessage *) FUNCTION Retrieves the GadOutline that owns the window from which this IntuiMessage came. The library uses the window's UserData field as a back-pointer to the GadOutline that is attached to the window, but you should call this function rather than directly accessing the field yourself. INPUTS Message - (struct IntuiMessage *) An IntuiMessage from Intuition. RESULT MsgGO - (struct GadOutline *) This message's window's GadOutline. TAGS EXAMPLE NOTES . BUGS . SEE ALSO GO_GetGOFromGOIMsg() gadoutline.library/GO_GetGOIMsg gadoutline.library/GO_GetGOIMsg 18 Jul 1993 13:41:22 NAME GO_GetGOIMsg -- Retrieves next available GOIMsg. SYNOPSIS Message = GO_GetGOIMsg(GadOutline) A0 struct GOIMsg *GO_GetGOIMsg(struct GadOutline *) FUNCTION Returns next message which the application should process. Standard intuition messages will be retrieved from the GadOutline's message port pointed to by go_MsgPort using GadTools' GT_GetIMsg() function. This message will then be sent to GO_FilterGOIMsg() for processing and the result returned by this function. See GO_FilterGOIMsg() for more information. INPUTS GadOutline - (struct GadOutline *) Allocated GadOutline. RESULT Message - (struct GOIMsg *) Next message to process. go_LastReqReturn is non-zero if there was an error. TAGS EXAMPLE NOTES . BUGS . SEE ALSO GO_DupGOIMsg(), GO_ReplyGOIMsg(), GO_FilterGOIMsg(), gadtools/GT_GetIMsg() gadoutline.library/GO_GetObjAttr gadoutline.library/GO_GetObjAttr 18 Jul 1993 09:38:45 NAME GO_GetObjAttr -- Get the value of a single object tag. SYNOPSIS Value = GO_GetObjAttr(GadOutline, StdID, Flags, GetTag, DefaultValue) A0 D0 D1 D2 D3 ULONG GO_GetObjAttr(struct GadOutline *, CMDID, ULONG, Tag, ULONG) FUNCTION Calls GO_GetObjAttrsA() to retrieve the given tag. INPUTS GadOutline - (struct GadOutline *) Allocated GadOutline. StdID - (CMDID) ID of command to retrieve from. Flags - (ULONG) Reserved. Always set to zero. GetTag - (Tag) Tag to retrieve. DefaultValue - (ULONG) Default value to supply if not found. RESULT Value - (ULONG) Value in tag or DefaultValue if it doesn't exist. go_LastReqReturn is non-zero if there was an error. TAGS EXAMPLE NOTES . BUGS . SEE ALSO GO_SetCmdAttrsA() gadoutline.library/GO_GetObjAttrsA gadoutline.library/GO_GetObjAttrsA 18 Jul 1993 09:33:50 NAME GO_GetObjAttrsA -- Retrieve the given object tags from a command. SYNOPSIS GO_GetObjAttrsA(GadOutline, StdID, Flags, TagList) A0 D0 D1 A1 void GO_GetObjAttrsA(struct GadOutline *, CMDID, ULONG, struct TagItem *) FUNCTION Fills in the given tag list with the current object tag state of the command which has the given ID. This essentially involves finding the command using GO_GetCmdInfo() and sending it a CHM_GETOBJATTR message with the given tag list. While the actual action performed is command-dependant, the standard hook will fill in the given tag list from its local objects tags. Higher-level hooks may fill in the tags with more information; for example, a BOOPSI hook may call GetAttrs() for each tag in the list. INPUTS GadOutline - (struct GadOutline *) Allocated GadOutline. StdID - (CMDID) The ID of a single command to get tags from. Flags - (ULONG) Reserved. Always set to zero. TagList - (struct TagItem *) Tags to retrieve. RESULT No return value. go_LastReqReturn is non-zero if there was an error. TAGS EXAMPLE NOTES . BUGS . SEE ALSO GO_GetObjAttr(), GO_SetObjAttrsA(), GO_GetCmdInfo() gadoutline.library/GO_InterpretTypedSizegadoutline.library/GO_InterpretTypedSize 16 Jul 1993 13:13:14 NAME GO_InterpretTypedSize -- Return the value of a single TypedSize. SYNOPSIS Value = GO_InterpretTypedSize(GadOutline, CurrentValue, TypedSize) A0 D0 D1 LONG GO_InterpretTypedSize(struct GadOutline *, LONG, TYPEDSIZE) FUNCTION Computes the actual value for a typed size. A typed size is a single ULONG quantity composed of three fields - the mode, type and quantity. The type is one of the GOT_* values and describes how to interpret the number in quantity. For example, GOT_PercCharW is a type which says that the quantity is units of percentages of a character width. These two fields combined produce an absolute number, and the mode field then describes an operation to perform between this computed number and the previous one passed in CurrentValue. The various types available can be broken down into three major groups. The first are miscellaneous units based on global layout information - character width and height, layout minimum and maximum dimensions. The type GOT_Pixels uses the value as an absolute number and GOT_PercScale is used to scale the given CurrentValue by a percentage in the value field. The next group operates on text strings. Types are provided to find the width and height of a text string, and the minimum, maximum and addition of these dimensions for multiple strings. In addition, the strings can also be viewed in terms of characters and lines. Finally, the largest group is based on the dimensions of a command. The more important types are GOT_PercBoxW and GOT_PercBoxH, which provide the current complete size of the box; GOT_PercUnusedW and GOT_PercUnusedH are the amount of extra spacing assigned to a box which it has not used yet. See the header file for a complete description of these types. A special type is GOT_BoxSize. Its value field is not intepreted as a number, but rather the lower 12 bits are interpreted as the StdID of a BoxAttr's command and the upper 4 bits are used to identify a particular dimension of the box to extract. There are currently six modes available. GOM_Set simply returns the computed type and value, and ignores CurrentValue. GOM_Max returns the larger of the computed and given values while GOM_Min returns the smaller. GOM_Add adds the two values together, GOM_Mul multiplies them, and GOM_Div divides the given CurrentValue by the newly computed value. INPUTS GadOutline - (struct GadOutline *) Previously allocated GadOutline. CurrentValue - (LONG) The value to start out with. TypedSize - (TYPEDSIZE) The typed size to interpret. RESULT Value - (LONG) The final computed result. TAGS EXAMPLE Assuming the current font is Topaz 8: GO_InterpretTypedSize(go, 20, GO_TSIZE(GOM_Set,100,GOT_Pixels)) ==> 100 GO_InterpretTypedSize(go, 20, GO_TSIZE(GOM_Set,100,GOT_PercCharH)) ==> 8 GO_InterpretTypedSize(go, 20, GO_TSIZE(GOM_Add,100,GOT_PercCharH)) ==> 28 GO_InterpretTypedSize(go, 20, GO_TSIZE(GOM_Add,-100,GOT_PercCharH)) ==> 12 GO_InterpretTypedSize(go, 20, GO_TSIZE(GOM_Max,100,GOT_Pixels)) ==> 100 GO_InterpretTypedSize(go, 20, GO_TSIZE(GOM_Min,100,GOT_Pixels)) ==> 20 NOTES To do a subtraction, use GOM_Add and a negative value field. The upper bits of the mode field, which flag the particular SPC, PAD and VAR components to modify, are ignored by this function except when using complex units, which can have different values for each of the components. Many of the types depend on previously set state information. In particular, all of the ones that refer to various dimensions of a command's BoxAttr need to know which command to look at. If you are calling this function within a user hook, this value will always have been set to point to your command. Otherwise, you can explicately set the current command by calling GO_GetCmdInfo() with the ID of the command you want to look at. The text size types - GOT_PercText* - need to have one or more text strings to refer to. These can be set by calling GO_ParseTypedSizeListA() with the appropriate tags; they will remain in context for subsequent calls to GO_InterpretTypedSize(). BUGS . SEE ALSO GO_ParseTypedSizeListA(), GO_GetCmdInfo(), <libraries/gadoutline.h> gadoutline.library/GO_OpenLibrary gadoutline.library/GO_OpenLibrary 16 Jul 1993 15:35:50 NAME GO_OpenLibrary -- Open a standard system library. SYNOPSIS LibBase = GO_OpenLibrary(GadOutline, ErrReport, Name, Version) A0 D0 A1 D1 struct Library *GO_OpenLibrary(struct GadOutline *, GOERR, UBYTE *, ULONG) FUNCTION Opens the specified library and returns its base address. This library is NOT currently tracked by the system; you will have to free it yourself. ErrReport specifies what to do if the library can not be opened. If it is 0, the library will simply return NULL. Otherwise, it is interpreted as a standard error code and the library will call GO_SetError() with the given error if unable to open the library. If the selected error has a RETRY choice, the library will attempt to open it if this is selected; if it is then able to get it, the caller will never know there was a problem. A shortcut is provided in specifying the error. If the error type field is zero, the library will interpret the code field as the type and automatically use the library code - ie, GO_MAKEERR(GETERRCODE(ErrReport),GOCODE_OPENLIB). INPUTS GadOutline - (struct GadOutline *) Allocate GadOutline or NULL. ErrReport - (GOERR) Error to report if the allocation fails. Name - (UBYTE *) Name of the library to open. Version - (ULONG) Minimum version of the library. RESULT LibBase - (struct Library *) The base address of the library or NULL. go_LastReqReturn is non-zero if an error occured. TAGS EXAMPLE NOTES While the library is not currently tracked and closed when FreeGadOutline() is called, this may be added in the future, so always be sure to call GO_CloseLibrary() before freeing a GadOutline used with GO_OpenLibrary(). BUGS . SEE ALSO GO_SetErrorA(), GO_ShowErrorA(), GO_CloseLibrary() gadoutline.library/GO_OpenScreenA gadoutline.library/GO_OpenScreenA 18 Jul 1993 04:27:18 NAME GO_OpenScreenA -- GadOutline open screen interface. SYNOPSIS Screen = GO_OpenScreenA(GadOutline, TagList) A0 A1 struct Screen *GO_OpenScreenA(struct GadOutline *, struct TagItem *) FUNCTION Not currently implemented. The general algorithm for doing a font-sensitive OpenScreen() is: - AllocGadOutline() - DimenGadOutline() with the DisplayID and overscan mode you will be using, and any other information you care about such as font preferece. - OpenScreen() with the resulting font in go_TextAttr (NOTE: You must make a copy of this to use, as there is no guarantee that it will not change.) - GO_OpenWindow() on the new screen. INPUTS GadOutline - (struct GadOutline *) Allocate GadOutline. TagList - (struct TagItem *) Standard screen tags (SA_*). RESULT Screen - (struct Screen *) A newly opened screen or NULL. go_LastReqReturn is non-zero if there was an error. TAGS EXAMPLE NOTES . BUGS . SEE ALSO GO_OpenWindowA(), GO_CloseScreen(), intuition/OpenScreen() gadoutline.library/GO_OpenWindowA gadoutline.library/GO_OpenWindowA 18 Jul 1993 04:38:30 NAME GO_OpenWindowA -- GadOutline open window interface. SYNOPSIS Window = GO_OpenWindowA(GadOutline, TagList) A0 A1 struct Window *GO_OpenWindowA(struct GadOutline *, struct TagItem *) FUNCTION Opens a window and attaches it to the given GadOutline. The tags passed to OpenWindow() are the combination of the tag list passed to the function and the object tags of a GO_WINDOWTAGS() command within the outline, if it is supplied. If a tag appears in both the GO_OpenWindowA() list and GO_WINDOWTAGS() list, the former will override the later. The screen to open the window on is derived in the following way: WA_PubScreen will be sent to DimenGadOutlineA() as GOA_ScreenAddr; the resulting screen in go_Screen will be used in the WA_PubScreen tag. WA_CustomScreen will be sent to DimenGadOutlineA() as GOA_ScreenAddr; the resulting screen in go_Screen will be used in the WA_CustomScreen tag. WA_PubScreenName and WA_PubScreenFallBack will be sent to DimenGadOutlineA() as GOA_ScreenName and GOA_ScreenFallBack. If WA_PubScreen is not supplied, GOA_ScreenFallBack will be FALSE. The resulting screen will then be used in a WA_PubScreen tag and the original WA_PubScreenName is removed from the tag list. If none of these tags are present, the window will be opened on the current screen attached to the GadOutline. If no screen is attached, DimenGadOutlineA() with { GOA_ScreenAddr, NULL } will be called to attempt to lock the default public screen. In either case, the screen address will be passed using WA_PublicScreen if it is a public screen the library has a lock on, or WA_CustomScreen if it was attached to the GadOutline using a non-NULL GOA_ScreenAddr. If any error has occured at this point, any screen will be detached from the GadOutline and a NULL will be returned. The window's default dimensions are determined by the GOA_WindowRelative flag; if non-NULL the default width and height will be the current minimum inner width of the layout (or full width if WA_AutoAdjust is FALSE) and the left and top edges will be set such that the window is positioned within the screen's current viewable area and not obscuring its title bar. Otherwise, they will all be initialized to zero. These default dimensions are then modified by the following tags: WA_InnerWidth will be added to the window's default width. If not specified and GOA_SaveWinDimens is TRUE, the previous width of the window will be used. WA_InnerHeight will be added to the window's default height. If not specified and GOA_SaveWinDimens is TRUE, the previous height of the window will be used. WA_Width and WA_Height will completely override the default width and height. WA_Left will be added to the window's default left edge. If not specified and GOA_SaveWinDimens is TRUE, the previous left edge of the window will be used. WA_Top will be added to the window's default top edge. If not specified and GOA_SaveWinDimens is TRUE, the previous top edge of the window will be used. The rest of the tags are passed as-is to OpenWindow(), except for the following modifications: WA_AutoAdjust will be TRUE by default. You must explicately set it to FALSE if this is not what you want. WA_MinWidth and WA_MinHeight will, if not specified, be set to the minimum dimensions of the layout. WA_MaxWidth and WA_MaxHeight will, if not specified, be set to ~0. WA_IDCMP may will have additional flags added to it if GOA_AddOutlineIDCMP or GOA_AddObjectIDCMP are TRUE. If a custom IDCMP has been requested with GOA_UserIDCMP, the window will be opened with this tag set to zero, then port attached to it, and ModifyIDCMP() then called to set the correct value. The window will then be opened and attached to the GadOutline using DimenGadOutlineA() and GOA_WindowAddr. If either the window can not be opened or there is an error when attaching it, it will be closed and a NULL returned. If the window is opened successfully, any menu strip will be layed out and attached to it and the address of the window will be returned. Note that you should normally only use this return value as a TRUE/FALSE indicator of whether the function call was successfull, and use the address in go_Window to reference the actual window. INPUTS GadOutline - (struct GadOutline *) Allocated GadOutline. TagList - (struct TagItem *) Window's tags (WA_*). RESULT Window - (struct Window *) The resulting window or NULL. go_LastReqReturn is non-zero if there was an error. TAGS EXAMPLE NOTES . BUGS The additional size of the window's borders are not taken into account when it has a sizing gadget. SEE ALSO GO_CloseWindow(), UpdateGadOutlineA() gadoutline.library/GO_ParseGOIMsgA gadoutline.library/GO_ParseGOIMsgA 18 Jul 1993 11:09:10 NAME GO_ParseGOIMsgA -- Perform standard actions for a message. SYNOPSIS GO_ParseGOIMsgA(GadOutline, StdID, Message, TagList) A0 D0 A1 A2 void GO_ParseGOIMsgA(struct GadOutline *, CMDID, struct GOIMsg *, struct TagItem *) FUNCTION This function is used internally by the library and should not currently be called by a user program. INPUTS GadOutline - (struct GadOutline *) Allocated GadOutline. StdID - (CMDID) (optional) Command to send message to. Message - (struct GOIMsg *) Standard message. TagList - (struct TagItem *) Control tags. RESULT nothing. go_LastReqReturn is non-zero if there was an error. TAGS EXAMPLE NOTES . BUGS . SEE ALSO GO_GetGOIMsg(), GO_FilterGOIMsg() gadoutline.library/GO_ParseTypedSizeListAgadoutline.library/GO_ParseTypedSizeListA 16 Jul 1993 14:07:08 NAME GO_ParseTypedSizeListA -- Compute a complete TypedSize tag list. SYNOPSIS Value = GO_ParseTypedSizeListA(GadOutline, CurrentValue, A0 D0 TypedSizeTags) A1 LONG GO_ParseTypedSizeListA(struct GadOutline *, LONG, struct TagItem *) FUNCTION Interprets all of a complete list of TypedSize tags. CurrentValue provides the initial value for the list; it is then successively modified by the TypedSize tags in the list. This routine is essentially like successively calling GO_InterpretTypedSize() and providing the result of one call to the CurrentValue parameter of the next. However, it also allows text strings to be examined using the GOCT_Text* and GOCT_MoreText* tags. Each TypedSize is provided in the ti_Data field of a GOCT_SizeParse tag. INPUTS GadOutline - (struct GadOutline *) Allocated GadOutline. CurrentValue - (LONG) The initial value for the parse. TypedSizeTags - (struct TagItem *) TypedSize and control tag list. RESULT Value - (LONG) The final size computed. TAGS EXAMPLE Assuming Topaz 8: GO_ParseTypedSize(go,0, GOCT_TextPtr, "1234567890", GOCT_SizeParse, GO_TSIZE(GOM_Set,1000,GOT_PercTextMaxW), GOCT_SizeParse, GO_TSIZE(GOM_Add,100,GOT_PercTextMaxH), TAG_END); ==> 808 NOTES See the notes for GO_InterpretTypedSize(). All standard tags - TAG_MORE, TAG_SKIP, etc. - can be used. BUGS . SEE ALSO GO_InterpretTypedSize() gadoutline.library/GO_PostFilterGOIMsg gadoutline.library/GO_PostFilterGOIMsg 18 Jul 1993 13:37:07 NAME GO_PostFilterGOIMsg -- Finishes special processing of a GOIMsg. SYNOPSIS OldMsg = GO_PostFilterGOIMsg(Message) A0 struct IntuiMessage *GO_PostFilterGOIMsg(struct GOIMsg *) FUNCTION Releases the GOIMsg back to the library and returns the original IntuiMessage to be sent to GadTools and reply'd. Additional message processing is performed at this time, primarily dealing with tracking IDCMP_NEWSIZE and IDCMP_SIZEVERIFY messages. A NULL OldMsg will be returned if the given GOIMsg was generated solely by the library. This is similar to GadTools' GT_FilterIMsg(). INPUTS Message - (struct GOIMsg *) Message returned from GO_FilterGOIMsg(). RESULT OldMsg - (struct IntuiMessage *) Original GadTools/Intuition message. go_LastReqReturn is non-zero if there was an error. TAGS EXAMPLE NOTES This function does not call GT_PostFilterIMsg(). BUGS . SEE ALSO GO_FilterGOIMsg(), GO_ReplyGOIMsg(), gadtools/GT_PostFilterIMsg() gadoutline.library/GO_ReplyGOIMsg gadoutline.library/GO_ReplyGOIMsg 18 Jul 1993 14:18:05 NAME GO_ReplyGOIMsg -- Reply messages retrieved with GO_GetGOIMsg(). SYNOPSIS GO_ReplyGOIMsg(Message) A0 void GO_ReplyGOIMsg(struct GOIMsg *) FUNCTION Finishes processing of a message and replies using GT_ReplyIMsg(). INPUTS Message - (struct GOIMsg *) Message returned by GO_GetGOIMsg(). RESULT nothing. go_LastReqReturn is non-zero if there was an error. TAGS EXAMPLE NOTES . BUGS . SEE ALSO GO_DupGOIMsg(), GO_GetGOIMsg(), GO_PostFilterGOIMsg(), gadtools/GT_ReplyIMsg() gadoutline.library/GO_SetCmdAttrsA gadoutline.library/GO_SetCmdAttrsA 18 Jul 1993 08:41:44 NAME GO_SetCmdAttrsA -- Modify a command's command tag list. SYNOPSIS GO_SetCmdAttrsA(GadOutline, CmdID, Flags, TagList) A0 D0 D1 A1 void GO_SetCmdAttrsA(struct GadOutline *, CMDID, ULONG, struct TagItem *) FUNCTION Changes the command tag list (ie, the first tag list) of the command(s) with the given CmdID. This is identical to GO_SetCmdGrpAttrsA(), except that a CmdID of 0 will result in no commands being changed rather than all of them, providing some protection against accidentally using a StdID of 0. While this function can be used with a non-zero group ID and multiple commands, GO_SetCmdGrpAttrsA() is the recomended interface for these types of operations. INPUTS GadOutline - (struct GadOutline *) Allocated GadOutline. CmdID - (CMDID) ID pattern of command(s) to change. Flags - (ULONG) Reserved. Always set to zero. TagList - (struct TagItem *) Tags to change. RESULT No return value. go_LastReqReturn is non-zero if there was an error. TAGS EXAMPLE NOTES . BUGS . SEE ALSO GO_SetCmdGrpAttrsA() gadoutline.library/GO_SetCmdGrpAttrsA gadoutline.library/GO_SetCmdGrpAttrsA 18 Jul 1993 08:56:10 NAME GO_SetCmdGrpAttrsA -- Modify one or more commands' command tag list. SYNOPSIS GO_SetCmdGrpAttrsA(GadOutline, CmdID, Flags, TagList) A0 D0 D1 A1 void GO_SetCmdGrpAttrsA(struct GadOutline *, CMDID, ULONG, struct TagItem *) FUNCTION Changes the command tag list (ie, the first tag list) of the command(s) with the given CmdID. This essentially involves sending a CHM_SETCMDATTR message to every CmdInfo returned by calling GO_GetCmdInfo() with the given CmdID. The exact interpretation of this operation is command-dependant; however, the standard hook will copy all of the supplied tags into its local tag list and update its internal flags to reflect these new values. If you are specifically changing only one command, GO_SetCmdAttrsA() is the recomended function to use. INPUTS GadOutline - (struct GadOutline *) Allocated GadOutline. CmdID - (CMDID) ID pattern of command(s) to change. Flags - (ULONG) Reserved. Always set to zero. TagList - (struct TagItem *) Tags to change. RESULT No return value. go_LastReqReturn is non-zero if there was an error. TAGS EXAMPLE NOTES . BUGS . SEE ALSO GO_GetCmdInfo(), GO_SetCmdAttrsA(), GO_GetCmdAttrsA() gadoutline.library/GO_SetErrorA gadoutline.library/GO_SetErrorA 17 Jul 1993 03:02:36 NAME GO_SetErrorA -- Set a GadOutline's error code. SYNOPSIS Return = GO_SetErrorA(GadOutline, ErrorCode, ErrorObject, Params) A0 D0 A1 A2 ULONG GO_SetErrorA(struct GadOutline *, GOERR, void *, UBYTE **) FUNCTION Sets the current error code and error object of the given outline to ErrorCode and ErrorObject; writes variables pointed to by GOA_ErrorCode and GOA_ErrorText tags, if they are non-NULL, to these new values. If the bit corresponding to this error type in the GOA_ErrorReportLevel tag is set, the error will then be displayed by calling GO_ShowErrorA(GadOutline,NULL,NULL,Params). The value returned will be put in go_LastReqReturn and returned to the caller. If the error report bit for this error type is cleared, this same bit will then be checked in the tag GOA_ErrorFailLevel. If it is 1, the function will return GORET_FAIL, otherwise GORET_CONT will be returned. In either case, no error will be reported to the user. An error code of 0 will clear any errors and set go_LastReqReturn to GORET_CONT. If GadOutline is NULL, this function will just call GO_ShowErrorA() with the given parameters. INPUTS GadOutline - (struct GadOutline *) Allocated GadOutline or NULL. ErrorCode - (GOERR) Error code and type to set. ErrorObject - (void *) Error code dependant object. Params - (UBYTE **) Optional additional text to display. RESULT Return - (ULONG) One of GORET_CONT, GORET_RETRY or GORET_FAIL. TAGS EXAMPLE NOTES 'Params' will only be used if an error is displayed automatically by this function. If you have an error type turned off and, after it occurs, show it yourself by calling GO_ShowErrorA(go,NULL,NULL,NULL), any additional text that was attached to it will not be displayed. The library at some points needs to turn off errors while executing internally. You should never notice this within your main program, but it may be in this state when calling a user hook, especially when sending CHM_UNHOOKOBJ and CHM_DESTROYOBJ messages. You should never create errors from these messages (or any other message that frees resources), so this shouldn't be a problem. Be careful about how you mark error type failures for any you turn off. In general, you should never mark a type as a failure if it does not a have a fail button, or mark types without a continue button as non-failures. This means that types GOTYPE_FAIL and GOTYPE_ALERT should always be failures, GOTYPE_WARN and GOTYPE_NOTE can be either, and GOTYPE_FINE should never be a failure. Library errors are generally divided into the primary type (ie, GOTYPE_WARN) being a system error, the second type (ie, GOTYPE_WARN2) being programmer debugging errors (such as having a non-unique StdID in an outline), and the third type (ie, GOTYPE_WARN3) being library debugging errors. You will usually want to have all primary and secondary errors reported during program development so that you can catch errors in your outline definition and other problems. It is perfectly fine to always leave these on, although there may be times that you need to turn them off in a release version if you need to keep the library from complaining about something like assigning a hotkey that is already attached to another command. BUGS . SEE ALSO GO_ShowErrorA(), GO_GetErrorCode(), GO_GetErrorText(), GO_GetErrorObject() gadoutline.library/GO_SetObjAttrsA gadoutline.library/GO_SetObjAttrsA 18 Jul 1993 09:07:58 NAME GO_SetObjAttrsA -- Modify a command's object tag list. SYNOPSIS GO_SetObjAttrsA(GadOutline, CmdID, Flags, TagList) A0 D0 D1 A1 void GO_SetObjAttrsA(struct GadOutline *, CMDID, ULONG, struct TagItem *) FUNCTION Changes the object tag list (ie, the second tag list) of the command(s) with the given CmdID. This is identical to GO_SetObjGrpAttrsA(), except that a CmdID of 0 will result in no commands being changed rather than all of them, providing some protection against accidentally using a StdID of 0. While this function can be used with a non-zero group ID and multiple commands, GO_SetObjGrpAttrsA() is the recomended interface for these types of operations. INPUTS GadOutline - (struct GadOutline *) Allocated GadOutline. CmdID - (CMDID) ID pattern of command(s) to change. Flags - (ULONG) Reserved. Always set to zero. TagList - (struct TagItem *) Tags to change. RESULT No return value. go_LastReqReturn is non-zero if there was an error. TAGS EXAMPLE NOTES This command is not fully supported while in an unhooked state. BUGS . SEE ALSO GO_SetObjGrpAttrsA(), UnhookGadOutlineA() gadoutline.library/GO_SetObjGrpAttrsA gadoutline.library/GO_SetObjGrpAttrsA 18 Jul 1993 09:10:30 NAME GO_SetObjGrpAttrsA -- Modify one or more commands' object tag list. SYNOPSIS GO_SetObjGrpAttrsA(GadOutline, CmdID, Flags, TagList) A0 D0 D1 A1 void GO_SetObjGrpAttrsA(struct GadOutline *, CMDID, ULONG, struct TagItem *) FUNCTION Changes the object tag list (ie, the first tag list) of the command(s) with the given CmdID. This essentially involves sending a CHM_SETOBJATTR message to every CmdInfo returned by calling GO_GetCmdInfo() with the given CmdID. The exact interpretation of this operation is command-dependant; however, the standard hook will copy all of the supplied tags into its local tag list and update its object to update these new flags. For example, the standard GadTools hook calls GT_SetGadAttrs() with the given tag list. Depending on the command and tags specified, this may cause the object to update its current imagery. If you are specifically changing only one command, GO_SetObjAttrsA() is the recomended function to use. INPUTS GadOutline - (struct GadOutline *) Allocated GadOutline. CmdID - (CMDID) ID pattern of command(s) to change. Flags - (ULONG) Reserved. Always set to zero. TagList - (struct TagItem *) Tags to change. RESULT No return value. go_LastReqReturn is non-zero if there was an error. TAGS EXAMPLE NOTES This command is not fully supported while in an unhooked state. BUGS . SEE ALSO GO_GetCmdInfo(), GO_SetObjAttrsA(), GO_GetObjAttrsA(), UnhookGadOutlineA() gadoutline.library/GO_ShowErrorA gadoutline.library/GO_ShowErrorA 17 Jul 1993 04:23:16 NAME GO_ShowErrorA -- Display a standard GadOutline error requester. SYNOPSIS Return = GO_ShowErrorA(GadOutline, ErrorCode, ErrorObject, Params) A0 D0 A1 A2 ULONG GO_ShowErrorA(struct GadOutline *, GOERR, void *, UBYTE **) FUNCTION Displays an error requester explaining the current error and waits for user input. The exact error to display is determined by ErrorCode; if its type is non-zero (ie, not GOTYPE_NONE), the requester displays the error code and type given. Otherwise, it displays the GadOutline's current error, as given by GO_GetErrorCode(). ErrorObject provides more detailed information about the error, and its exact meaning is error-code dependant; see GO_GetErrorObject() for information about what object each code expects. The standard error requester's title is either the text supplied in GOA_BaseName or, if that has not been set, defaults to "GadOutline Requester". The body displayed is in the form: +-------------------------+ | (<T>) <Type text> #<C>: | | <Code text>. | | | | <Additional information>| | <Extra parameters> | +-------------------------+ Where <T> is the error type number, <Type text> is the textual interpretation of that type (ie, type #8 is "Warning"), <C> is the code number, and <Code text> is the description of the error code. Errors which have an object will then fill in more detailed information in the <Additional information> field; what exactly is displayed here and the number of lines is code dependant. Finally, any user-supplied parameter(s) are appended to the bottom. The user supplied parameters are passed in 'Params.' This is a pointer to a string pointer, followed by its arguments, as per Intuition's EasyRequestA() function. This provides the standard C-style formatting arguments identical to EasyRequestA(). The library also provides three additional formatting escape characters: ^ provides global GadOutline information, ~ provides object-dependant information, and ` is reserved for future use. This sequences are in the form of the escape character followed by a two-character code, ie "^lb" will be translated into the maximum outline size, as given by GOA_OutlineSize. A special sequence of the escape character followed by itself will be reduced to a single escape, ie if the GOA_OutlineSize is 10, "^lb^^^lb" will display the text "10^10". The object formatting character ~ determines how the object will be interpreted; the library has no way of determining what the object actually is except by the formatting sequences used, so you should be careful about what you are actually giving it. The available buttons at the bottom of the requester are determined by the error type. They are: GOTYPE_NONE - "CONTINUE" GOTYPE_NOTE - "CONTINUE" / "ABORT" GOTYPE_WARN - "CONTINUE" / "RETRY" / "ABORT" GOTYPE_ALERT - "RETRY" / "ABORT" GOTYPE_FAIL - "ABORT" The value returned by the function will be one of GORET_CONT, GORET_RETRY or GORET_FAIL, depending on whether the user selected "CONTINUE", "RETRY" or "ABORT", respectively. A special display mode is provided when the error code (the lower 16 bits of the error) is GOCODE_NONE. In this case, none of the standard information (error type, code, addition information) is displayed, and instead only the user parameters are used. Which buttons are displayed, however, is still determined by the error type. This us useful it you want to display your own custom requester. The formatting codes currently recognized are: Global Outline information: ~~~~~~~~~~~~~~~~~~~~~~~~~~~ ^et: text of the error code that was supplied to the function. ^ec: number of the error code that was supplied to the function. ^eh: header text for the error type supplied to the function. ^el: number of the error type that was supplied to the function. ^st: text of the gadoutline's current state (error code.) ^sc: number of the gadoutline's current state (error code.) ^sh: header text for the gadoutline's current level (error type.) ^sl: number of the gadoutline's current level (error type.) ^Za: programmer's address ^Zb: library base name ^Zd: library creation date ^Ze: programmer's email address ^Zp: library programmer ^Zr: library revision ^Zt: library creation time ^Zv: library version ^Zy: library creation year ^ZR: library release version ^ZV: full library version info ^lb: maximum size (in bytes) of outline ^lw: current layout needed window width ^lh: current layout needed window height ^lW: maximum layout width ^lH: maximum layout height ^lx: current layout needed inner width ^ly: current layout needed inner height ^lX: maximum layout inner width ^lY: maximum layout inner height ^ln: current layout font name ^ls: current layout font size ^lN: target font name ^lS: target font size ^^: insert a single ^ Current Object Information: ~~~~~~~~~~~~~~~~~~~~~~~~~~~ Base objects (ULONG): ~bb: print as number in binary ~bd: print as number in decimal ~bh: print as number in hex ~bc: print as a character ~bs: print as string (This object is a UBYTE *) For CmdInfo objects (struct CmdInfo *): ~ck: command's kind (number) ~cc: command's code (number) ~cs: command's subcode (number) ~cv: command's full value in hex ~ci: command's standard ID ~cg: command's group ID ~cG: command's group code ID ~cm: command's group mask ID ~cl: command's label or other identifying text For CmdID objects (CMDID): ~is: standard ID part ~ig: group ID part ~ic: group code ID part ~im: group mask ID part For TypedSize objects (TYPEDSIZE): ~tm: mode part (number) ~ts: size part (number) ~tt: type part (number) ~tv: full value in hex For IntErr objects (ULONG): ~em: module of error (text) ~el: line of error (number) ~~: insert a single ~ Reserved Formatter: ~~~~~~~~~~~~~~~~~~~ ``: insert a single ` INPUTS GadOutline - (struct GadOutline *) Allocated GadOutline or NULL. ErrorCode - (GOERR) Error code and type to display. ErrorObject - (void *) Error code dependant object. Params - (UBYTE **) Optional additional text to display. RESULT Return - (ULONG) One of GORET_CONT, GORET_RETRY or GORET_FAIL. TAGS EXAMPLE /* Show information about a command * Runs through every command with the given CmdID and displays * a requester with the given ID and the command's kind, code and * subcode. Allows user to: Retry, which will restart displaying * the commands; Continue, which will display the next command; and * Abort, which will immediately stop displaying commands. */ void show_command(struct GadOutline *go,CMDID id) { struct CmdInfo *ci = NULL; ULONG ret = GORET_CONT; while( ret == GORET_CONT && (ci = GO_GetCmdInfo(go,id,ci)) != NULL ) { ret = GO_ShowError(go, GO_MAKEERR(GOTYPE_WARN,GOCODE_NONE), ci, "Matched cmd with ID #%lx:\n\nKind:~ck Code: ~cc SubCode: ~cs", id); if(ret == GORET_RETRY) { ci = NULL; ret = GORET_CONT; } } } NOTES All error codes which expect a pointer to something for their object will interpret NULL as "none available". You should always supply a NULL object for any codes which currently have no defined object; this is the only object value which will always be safe to use. This function does not set go_LastReqReturn. BUGS If one of the standard errors prints a string (ie, from an actual string object or the label of a command) which contains a "%", this will be blindly passed on to EasyRequest, which will interpret it as a C-style formatter. SEE ALSO GO_SetErrorA(), GO_GetErrorCode(), GO_GetErrorText(), GO_GetErrorObject(), intuition/EasyRequestA() gadoutline.library/GO_UndupGOIMsg gadoutline.library/GO_UndupGOIMsg 18 Jul 1993 10:32:31 NAME GO_UndupGOIMsg -- Free a previously duplicated GOIMsg. SYNOPSIS OldMessage = GO_UndupGOIMsg(Message) A0 struct GOIMsg *GO_UndupGOIMsg(struct GOIMsg *) FUNCTION Frees a message that was allocated with GO_DupGOIMsg(). Exactly what is returned depends what the given message is: If it is a GOIMsg returned by calling GO_DupGOIMsg() with a GOIMsg or IntuiMessage, the message upon which it was based will be returned. If it is a GOIMsg returned by calling GO_DupGOIMsg() with a NULL message, a NULL will be returned. If it is an actual IntuiMessage, this same IntuiMessage will simply be returned. INPUTS Message - (struct GOIMsg *) A previously dupped message. RESULT OldMessage - (struct GOIMsg *) What this message was based on. TAGS EXAMPLE NOTES This routine does not actually free the memory used by the message, but rather puts it back on a 'free message list' of the GadOutline which allocated it, to be reused by GO_DupGOIMsg(). BUGS . SEE ALSO GO_DupGOIMsg() gadoutline.library/HookGadOutlineA gadoutline.library/HookGadOutlineA 16 Jul 1993 08:26:43 NAME HookGadOutlineA -- Attach gadgets to window. SYNOPSIS HookGadOutlineA(GadOutline, TagList) A0 A1 void HookGadOutlineA(struct GadOutline *, struct TagItem *) FUNCTION Calls UpdateGadOutlineA() with the given tag list and then attaches the go_GToolsList and go_BoopsiList to the window's gadget list and calls RefreshGList(). If GO_DoHookCallback is TRUE, CHM_HOOKOBJ messages will then be sent to all of the commands. INPUTS GadOutline - (struct GadOutline *) Previously allocated GadOutline. TagList - (struct TagItem *) Global (GOA_*) outline tags, parsed before the gadgets are actually attached. RESULT Nothing returned from the function. go_LastReqReturn is non-zero if an error occured. TAGS EXAMPLE NOTES The operational order is: Add and refresh BOOPSI then GadTools gadget lists, send CHM_HOOKOBJ messages, call DrawGadOutlineA(). BUGS . SEE ALSO UpdateGadOutlineA(), UnhookGadOutlineA() gadoutline.library/RebuildGadOutlineA gadoutline.library/RebuildGadOutlineA 15 Jul 1993 08:36:01 NAME RebuildGadOutlineA -- Perform a final layout on a GadOutline. SYNOPSIS RebuildGadOutlineA(GadOutline, TagList) A0 A1 void RebuildGadOutlineA(struct GadOutline *, struct TagItem *) FUNCTION This function performs the second part of a complete layout. It first calles UpdateGadOutlineA() with the given tags and then uses the box and groups' minimum dimension information and the required minimum size of the layout to find the final size that everything needs to be. It then positions the boxes and groups, processes the final box dimension tags [ie, GOCT_SetBoxLeft] for all boxes, groups and images, fills in the global information tags [ie, GOCT_CopyScreen], and finally creates the gadgets by sending CHM_CREATEOBJ messages to every command after resolving all of its tag links. This phase is concerned with what to do with any extra space within within the layout. This extra space may come from two distinct places - the difference between the entire layout's base dimension, as computed by DimenGadOutlineA(), and the minimum size allowed, and the difference between a group's minimum size and the size of the individual boxes within it. However, these two are, for the most part, treated as a single quantity by the library. The layout starts at the root group; the amount of space needed to make it fit the GadOutline's minimum dimensions is distributed to each of its children in its running dimension according to their relative weights, and in the static dimension it is summed with the difference between the group's minimum size and each child's. Each child group will then distribute the space it received in a similar fashion. When a box receives its extra space, it distributes it among its various areas. By default, the box will simply put all of it in its body area, but this behavior can be changed by providing a custom weight distribution and using TypedSize commands changing the VAR component. Two tags are available to control the way the library performs the layout. The tag GOCT_AutoDistExtra will cause a box or group to try to distribute the extra space within itself so that it matches its parent's final dimensions, and GOCT_IgnoreFinDimens will make the library ignore a box or group's dimensions, essentially putting the group or box that follows on top of it. Once the final dimensions have been determined, another run through the layout will be performed to compute the final positions of the groups and boxes. Finally, a last run through the entire outline will be performed to execute the GOCT_Set* command tags for all boxes, groups and images, after which any attached BoxPosInfo will be filled in and the GOCT_Copy* global information tags will be executed along with GOCT_CopyUser1ToTag and GOCT_CopyUser2ToTag. After the layout is finished, the library will run through the entire command list and send each a CHM_CREATEOBJ. At this time, all TagLinks are resolved by reordering the gadget creation. If the library is unable to find an order to that will resolve the links [ie, you have two commands pointing to each other], it will not create either command. If any hook returns a non-zero go_LastReqReturn, the entire creation will be aborted. However, a command not creating an object [not setting its ci_Object field to a non-NULL value] is NOT considered an error. If the command has GOCT_IgnoreCreation set to TRUE, or if this is a box or group and any of its parent groups has GOCT_IgnoreCreation set to true, it is completely ignored and no CHM_CREATEOBJ is sent to it, even if there is a TagLink connected to it. If GOA_SetWindowFont is TRUE, the window's font will be set before creating the gadgets. If there are no errors while creating the gadgets, the library calls HookGadOutlineA() with an empty tag list. INPUTS GadOutline - (struct GadOutline *) Previously allocated GadOutline. TagList - (struct TagItem *) Global (GOA_*) outline tags, parsed before the actual layout is performed. RESULT Nothing returned from the function. go_LastReqReturn is non-zero if an error occured. TAGS Command tags - GOCT_AutoDistExtra - distribute dimensions to match parent. GOCT_IgnoreFinDimens - ignore box/group during layout. EXAMPLE NOTES This function may fall back to DimenGadOutlineA() if you have changed the screen, window, etc of the GadOutline. If there is no window attached to the GadOutline, no layout and gadget creation will be performed. Groups currently ignore any TypedSize VAR commands; never use them, as a meaning may be attached to them in the future. The order that commands are sent CHM_CREATEOBJ messages is not defined and may change. If you want to ensure a particular order, supply TagLinks pointing to a dummy tag in the command that you would like created before the current one. This will force the library to create the object being pointed to before it creates the current one. This function depends on the minimum dimensioning information computed by DimenGadOutlineA() to be correct and up-to-date. If you have made any changes to the outline that has made it need more room and don't call DimenGadOutlineA(), this function will probably create a layout that is larger than the current maximum dimensions. BUGS The algorithm for creating objects in the correct order is not very efficient, and may slow down severly if you have many commands linked to others that occur before them in the outline. SEE ALSO DimenGadOutlineA(), HookGadOutlineA(), UpdateGadOutlineA() gadoutline.library/ResizeGadOutlineA gadoutline.library/ResizeGadOutlineA 15 Jul 1993 09:45:42 NAME ResizeGadOutlineA -- Perform only a resize of a GadOutline. SYNOPSIS ResizeGadOutlineA(GadOutline, TagList) A0 A1 void ResizeGadOutlineA(struct GadOutline *, struct TagItem *) FUNCTION This routine performs a simple resize of a layout which has ONLY changed in size. This is intended to support BOOPSI gadgets that are able to resize themselves without being completely destroyed and recreated, but currently always does a full RebuildGadOutlineA(). You should only call this function to update the layout after a window resize; use RebuildGadOutlineA() to update after changing any object attributes (such as the depth of a palette gadget) or command tags such as GOCT_IgnoreCreation and GOCT_IgnoreFinDimens. INPUTS GadOutline - (struct GadOutline *) Previously allocated GadOutline. TagList - (struct TagItem *) Global (GOA_*) outline tags, parsed before the actual resize is performed. RESULT Nothing returned from the function. go_LastReqReturn is non-zero if an error occured. TAGS EXAMPLE NOTES You should never need to call this unless you turn off automatic resizing using { GOA_AutoResize, FALSE }. BUGS Currently always calls RebuildGadOutlineA(). SEE ALSO RebuildGadOutlineA(), UpdateGadOutlineA() gadoutline.library/translation_hooks gadoutline.library/translation_hooks 18 Jul 1993 15:09:09 NAME translation_hooks -- Information on GadOutline translation hooks. SYNOPSIS Return = translation_hooks(Hook, GadOutline, Message) A0 A2 A1 static ULONG translation_hooks(struct Hook *, struct GadOutline *, struct CmdHookMsg *) FUNCTION . These are the operations implemented by the library's built-in hook: CHM_TRANSCMDHOOK: CHM_TRANSEDITHOOK: CHM_TRANSTEXTPTR: CHM_TRANSTEXTARRAY: CHM_TRANSTEXTFMT: CHM_TRANSPUBCLASS: CHM_TRANSPRIVCLASS: Just returns the given code. CHM_TRANSTEXTARRAY: Allocates memory to hold an array of the same size as the one pointed to by the given code, and sends CHM_TRANSTEXTPTR for each entry in the array. CHM_TRANSHOTKEY: Returns the hotkey code, parsing HOTKEY_NOTRANS, HOTKEY_UPONLY and HOTKEY_LOWONLY flags. All others return the given code. INPUTS Hook - (struct Hook *) Your hook. GadOutline - (struct GadOutline *) GadOutline asking for translation. Message - (struct CmdHookMsg *) The translation to perform. RESULT Return - (static ULONG) The translated code. TAGS EXAMPLE NOTES . BUGS . SEE ALSO gadoutline.library/UnhookGadOutlineA gadoutline.library/UnhookGadOutlineA 16 Jul 1993 08:35:38 NAME UnhookGadOutlineA -- Detach gadgets from a window. SYNOPSIS UnhookGadOutlineA(GadOutline, TagList) A0 A1 void UnhookGadOutlineA(struct GadOutline *, struct TagItem *) FUNCTION Calls UpdateGadOutlineA() with the given tag list and then detaches the go_GToolsList and go_BoopsiList gadgets from the window. If the commands were previously sent CHM_HOOKOBJ by HookGadOutlineA(), they will ALL be sent a CHM_UNHOOKOBJ, even if an error had occured before being sent the hook message. (In other words, a user hook must be able to handle receiving CHM_UNHOOKOBJ messages without an associated CHM_HOOKOBJ.) INPUTS GadOutline - (struct GadOutline *) Previously allocated GadOutline. TagList - (struct TagItem *) Global (GOA_*) outline tags, parsed before the gadgets are actually detached. RESULT Nothing returned from the function. go_LastReqReturn is non-zero if an error occured. (If an empty tag list is passed, an error should never be returned.) TAGS EXAMPLE NOTES The operational order is: Send CHM_UNHOOKOBJ messages, remove GadTools and BOOPSI lists. BUGS Sending CHM_SETOBJATTR messages, either directly through GO_SetObjAttrsA(), or indirectly by sending CHM_HOTKEY, etc. messages which cause a change in state, while a GadOutline is in an unhooked state, but with its objects still created, is not really supported and may cause a crash. SEE ALSO UpdateGadOutlineA(), HookGadOutline(). gadoutline.library/UpdateGadOutlineA gadoutline.library/UpdateGadOutlineA 16 Jul 1993 06:36:02 NAME UpdateGadOutlineA -- Modify GadOutline from supplied tag list. SYNOPSIS UpdateGadOutlineA(GadOutline, TagList) A0 A1 void UpdateGadOutlineA(struct GadOutline *, struct TagItem *) FUNCTION This is the interface for changing a GadOutline's global state using the GOA_* tag commands. It is called by AllocGadOutlineA(), DimenGadOutlineA(), RebuildGadOutlineA(), ResizeGadOutlineA(), HookGadOutlineA(), DrawGadOutlineA(), UnhookGadOutlineA() and DestroyGadOutlineA() to process the tag list passed to them. This routine provides a way for you to change the outline's global state without directly performing any other action. However, note that many of the global tags will cause either an immediate action, or delayed action that will occur the next time one of the above functions is called. See <libraries/gadoutline.h> for more detailed information on the global tags. INPUTS GadOutline - (struct GadOutline *) Previously allocated GadOutline. TagList - (struct TagItem *) Global (GOA_*) outline tags to parse. RESULT Nothing returned from the function. go_LastReqReturn is non-zero if an error occured. TAGS GOA_BaseName - assign a program basename to the outline. This string is currently only used as the title in the error requester. GOA_ErrorCode - provide location of a ULONG to put error codes in. GOA_ErrorText - provide location of a UBYTE * to put error text in. GOA_SetUserData - put value in ti_Data into go_UserData. GOA_SetUserHandler - put value in ti_Data into go_UserHandler. GOA_SetTransHook - ti_Data points to a standard Hook structure which will be called to perform code translations. GOA_SetTransHookData - put value in ti_Data into go_TransHookData. These tags will cause the next call to RebuildGadOutlineA() or ResizeGadOutlineA() to fall back to DimenGadOutlineA(). If a window a screen is currently attached to the GadOutline, they will immediately be closed if these tags specify a different screen/window. GOA_DisplayID and GOA_Overscan - provide a display mode and the desired overscan size to fit the layout in. GOA_ScreenAddr - specify the address of a screen to attach to the GadOutline and fit the layout to. This screen must remain valid while it is attached to the GadOutline. GOA_ScreenName - specify the name of a public screen to attach to the GadOutline and fit the layout to. This screen will automatically be locked by the library while it is attached to the GadOutline. GOA_ScreenFallBack - if TRUE, try opening the public screen if the given screen name does not exist. GOA_WindowAddr - specify the address of a window to attach to the GadOutline. While a window is attached, DimenGadOutlineA(), RebuildGadOutline() and ResizeGadOutline() will result in the full creation of the gadgets and attach them to the window. GOA_MinWidth, GOA_MinHeight, GOA_MaxWidth, GOA_MaxHeight - override the default layout dimensions. The dimensions are always reset reset to the current screen/window if these tags are not supplied, regardless of whether or not they were previously set. Font tags. These will not take affect until DimenGadOutlineA() is called. Zero or NULL for any of these tags means "don't care." GOA_TextAttr - completely specify desired font. GOA_FontName - specify name of font. The ".font" suffix is optional. GOA_FontSize - specify size of font. GOA_FontStyle - specify style of font, ie FSF_Bold. Font fitting control. Don't take affect until DimenGadOutlineA(). GOA_FontMinSize - set the minimum point size the library will try to scale the requested font down to before falling back to the system fonts. GOA_FontSystemOnly - if true, the library will never try smaller font point sizes before using the system fonts. GOA_FontROMFont - set FPF_ROMFONT flag when opening fonts. GOA_FontDiskFont - set FPF_ROMFONT flag when opening fonts and use OpenDiskFont() instead of OpenFont(). GOA_FontDesigned - set FPF_DESIGNED flag when opening fonts. GO_OpenWindow() tags - window menu strip and size control. These only affect the operation of GO_OpenWindow(). GOA_AllocMenus - supply a GadTools NewMenu array to allocate and attach to the window. GOA_GToolsMenus - supply a menu strip that was previously allocated by GadTools; it will be automatically layed out. GOA_StandardMenus - supply a standard Intuition menu strip to be attached to the window. It will not be touched in any way. GOA_SaveWinDimens - if TRUE, the window's dimensions will be remembered between closing and reopening it. GOA_WindowRelative - if TRUE, the position and size information given in the window tags is interpreted relative to the screen and layout position and size. IDCMP control. GOA_UserIDCMP - set a custom MsgPort. If NULL, the window's UserPort will be used; if ~0, the library will immediately allocate its own message port. NEVER specify this flag while a window is attached to the outline. GOA_AutoSizeVerify - if TRUE, automatically call UnhookGadOutlineA() when an IDCMP_SIZEVERIFY message is received. GOA_AutoNewSize - if TRUE, automatically call ResizeGadOutlineA() when the window's size changes. GOA_AddOutlineIDCMP - if TRUE, the window will be set to report all IDCMP events needed by the library. GOA_AddObjectIDCMP - if TRUE, the window will be set to report all IDCMP events needed by the objects within the GadOutline. GOA_AutoHotKeys - if TRUE, IDCMP_RAWKEY and IDCMP_VANILLAKEY will be redirected to any command attached to them. GOA_RedrawWinFrame - if TRUE, the library will automatically refresh the window's frame after it has been resized. GOA_SetWindowFont - if TRUE, the window's RastPort font will be set to the font being used in the layout. GOA_ClearFullWin - if TRUE, the entire area inside of the window's borders will be cleared during a resize. GOA_DoHookCallback - if TRUE, CHM_HOOKOBJ and CHM_UNHOOKOBJ messages will be sent when the gadgets are hooked and unhooked from the window. GOA_WindowResize - allow library to resize window to make layout fit. NOT IMPLEMENTED. GOA_ErrorReportLevel - specify which error types will be reported. GOA_ErrorFailLevel - specify which unreported types will be failures. GOA_OutlineSize - provide the size of the static outline array, for bounds checking. This tag is only useful when directly passed to AllocGadOutlineA(). EXAMPLE NOTES . BUGS GOA_WindowResize is not implemented. Using GOA_UserIDCMP while a window is attached can crash. SEE ALSO AllocGadOutlineA(), DimenGadOutlineA(), RebuildGadOutlineA(), ResizeGadOutlineA(), HookGadOutlineA(), DrawGadOutlineA(), UnhookGadOutlineA(), DestroyGadOutlineA(), <libraries/gadoutline.h>