home *** CD-ROM | disk | FTP | other *** search
/ Amiga ISO Collection / AmigaUtilCD2.iso / Programming / Assembler / TFF-AOC.DMS / in.adf / Release3.1 / AutoDocs3.1.lha / doc / gadtools.doc < prev    next >
Encoding:
Text File  |  1993-08-12  |  51.9 KB  |  1,356 lines
  1. TABLE OF CONTENTS
  2.  
  3. gadtools.library/CreateContext
  4. gadtools.library/CreateGadgetA
  5. gadtools.library/CreateMenusA
  6. gadtools.library/DrawBevelBoxA
  7. gadtools.library/FreeGadgets
  8. gadtools.library/FreeMenus
  9. gadtools.library/FreeVisualInfo
  10. gadtools.library/GetVisualInfoA
  11. gadtools.library/GT_BeginRefresh
  12. gadtools.library/GT_EndRefresh
  13. gadtools.library/GT_FilterIMsg
  14. gadtools.library/GT_GetGadgetAttrsA
  15. gadtools.library/GT_GetIMsg
  16. gadtools.library/GT_PostFilterIMsg
  17. gadtools.library/GT_RefreshWindow
  18. gadtools.library/GT_ReplyIMsg
  19. gadtools.library/GT_SetGadgetAttrsA
  20. gadtools.library/LayoutMenuItemsA
  21. gadtools.library/LayoutMenusA
  22. gadtools.library/CreateContext                 gadtools.library/CreateContext
  23.  
  24.    NAME
  25.     CreateContext -- create a place for GadTools context data. (V36)
  26.  
  27.    SYNOPSIS
  28.     gad = CreateContext(glistpointer);
  29.     D0                  A0
  30.  
  31.     struct Gadget *CreateContext(struct Gadget **);
  32.  
  33.    FUNCTION
  34.     Creates a place for GadTools to store any context data it might
  35.     need for your window.  In reality, an unselectable invisible
  36.     gadget is created, with room for the context data.
  37.     This function also establishes the linkage from a glist type
  38.     pointer to the individual gadget pointers.  Call this function
  39.     before any of the other gadget creation calls.
  40.  
  41.    INPUTS
  42.     glistptr - address of a pointer to a Gadget, which was previously
  43.                set to NULL.  When all the gadget creation is done, you may
  44.                use that pointer as your NewWindow.FirstGadget, or
  45.                in intuition.library/AddGList(),
  46.                intuition.library/RefreshGList(), FreeGadgets(), etc.
  47.  
  48.    RESULT
  49.     gad - pointer to context gadget, or NULL if failure.
  50.  
  51.    EXAMPLE
  52.  
  53.     struct Gadget *gad;
  54.     struct Gadget *glist = NULL;
  55.     gad = CreateContext(&glist);
  56.     /*  Other creation calls go here */
  57.     if (gad)
  58.     {
  59.         myNewWindow.FirstGadget = glist;
  60.         if ( myWindow = OpenWindow(&myNewWindow) )
  61.         {
  62.         GT_RefreshWindow(win,NULL);
  63.         /* other stuff */
  64.         CloseWindow(myWindow);
  65.         }
  66.     }
  67.     FreeGadgets(glist);
  68.  
  69. gadtools.library/CreateGadgetA                 gadtools.library/CreateGadgetA
  70.  
  71.    NAME
  72.     CreateGadgetA -- allocate and initialize a gadtools gadget. (V36)
  73.     CreateGadget -- varargs stub for CreateGadgetA(). (V36)
  74.  
  75.    SYNOPSIS
  76.     gad = CreateGadgetA(kind, previous, newgad, tagList)
  77.     D0                  D0    A0        A1      A2
  78.  
  79.     struct Gadget *CreateGadgetA(ULONG, struct Gadget *,
  80.                                  struct NewGadget *, struct TagItem *);
  81.  
  82.     gad = CreateGadget(kind, previous, newgad, firsttag, ...)
  83.  
  84.     struct Gadget *CreateGadget(ULONG, struct Gadget *,
  85.                                 struct NewGadget *, Tag, ...);
  86.  
  87.    FUNCTION
  88.     CreateGadgetA() allocates and initializes a new gadget of the
  89.     specified kind, and attaches it to the previous gadget.  The
  90.     gadget is created based on the supplied kind, NewGadget structure,
  91.     and tags.
  92.  
  93.    INPUTS
  94.     kind - kind of gadget is to be created, one of the XXX_KIND values
  95.            defined in <libraries/gadtools.h>
  96.     previous - pointer to the previous gadget that this new gadget
  97.                is to be attached to. This function will fail if this value
  98.            is NULL
  99.     newgad - a filled in NewGadget structure describing the desired
  100.              gadget's size, position, label, etc.
  101.     tagList - pointer to an array of tags providing optional extra
  102.           parameters, or NULL
  103.  
  104.    TAGS
  105.     All kinds:
  106.     GT_Underscore - Indicates the symbol that precedes the character in
  107.         the gadget label to be underscored.  This can be to indicate
  108.         keyboard equivalents for gadgets (note that GadTools does not
  109.         process the keys - it just displays the underscore).  For example,
  110.         to underscore the "M" in "Mode":
  111.         ng.ng_GadgetText = "_Mode:";
  112.         gad = CreateGadget(..._KIND, &ng, prev,
  113.             GT_Underscore, '_',
  114.             ...
  115.             );
  116.         (V37)
  117.  
  118.     BUTTON_KIND (action buttons):
  119.     GA_Disabled (BOOL) - Set to TRUE to disable gadget, FALSE otherwise
  120.         (defaults to FALSE). (V36)
  121.     GA_Immediate (BOOL) - Hear IDCMP_GADGETDOWN events from button gadget
  122.         (defaults to FALSE). (V39)
  123.  
  124.     CHECKBOX_KIND (on/off items):
  125.     GA_Disabled (BOOL) - Set to TRUE to disable gadget, FALSE otherwise
  126.         (defaults to FALSE).
  127.     GTCB_Checked (BOOL) - Initial state of checkbox (defaults to FALSE)
  128.         (V36)
  129.     GTCB_Scaled (BOOL) - If true, then checkbox imagery will be scaled to
  130.         fit the gadget's width & height.  Otherwise, a fixed size of
  131.         CHECKBOXWIDTH by CHECKBOXHEIGHT will be used. (defaults to FALSE)
  132.         (V39)
  133.  
  134.     CYCLE_KIND (multiple state selections):
  135.     GA_Disabled (BOOL) - Set to TRUE to disable gadget, FALSE otherwise
  136.         (defaults to FALSE). (V37)
  137.     GTCY_Labels (STRPTR *) - Pointer to NULL-terminated array of strings
  138.         that are the choices offered by the cycle gadget. This tag is
  139.         required. (V36)
  140.     GTCY_Active (UWORD) - The ordinal number (counting from zero) of
  141.         the initially active choice of a cycle gadget (defaults to zero).
  142.         (V36)
  143.  
  144.     INTEGER_KIND (numeric entry):
  145.     GA_Disabled (BOOL) - Set to TRUE to disable gadget, FALSE otherwise
  146.         (defaults to FALSE). (V36)
  147.     GA_Immediate (BOOL) - Hear IDCMP_GADGETDOWN events from integer
  148.         gadget (defaults to FALSE). (V39)
  149.     GA_TabCycle (BOOL) - Set to TRUE so that pressing <TAB> or <Shift-TAB>
  150.         will activate the next or previous such gadget. (defaults to TRUE,
  151.         unlike regular Intuition string gadgets which default to FALSE).
  152.         (V37)
  153.     GTIN_Number (LONG) - The initial contents of the integer gadget
  154.         (defaults to 0). (V36)
  155.     GTIN_MaxChars (UWORD) - The maximum number of digits that the
  156.         integer gadget is to hold (defaults to 10). (V36)
  157.     GTIN_EditHook (struct Hook *) - Hook to use as a custom
  158.         integer gadget edit hook (StringExtend->EditHook) for this gadget.
  159.         GadTools will allocate the StringExtend->WorkBuffer for you.
  160.         (defaults to NULL). (V37)
  161.     STRINGA_ExitHelp (BOOL) - Set to TRUE to have the help-key cause an
  162.         exit from the integer gadget.  You will then receive an
  163.         IDCMP_GADGETUP event with Code = 0x5F (rawkey for help).
  164.         (defaults to FALSE) (V37)
  165.     STRINGA_Justification - Controls the justification of the contents of
  166.         an integer gadget.  Choose one of STRINGLEFT, STRINGRIGHT, or
  167.         STRINGCENTER (defaults to STRINGLEFT). (V37)
  168.     STRINGA_ReplaceMode (BOOL) - If TRUE, this integer gadget is in
  169.         replace-mode (defaults to FALSE (insert-mode)). (V37)
  170.  
  171.     LISTVIEW_KIND (scrolling list):
  172.     GA_Disabled (BOOL) - Set to TRUE to disable gadget, FALSE otherwise
  173.         (defaults to FALSE). (V39)
  174.     GTLV_Top (WORD) - Top item visible in the listview.  This value
  175.         will be made reasonable if out-of-range (defaults to 0). (V36)
  176.     GTLV_MakeVisible (WORD) - Number of an item that should be forced
  177.         within the visible area of the listview by doing minimal scrolling.
  178.         This tag overrides GTLV_Top. (V39)
  179.     GTLV_Labels (struct List *) - List of nodes whose ln_Name fields
  180.         are to be displayed in the listview. (V36)
  181.     GTLV_ReadOnly (BOOL) - If TRUE, then listview is read-only
  182.         (defaults to FALSE). (V36)
  183.     GTLV_ScrollWidth (UWORD) - Width of scroll bar for listview.
  184.         Must be greater than zero (defaults to 16). (V36)
  185.     GTLV_ShowSelected (struct Gadget *) - NULL to have the currently
  186.         selected item displayed beneath the listview under V37 or with
  187.         a highlight bar in V39. If not NULL, this is a pointer to
  188.         an already-created GadTools STRING_KIND gadget to have an
  189.         editable display of the currently selected item. If the tag is
  190.         not present, the currently selected item will not be displayed.
  191.         (V36)
  192.     GTLV_Selected (UWORD) - Ordinal number of currently selected
  193.         item, or ~0 to have no current selection (defaults to ~0). (V36)
  194.     LAYOUTA_Spacing (UWORD) - Extra space to place between lines of
  195.         listview (defaults to 0). (V36)
  196.     GTLV_ItemHeight (UWORD) - The exact height of an item. This is
  197.         normally useful for listviews that use the GTLV_CallBack
  198.         rendering hook (defaults to ng->ng_TextAttr->ta_YSize). (V39)
  199.     GTLV_CallBack (struct Hook *) - Callback hook for various listview
  200.         operations. As of V39, the only callback supported is for custom
  201.         rendering of individual items in the listview. The call back hook
  202.         is called with:
  203.         A0 - struct Hook *
  204.         A1 - struct LVDrawMsg *
  205.         A2 - struct Node *
  206.         The callback hook *must* check the lvdm_MethodID field of the
  207.         message and only do processing if it equals LV_DRAW. If any
  208.         other value is passed, the callback hook must return LVCB_UNKNOWN
  209.     GTLV_MaxPen (UWORD) - The maximum pen number used by rendering
  210.         in a custom rendering callback hook. This is used to optimize
  211.         the rendering and scrolling of the listview display (default is
  212.         the maximum pen number used by all of TEXTPEN, BACKGROUNDPEN,
  213.         FILLPEN, TEXTFILLPEN, and BLOCKPEN. (V39)
  214.  
  215.     MX_KIND (mutually exclusive, radio buttons):
  216.     GA_Disabled (BOOL) - Set to TRUE to disable gadget, FALSE otherwise
  217.         (defaults to FALSE). (V39)
  218.     GTMX_Labels (STRPTR *) - Pointer to a NULL-terminated array of
  219.         strings which are to be the labels beside each choice in a
  220.         set of mutually exclusive gadgets. This tag is required. (V36)
  221.     GTMX_Active (UWORD) - The ordinal number (counting from zero) of
  222.         the initially active choice of an mx gadget (defaults to 0). (V36)
  223.     GTMX_Spacing (UWORD) - The amount of space between each choice
  224.         of a set of mutually exclusive gadgets.  This amount is added
  225.         to the font height to produce the vertical shift between
  226.         choices (defaults to 1). (V36)
  227.     GTMX_Scaled (BOOL) - If true, then mx gadget imagery will be scaled
  228.         to fit the gadget's width & height.  Otherwise, a fixed size of
  229.         MXWIDTH by MXHEIGHT will be used. When setting this tag to TRUE,
  230.         you should typically set the height of the gadget to be
  231.         (ng.ng_TextAttr->ta_YSize + 1). (defaults to FALSE.) (V39)
  232.     GTMX_TitlePlace - One of PLACETEXT_LEFT, PLACETEXT_RIGHT,
  233.         PLACETEXT_ABOVE, or PLACETEXT_BELOW, indicating where the title
  234.         of the gadget is to be displayed. Without this tag, the
  235.         NewGadget.ng_GadgetText field is ignored for MX_KIND gadgets.
  236.         (V39)
  237.     LAYOUTA_Spacing - FOR COMPATIBILITY ONLY.  Use GTMX_Spacing instead.
  238.         The number of extra pixels to insert between each choice of a
  239.         mutually exclusive gadget.  This is added to the present gadget
  240.         image height (9) to produce the true spacing between choices.
  241.         (defaults to FontHeight-8, which is zero for 8-point font users).
  242.         (V36)
  243.  
  244.     NUMBER_KIND (read-only numeric):
  245.     GTNM_Number (LONG) - A signed long integer to be displayed as a read-only
  246.         number (defaults to 0). (V36)
  247.     GTNM_Border (BOOL) - If TRUE, this flag asks for a recessed border to
  248.         be placed around the gadget. (V36)
  249.     GTNM_FrontPen (UBYTE) - The pen to use when rendering the number
  250.         (defaults to DrawInfo->dri_Pens[TEXTPEN]). (V39)
  251.     GTNM_BackPen (UBYTE) - The pen to use when rendering the background
  252.         of the number (defaults to leaving the background untouched).
  253.         (V39)
  254.     GTNM_Justification (UBYTE) - Determines how the number is rendered
  255.         within the gadget box. GTJ_LEFT will make the rendering be
  256.         flush with the left side of the gadget, GTJ_RIGHT will make it
  257.         flush with the right side, and GTJ_CENTER will center the number
  258.         within the gadget box. Under V39, using this tag also required
  259.         using {GTNM_Clipped, TRUE}, otherwise the text would not show
  260.         up in the gadget. This has been fixed in V40.
  261.         (defaults to GTJ_LEFT). (V39)
  262.     GTNM_Format (STRPTR) - C-Style formatting string to apply on the number
  263.         before display. Be sure to use the 'l' (long) modifier. This string
  264.         is processed using exec.library/RawDoFmt(), so refer to that
  265.         function for details. (defaults to "%ld") (V39)
  266.     GTNM_MaxNumberLen (ULONG) - Maximum number of bytes that can be
  267.         generated by applying the GTNM_Format formatting string to the
  268.         number (excluding the NULL terminator). (defaults to 10). (V39)
  269.     GTNM_Clipped (BOOL) - Determine whether text should be clipped to
  270.         the gadget dimensions (defaults to FALSE for gadgets without
  271.         borders, TRUE for gadgets with borders). (V39)
  272.  
  273.     PALETTE_KIND (color selection):
  274.     GA_Disabled (BOOL) - Set to TRUE to disable gadget, FALSE otherwise
  275.         (defaults to FALSE). (V36)
  276.     GTPA_Depth (UWORD) - Number of bitplanes in the palette
  277.         (defaults to 1). (V36)
  278.     GTPA_Color (UBYTE) - Initially selected color of the palette. This
  279.         number is a pen number, and not the ordinal color number within
  280.         the palette gadget itself. (defaults to 1). (V36)
  281.     GTPA_ColorOffset (UBYTE) - First color to use in palette
  282.         (defaults to 0). (V36)
  283.     GTPA_IndicatorWidth (UWORD) - The desired width of the current-color
  284.         indicator, if you want one to the left of the palette. (V36)
  285.     GTPA_IndicatorHeight (UWORD) - The desired height of the current-color
  286.         indicator, if you want one above the palette. (V36)
  287.     GTPA_ColorTable (UBYTE *) - Pointer to a table of pen numbers
  288.         indicating  which colors should be used and edited by the palette
  289.         gadget. This array must contain as many entries as there are
  290.         colors displayed in the palette gadget. The array provided with
  291.         this tag must remain valid for the life of the gadget or until a
  292.         new table is provided. (default is NULL, which causes a 1-to-1
  293.         mapping of pen numbers). (V39)
  294.     GTPA_NumColors (UWORD) - Number of colors to display in the palette
  295.         gadget. This override GTPA_Depth and allows numbers which aren't
  296.         powers of 2. (defaults to 2) (V39)
  297.  
  298.     SCROLLER_KIND (for scrolling through areas or lists):
  299.     GA_Disabled (BOOL) - Set to TRUE to disable gadget, FALSE otherwise
  300.         (defaults to FALSE). (V36)
  301.     GA_RelVerify (BOOL) - Hear every IDCMP_GADGETUP event from scroller
  302.         (defaults to FALSE). (V36)
  303.     GA_Immediate (BOOL) - Hear every IDCMP_GADGETDOWN event from scroller
  304.         (defaults to FALSE). (V36)
  305.     GTSC_Top (WORD) - Top visible in area scroller represents
  306.         (defaults to 0). (V36)
  307.     GTSC_Total (WORD) - Total in area scroller represents
  308.         (defaults to 0). (V36)
  309.     GTSC_Visible (WORD) - Number visible in scroller (defaults to 2). (V36)
  310.     GTSC_Arrows (UWORD) - Asks for arrows to be attached to the scroller.
  311.         The value supplied will be taken as the width of each arrow button
  312.         for a horizontal scroller, or the height of each button for a
  313.         vertical scroller (the other dimension will match the whole
  314.         scroller). (V36)
  315.     PGA_Freedom - Whether scroller is horizontal or vertical.
  316.         Choose LORIENT_VERT or LORIENT_HORIZ (defaults to LORIENT_HORIZ).
  317.         (V36)
  318.  
  319.     SLIDER_KIND (to indicate level or intensity):
  320.     GA_Disabled (BOOL) - Set to TRUE to disable gadget, FALSE otherwise
  321.         (defaults to FALSE). (V36)
  322.     GA_RelVerify (BOOL) - If you want to hear each slider IDCMP_GADGETUP
  323.         event (defaults to FALSE). (V36)
  324.     GA_Immediate (BOOL) - If you want to hear each slider IDCMP_GADGETDOWN
  325.         event (defaults to FALSE). (V36)
  326.     GTSL_Min (WORD) - Minimum level for slider (defaults to 0). (V36)
  327.     GTSL_Max (WORD) - Maximum level for slider (defaults to 15). (V36)
  328.     GTSL_Level (WORD) - Current level of slider (defaults to 0). (V36)
  329.     GTSL_MaxLevelLen (UWORD) - Maximum length in characters of level string
  330.         when rendered beside slider (defaults to 2). (V36)
  331.     GTSL_LevelFormat (STRPTR) - C-Style formatting string for slider
  332.         level.  Be sure to use the 'l' (long) modifier.  This string
  333.         is processed using exec.library/RawDoFmt(), so refer to that
  334.         function for details. (defaults to "%ld"). (V36)
  335.     GTSL_LevelPlace - One of PLACETEXT_LEFT, PLACETEXT_RIGHT,
  336.         PLACETEXT_ABOVE, or PLACETEXT_BELOW, indicating where the level
  337.         indicator is to go relative to slider (default to PLACETEXT_LEFT).
  338.         (V36)
  339.     GTSL_DispFunc ( LONG (*function)(struct Gadget *, WORD) ) - Function
  340.         to calculate level to be displayed.  A number-of-colors slider
  341.         might want to set the slider up to think depth, and have a
  342.         (1 << n) function here.  Defaults to none.  Your function must
  343.         take a pointer to gadget as the first parameter, the level
  344.         (a WORD) as the second, and return the result as a LONG. (V36)
  345.     GTSL_MaxPixelLen (ULONG) - Indicates the maximum pixel size used up
  346.         by the level display for any value of the slider. This is mostly
  347.         useful when dealing with proportional fonts. (defaults to
  348.         FontWidth*MaxLevelLen). (V39)
  349.     GTSL_Justification (UBYTE) - Determines how the level display is to
  350.         be justified within its alotted space. Choose one of GTJ_LEFT,
  351.         GTJ_RIGHT, or GTJ_CENTER (defaults to GTJ_LEFT). (V39)
  352.     PGA_Freedom - Set to LORIENT_VERT or LORIENT_HORIZ to have a
  353.         vertical or horizontal slider (defaults to LORIENT_HORIZ). (V36)
  354.  
  355.     STRING_KIND (text-entry):
  356.     GA_Disabled (BOOL) - Set to TRUE to disable gadget, FALSE otherwise
  357.         (defaults to FALSE). (V36)
  358.     GA_Immediate (BOOL) - Hear IDCMP_GADGETDOWN events from string
  359.         gadget (defaults to FALSE). (V39)
  360.     GA_TabCycle (BOOL) - Set to TRUE so that pressing <TAB> or <Shift-TAB>
  361.         will activate the next or previous such gadget. (defaults to TRUE,
  362.         unlike regular Intuition string gadgets which default to FALSE).
  363.         (V37)
  364.     GTST_String (STRPTR) - The initial contents of the string gadget,
  365.         or NULL (default) if string is to start empty. (V36)
  366.     GTST_MaxChars (UWORD) - The maximum number of characters that the
  367.         string gadget is to hold. (V36)
  368.     GTST_EditHook (struct Hook *) - Hook to use as a custom string gadget
  369.         edit hook (StringExtend->EditHook) for this gadget. GadTools will
  370.         allocate the StringExtend->WorkBuffer for you. (defaults to NULL).
  371.         (V37)
  372.     STRINGA_ExitHelp (BOOL) - Set to TRUE to have the help-key cause an
  373.         exit from the string gadget.  You will then receive an
  374.         IDCMP_GADGETUP event with Code = 0x5F (rawkey for help).
  375.         (V37)
  376.     STRINGA_Justification - Controls the justification of the contents of
  377.         a string gadget.  Choose one of STRINGLEFT, STRINGRIGHT, or
  378.         STRINGCENTER (defaults to STRINGLEFT). (V37)
  379.     STRINGA_ReplaceMode (BOOL) - If TRUE, this string gadget is in
  380.         replace-mode (defaults to FALSE (insert-mode)). (V37)
  381.  
  382.     TEXT_KIND (read-only text):
  383.     GTTX_Text - Pointer to a NULL terminated string to be displayed,
  384.         as a read-only text-display gadget, or NULL. (defaults to NULL)
  385.         (V36)
  386.     GTTX_CopyText (BOOL) -    This flag instructs the text-display gadget
  387.         to copy the supplied text string, instead of using only
  388.         pointer to the string.  This only works for the initial value
  389.         of GTTX_Text set at CreateGadget() time.  If you subsequently
  390.         change GTTX_Text, the new text will be referenced by pointer,
  391.         not copied.  Do not use this tag with a NULL GTTX_Text. (V37)
  392.     GTTX_Border (BOOL) - If TRUE, this flag asks for a recessed
  393.         border to be placed around the gadget. (V36)
  394.     GTTX_FrontPen (UBYTE) - The pen to use when rendering the text
  395.         (defaults to DrawInfo->dri_Pens[TEXTPEN]). (V39)
  396.     GTTX_BackPen (UBYTE) - The pen to use when rendering the background
  397.         of the text (defaults to leaving the background untouched).
  398.         (V39)
  399.     GTTX_Justification (UBYTE) - Determines how the text is rendered
  400.         within the gadget box. GTJ_LEFT will make the rendering be
  401.         flush with the left side of the gadget, GTJ_RIGHT will make it
  402.         flush with the right side, and GTJ_CENTER will center the text
  403.         within the gadget box. Under V39, using this tag also required
  404.         using {GTNM_Clipped, TRUE}, otherwise the text would not show
  405.         up in the gadget. This has been fixed in V40.
  406.         (defaults to GTJ_LEFT). (V39)
  407.     GTTX_Clipped (BOOL) - Determine whether text should be clipped to
  408.         the gadget dimensions (defaults to FALSE for gadgets without
  409.         borders, TRUE for gadgets with borders). (V39)
  410.  
  411.    RESULT
  412.     gad - pointer to the new gadget, or NULL if the allocation failed
  413.           or if previous was NULL.
  414.  
  415.    NOTES
  416.     Note that the ng_VisualInfo and ng_TextAttr fields of the
  417.     NewGadget structure must be set to valid VisualInfo and
  418.     TextAttr pointers, or this function will fail.
  419.  
  420.     Starting with V37, string and integer gadgets have the GFLG_TABCYCLE
  421.     feature automatically.  If the user presses Tab or Shift-Tab while
  422.     in a string or integer gadget, the next or previous one in
  423.     sequence will be activated.  You will hear an IDCMP_GADGETUP message
  424.     with a code of 0x09.  Use {GA_TabCycle, FALSE} to supress this.
  425.  
  426.    SEE ALSO
  427.     FreeGadgets(), GT_SetGadgetAttrs(), GetVisualInfo(),
  428.     <libraries/gadtools.h>
  429.  
  430. gadtools.library/CreateMenusA                   gadtools.library/CreateMenusA
  431.  
  432.    NAME
  433.     CreateMenusA -- allocate and fill out a menu structure. (V36)
  434.     CreateMenus -- varargs stub for CreateMenus(). (V36)
  435.  
  436.    SYNOPSIS
  437.     menu = CreateMenusA(newmenu, tagList)
  438.     D0                  A0       A1
  439.  
  440.     struct Menu *CreateMenusA(struct NewMenu *, struct TagItem *);
  441.  
  442.     menu = CreateMenus(newmenu, firsttag, ...)
  443.  
  444.     struct Menu *CreateMenus(struct NewMenu *, Tag, ...);
  445.  
  446.    FUNCTION
  447.     CreateMenusA() allocates and initializes a complete menu
  448.     structure based on the supplied array of NewMenu structures.
  449.     Optionally, CreateMenusA() can allocate and initialize a complete
  450.     set of menu items and sub-items for a single menu title.  This
  451.     is dictated by the contents of the array of NewMenus.
  452.  
  453.    INPUTS
  454.     newmenu - pointer to an array of initialized struct NewMenus.
  455.     tagList - pointer to an array of tags providing optional extra
  456.           parameters, or NULL.
  457.  
  458.    TAGS
  459.     GTMN_FrontPen (UBYTE) - Pen number to be used for menu text.
  460.         (Under V39 and higher, this tag also exists for LayoutMenusA()
  461.         and LayoutMenuItemsA()).  (defaults to zero).
  462.     GTMN_FullMenu (BOOL) - Requires that the NewMenu specification
  463.         describes a complete menu strip, not a fragment.  If a fragment
  464.         is found, CreateMenusA() will fail with a secondary error of
  465.         GTMENU_INVALID.  (defaults to FALSE). (V37)
  466.     GTMN_SecondaryError (ULONG *) - Supply a pointer to a NULL-initialized
  467.         ULONG to receive a descriptive error code.  Possible values:
  468.         GTMENU_INVALID - NewMenu structure describes an illegal
  469.             menu.  (CreateMenusA() will fail with a NULL result).
  470.         GTMENU_TRIMMED - NewMenu structure has too many menus, items,
  471.             or subitems (CreateMenusA() will succeed, returning a
  472.             trimmed-down menu structure).
  473.         GTMENU_NOMEM - CreateMenusA() ran out of memory.
  474.         (V37)
  475.  
  476.    RESULT
  477.     menu - pointer to the resulting initialized menu structure (or
  478.               the resulting FirstItem), with all the links for menu items
  479.               and subitems in place.
  480.               The result will be NULL if CreateMenusA() could not allocate
  481.               memory for the menus, or if the NewMenu array had an
  482.               illegal arrangement (eg. NM_SUB following NM_TITLE).
  483.               (see also the GTMN_SecondaryError tag above).
  484.  
  485.    NOTES
  486.     The strings you supply for menu text are not copied, and must
  487.     be preserved for the life of the menu.
  488.     The resulting menus have no positional information.  You will
  489.     want to call LayoutMenusA() (or LayoutMenuItemsA()) to supply that.
  490.     CreateMenusA() automatically provides you with a UserData field
  491.     for each menu, menu-item or sub-item.  Use the GTMENU_USERDATA(menu)
  492.     or GTMENUITEM_USERDATA(menuitem) macro to access it.
  493.  
  494.    BUGS
  495.     Prior to V39, if you put images into menus using IM_ITEM
  496.     or IM_SUB for a NewMenu->nm_Type, the image supplied had to
  497.     be an ordinary struct Image.  Starting with V39, you can use
  498.     boopsi images.
  499.  
  500.    SEE ALSO
  501.     LayoutMenusA(), FreeMenus(), gadtools.h/GTMENU_USERDATA(),
  502.     gadtools.h/GTMENUITEM_USERDATA()
  503.  
  504. gadtools.library/DrawBevelBoxA                 gadtools.library/DrawBevelBoxA
  505.  
  506.    NAME
  507.     DrawBevelBoxA -- draw a bevelled box. (V36)
  508.     DrawBevelBox -- varargs stub for DrawBevelBoxA(). (V36)
  509.  
  510.    SYNOPSIS
  511.     DrawBevelBoxA(rport, left, top, width, height, tagList);
  512.                   A0     D0    D1   D2     D3      A1
  513.  
  514.     VOID DrawBevelBoxA(struct RastPort *, WORD, WORD, WORD, WORD,
  515.                        struct TagItem *taglist);
  516.  
  517.     DrawBevelBox(rport, left, top, width, height, firsttag, ...);
  518.  
  519.     VOID DrawBevelBox(struct RastPort *, WORD, WORD, WORD, WORD,
  520.                       Tag, ...);
  521.  
  522.    FUNCTION
  523.     This function renders a bevelled box of specified dimensions
  524.     and type into the supplied RastPort.
  525.  
  526.    INPUTS
  527.     rport - RastPort into which the box is to be drawn.
  528.     left - left edge of the box.
  529.     top - top edge of the box.
  530.     width - width of the box.
  531.     height - height of the box.
  532.     tagList - pointer to an array of tags providing extra parameters
  533.  
  534.    TAGS
  535.     GTBB_Recessed (BOOL) - Set to anything for a recessed-looking box.
  536.             If absent, the box defaults, it would be raised. (V36)
  537.  
  538.     GTBB_FrameType (ULONG) - Determines what kind of box this function
  539.             renders. BBFT_BUTTON generates a box like what is
  540.             used around GadTools BUTTON_KIND gadgets. BBFT_RIDGE
  541.             generates a box like what is used around GadTools
  542.             STRING_KIND gadgets. Finally, BBFT_ICONDROPBOX
  543.             generates a box suitable for a standard icon drop
  544.             box imagery. (defaults to BBFT_BUTTON). (V39)
  545.  
  546.     GT_VisualInfo (APTR) - You MUST supply the value you obtained
  547.             from an earlier call to GetVisualInfoA() with this
  548.             tag. (V36)
  549.  
  550.    NOTES
  551.     DrawBevelBox() is a rendering operation, not a gadget. That
  552.     means you must refresh it at the appropriate time, like any
  553.     other rendering operation.
  554.  
  555.    SEE ALSO
  556.     GetVisualInfoA(), <libraries/gadtools.h>
  557.  
  558. gadtools.library/FreeGadgets                     gadtools.library/FreeGadgets
  559.  
  560.    NAME
  561.     FreeGadgets -- free a linked list of gadgets. (V36)
  562.  
  563.    SYNOPSIS
  564.     FreeGadgets(glist)
  565.                 A0
  566.  
  567.     VOID FreeGadgets(struct Gadget *glist);
  568.                      A0
  569.  
  570.    FUNCTION
  571.     Frees any GadTools gadgets found on the linked list of gadgets
  572.     beginning with the specified one.  Frees all the memory that was
  573.     allocated by CreateGadgetA().  This function will return safely
  574.     with no action if it receives a NULL parameter.
  575.  
  576.    INPUTS
  577.     glist - pointer to first gadget in list to be freed.
  578.  
  579.    SEE ALSO
  580.     CreateGadgetA()
  581.  
  582. gadtools.library/FreeMenus                         gadtools.library/FreeMenus
  583.  
  584.    NAME
  585.     FreeMenus -- frees memory allocated by CreateMenusA(). (V36)
  586.  
  587.    SYNOPSIS
  588.     FreeMenus(menu)
  589.               A0
  590.  
  591.     VOID FreeMenus(struct Menu *);
  592.  
  593.    FUNCTION
  594.     Frees the menus allocated by CreateMenusA().  It is safe to
  595.     call this function with a NULL parameter.
  596.  
  597.    INPUTS
  598.     menu - pointer to menu structure (or first MenuItem) obtained
  599.            from CreateMenusA().
  600.  
  601.    SEE ALSO
  602.     CreateMenusA()
  603.  
  604. gadtools.library/FreeVisualInfo               gadtools.library/FreeVisualInfo
  605.  
  606.    NAME
  607.     FreeVisualInfo -- return any resources taken by GetVisualInfo. (V36)
  608.  
  609.    SYNOPSIS
  610.     FreeVisualInfo(vi)
  611.                    A0
  612.  
  613.     VOID FreeVisualInfo(APTR);
  614.  
  615.    FUNCTION
  616.     FreeVisualInfo() returns any memory or other resources that
  617.     were allocated by GetVisualInfoA().  You should only call this function
  618.     once you are done with using the gadgets (i.e. after CloseWindow()),
  619.     but while the screen is still valid (i.e. before CloseScreen() or
  620.     UnlockPubScreen()).
  621.  
  622.    INPUTS
  623.     vi - pointer that was obtained by calling GetVisualInfoA(). This
  624.          value may be NULL.
  625.  
  626.    SEE ALSO
  627.     GetVisualInfoA()
  628.  
  629. gadtools.library/GetVisualInfoA               gadtools.library/GetVisualInfoA
  630.  
  631.    NAME
  632.     GetVisualInfoA -- get information GadTools needs for visuals. (V36)
  633.     GetVisualInfo -- varargs stub for GetVisualInfoA(). (V36)
  634.  
  635.    SYNOPSIS
  636.     vi = GetVisualInfoA(screen, tagList)
  637.     D0                  A0      A1
  638.  
  639.     APTR vi = GetVisualInfoA(struct Screen *, struct TagItem *);
  640.  
  641.     vi = GetVisualInfo(screen, firsttag, ...)
  642.  
  643.     APTR vi = GetVisualInfo(struct Screen *, Tag, ...);
  644.  
  645.    FUNCTION
  646.     Get a pointer to a (private) block of data containing various bits
  647.     of information that GadTools needs to ensure the best quality
  648.     visuals.  Use the result in the NewGadget structure of any gadget
  649.     you create, or as a parameter to the various menu calls.  Once the
  650.     gadgets/menus are no longer needed (after the last CloseWindow),
  651.     call FreeVisualInfo().
  652.  
  653.    INPUTS
  654.     screen - pointer to the screen you will be opening on. This parameter
  655.          may be NULL, in which case this function fails.
  656.     tagList - pointer to an array of tags providing optional extra
  657.           parameters, or NULL.
  658.  
  659.    TAGS
  660.     There are currently no tags defined for this function.
  661.  
  662.    RESULT
  663.     vi - pointer to private data, or NULL for failure
  664.  
  665.    SEE ALSO
  666.     FreeVisualInfo(), intuition/LockPubScreen(),
  667.     intuition/UnlockPubScreen()
  668.  
  669. gadtools.library/GT_BeginRefresh             gadtools.library/GT_BeginRefresh
  670.  
  671.    NAME
  672.     GT_BeginRefresh -- begin refreshing friendly to GadTools. (V36)
  673.  
  674.    SYNOPSIS
  675.     GT_BeginRefresh(win)
  676.                     A0
  677.  
  678.     VOID GT_BeginRefresh(struct Window *);
  679.  
  680.    FUNCTION
  681.     Invokes the intuition.library/BeginRefresh() function in a manner
  682.     friendly to the Gadget Toolkit.  This function call permits the
  683.     GadTools gadgets to refresh themselves at the correct time.
  684.     Call GT_EndRefresh() function when done.
  685.  
  686.    INPUTS
  687.     win - pointer to Window structure for which a IDCMP_REFRESHWINDOW
  688.           IDCMP event was received.
  689.  
  690.    NOTES
  691.     The nature of GadTools precludes the use of the IDCMP flag
  692.     WFLG_NOCAREREFRESH.  You must handle IDCMP_REFRESHWINDOW events
  693.     in at least the minimal way, namely:
  694.  
  695.         case IDCMP_REFRESHWINDOW:
  696.             GT_BeginRefresh(win);
  697.             GT_EndRefresh(win, TRUE);
  698.             break;
  699.  
  700.    SEE ALSO
  701.     intuition.library/BeginRefresh()
  702.  
  703. gadtools.library/GT_EndRefresh                 gadtools.library/GT_EndRefresh
  704.  
  705.    NAME
  706.     GT_EndRefresh -- end refreshing friendly to GadTools. (V36)
  707.  
  708.    SYNOPSIS
  709.     GT_EndRefresh(win, complete)
  710.                   A0   D0
  711.  
  712.     VOID GT_EndRefresh(struct Window *, BOOL complete);
  713.  
  714.    FUNCTION
  715.     Invokes the intuition.library/EndRefresh() function in a manner
  716.     friendly to the Gadget Toolkit.  This function call permits
  717.     GadTools gadgets to refresh themselves at the correct time.
  718.     Call this function to EndRefresh() when you have used
  719.     GT_BeginRefresh().
  720.  
  721.    INPUTS
  722.     win - pointer to Window structure for which a IDCMP_REFRESHWINDOW
  723.           IDCMP event was received.
  724.     complete - TRUE when done with refreshing.
  725.  
  726.    SEE ALSO
  727.     intuition.library/EndRefresh()
  728.  
  729. gadtools.library/GT_FilterIMsg                 gadtools.library/GT_FilterIMsg
  730.  
  731.    NAME
  732.     GT_FilterIMsg -- filter an IntuiMessage through GadTools. (V36)
  733.  
  734.    SYNOPSIS
  735.     modimsg = GT_FilterIMsg(imsg)
  736.     D0                      A1
  737.  
  738.     struct IntuiMessage *GT_FilterIMsg(struct IntuiMessage *);
  739.  
  740.    FUNCTION
  741.     NOTE WELL:  Extremely few programs will actually need this function.
  742.     You almost certainly should be using GT_GetIMsg() and GT_ReplyIMsg()
  743.     only, and not GT_FilterIMsg() and GT_PostFilterIMsg().
  744.  
  745.     GT_FilterIMsg() takes the supplied IntuiMessage and asks the
  746.     Gadget Toolkit to consider and possibly act on it.  Returns
  747.     NULL if the message was only of significance to a GadTools gadget
  748.     (i.e. not to you), else returns a pointer to a modified IDCMP
  749.     message, which may contain additional information.
  750.  
  751.     You should examine the Class, Code, and IAddress fields of
  752.     the returned message to learn what happened.  Do not make
  753.     interpretations based on the original imsg.
  754.  
  755.     You should use GT_PostFilterIMsg() to revert to the original
  756.     IntuiMessage once you are done with the modified one.
  757.  
  758.    INPUTS
  759.     imsg - an IntuiMessage you obtained from a Window's UserPort.
  760.  
  761.    RESULT
  762.     modimsg - a modified IntuiMessage, possibly with extra information
  763.               from GadTools, or NULL. When NULL, the message passed in to
  764.           the function should be sent back to Intuition via ReplyMsg()
  765.  
  766.    NOTES
  767.     Starting with V39, this function actually expects and returns
  768.     pointers to ExtIntuiMessage structures, but the prototype was not
  769.     changed for source code compatibility with older software.
  770.  
  771.    WARNING
  772.     If this function returns NULL, you must call ReplyMsg() on the
  773.     IntuiMessage you passed in to GT_FilterIMsg(). That is, if the
  774.     message was processed by the toolkit you must reply this message
  775.     to Intuition since gadtools will not do this automatically.
  776.  
  777.    SEE ALSO
  778.     GT_GetIMsg(), GT_PostFilterIMsg()
  779.  
  780. gadtools.library/GT_GetGadgetAttrsA       gadtools.library/GT_GetGadgetAttrsA
  781.  
  782.    NAME
  783.     GT_GetGadgetAttrsA -- request the attributes of a GadTools gadget. (V39)
  784.     GT_GetGadgetAttrs -- varargs stub for GT_GetGadgetAttrsA(). (V39)
  785.  
  786.    SYNOPSIS
  787.     numProcessed = GT_GetGadgetAttrsA(gad, win, req, taglist)
  788.                                       A0   A1   A2   A3
  789.  
  790.     LONG GT_GetGadgetAttrsA(struct Gadget *, struct Window *,
  791.                             struct Requester *, struct TagItem *);
  792.  
  793.     numProcessed = GT_GetGadgetAttrs(gad, win, req, firsttag, ...)
  794.  
  795.     LONG GT_GetGadgetAttrs(struct Gadget *, struct Window *,
  796.                               struct Requester *, Tag, ...);
  797.  
  798.    FUNCTION
  799.     Retrieve the attributes of the specified gadget, according to the
  800.     attributes chosen in the tag list.  For each entry in the tag list,
  801.     ti_Tag identifies the attribute, and ti_Data is a pointer to
  802.     the long variable where you wish the result to be stored.
  803.  
  804.    INPUTS
  805.     gad - pointer to the gadget in question. May be NULL, in which case
  806.           this function returns 0
  807.     win - pointer to the window containing the gadget.
  808.     req - reserved for future use, should always be NULL
  809.     taglist - pointer to TagItem list.
  810.  
  811.    TAGS
  812.     BUTTON_KIND:
  813.     GA_Disabled (BOOL) - TRUE if this gadget is disabled,
  814.         FALSE otherwise. (V39)
  815.  
  816.     CHECKBOX_KIND:
  817.     GA_Disabled (BOOL) - TRUE if this gadget is disabled,
  818.         FALSE otherwise. (V39)
  819.     GTCB_Checked (BOOL) - TRUE if this gadget is currently checked,
  820.         FALSE otherwise. (V39)
  821.  
  822.     CYCLE_KIND:
  823.     GA_Disabled (BOOL) - TRUE if this gadget is disabled,
  824.         FALSE otherwise. (V39)
  825.     GTCY_Active (UWORD) - The ordinal number (counting from zero) of
  826.         the active choice of a cycle gadget. (V39)
  827.     GTCY_Labels (STRPTR *) - The NULL-terminated array of strings
  828.         that are the choices offered by the cycle gadget. (V39)
  829.  
  830.     INTEGER_KIND:
  831.     GA_Disabled (BOOL) - TRUE if this gadget is disabled,
  832.         FALSE otherwise. (V39)
  833.     GTIN_Number (ULONG) - The contents of the integer gadget. (V39)
  834.  
  835.     LISTVIEW_KIND:
  836.     GA_Disabled (BOOL) - TRUE if this gadget is disabled,
  837.         FALSE otherwise. (V39)
  838.     GTLV_Top (WORD) - Ordinal number of the top item visible
  839.         in the listview. (V39)
  840.     GTLV_Labels (struct List *) - The list of nodes whose ln_Name fields
  841.         are displayed in the listview. (V39)
  842.     GTLV_Selected (UWORD) - Ordinal number of currently selected
  843.         item. Returns ~0 if no item is selected. (V39)
  844.  
  845.     MX_KIND:
  846.     GA_Disabled (BOOL) - TRUE if this gadget is disabled,
  847.         FALSE otherwise. (V39)
  848.     GTMX_Active (UWORD) - The ordinal number (counting from zero) of
  849.         the active choice of an mx gadget. (V39)
  850.  
  851.     NUMBER_KIND:
  852.     GTNM_Number - The signed long integer that is displayed in
  853.         the read-only number. (V39)
  854.  
  855.     PALETTE_KIND:
  856.     GA_Disabled (BOOL) - TRUE if this gadget is disabled,
  857.         FALSE otherwise. (V39)
  858.     GTPA_Color (UBYTE) - The selected color of the palette. (V39)
  859.     GTPA_ColorOffset (UBYTE) - First color used in palette. (V39)
  860.     GTPA_ColorTable (UBYTE *) - Pointer to a table of pen numbers
  861.         indicating  which colors should be used and edited by the palette
  862.         gadget. May be NULL, which causes a 1-to-1 mapping of pen numbers.
  863.         (V39)
  864.  
  865.     SCROLLER_KIND:
  866.     GA_Disabled (BOOL) - TRUE if this gadget is disabled,
  867.         FALSE otherwise. (V39)
  868.     GTSC_Top (WORD) - Top visible in scroller. (V39)
  869.     GTSC_Total (WORD) - Total in scroller area. (V39)
  870.     GTSC_Visible (WORD) - Number visible in scroller. (V39)
  871.  
  872.     SLIDER_KIND:
  873.     GA_Disabled (BOOL) - TRUE if this gadget is disabled,
  874.         FALSE otherwise. (V39)
  875.     GTSL_Min (WORD) - Minimum level for slider. (V39)
  876.     GTSL_Max (WORD) - Maximum level for slider. (V39)
  877.     GTSL_Level (WORD) - Current level of slider. (V39)
  878.  
  879.     STRING_KIND:
  880.     GA_Disabled (BOOL) - TRUE if this gadget is disabled,
  881.         FALSE otherwise. (V39)
  882.     GTST_String (STRPTR) - Returns a pointer to the string gadget's
  883.         buffer. (V39)
  884.  
  885.     TEXT_KIND:
  886.     GTTX_Text - Pointer to the string to be displayed in the
  887.         read-only text-display gadget. (V39)
  888.  
  889.    RESULT
  890.     numProcessed - the number of attributes successfully filled in.
  891.  
  892.    EXAMPLE
  893.         long top = 0;
  894.         long selected = 0;
  895.         long result;
  896.         result = GT_GetGadgetAttrs( listview_gad, win, NULL,
  897.             GTLV_Top, &top,
  898.             GTLV_Selected, &selected,
  899.             TAG_DONE );
  900.         if ( result != 2 )
  901.         {
  902.             printf( "Something's wrong!" );
  903.         }
  904.  
  905.    WARNING
  906.     The pointers you provide within the tag list to store the return
  907.     values MUST POINT TO LONGWORDS. That is, even if the type of a
  908.     return value is defined as (UWORD *), you must pass a pointer to
  909.     a longword of memory.
  910.  
  911.    SEE ALSO
  912.     GT_SetGadgetAttrs()
  913.  
  914. gadtools.library/GT_GetIMsg                       gadtools.library/GT_GetIMsg
  915.  
  916.    NAME
  917.     GT_GetIMsg -- get an IntuiMessage, with GadTools processing. (V36)
  918.  
  919.    SYNOPSIS
  920.     imsg = GT_GetIMsg(intuiport)
  921.     D0                A0
  922.  
  923.     struct IntuiMessage *GT_GetIMsg(struct MsgPort *);
  924.  
  925.    FUNCTION
  926.     Use GT_GetIMsg() in place of the usual exec.library/GetMsg() when
  927.     reading IntuiMessages from your window's UserPort.  If needed,
  928.     the GadTools dispatcher will be invoked, and suitable processing
  929.     will be done for gadget actions.  This function returns a pointer
  930.     to a modified IntuiMessage (which is a copy of the original,
  931.     possibly with some supplementary information from GadTools).
  932.     If there are no messages (or if the only messages are meaningful
  933.     only to GadTools, NULL will be returned.
  934.  
  935.    INPUTS
  936.     intuiport - the Window->UserPort of a window that is using the
  937.                 Gadget Toolkit.
  938.  
  939.    RESULT
  940.     imsg - pointer to modified IntuiMessage, or NULL if there are
  941.            no applicable messages.
  942.  
  943.    NOTES
  944.     Be sure to use GT_ReplyIMsg() and not exec.library/ReplyMsg() on
  945.     messages obtained with GT_GetIMsg().
  946.     If you intend to do more with the resulting message than read
  947.     its fields, act on it, and reply it, you may find GT_FilterIMsg()
  948.     more appropriate.
  949.  
  950.     Starting with V39, this function actually returns a pointer to an
  951.     ExtIntuiMessage structure, but the prototype was not changed for
  952.     source code compatibility with older software.
  953.  
  954.    SEE ALSO
  955.     GT_ReplyIMsg(), GT_FilterIMsg()
  956.  
  957. gadtools.library/GT_PostFilterIMsg         gadtools.library/GT_PostFilterIMsg
  958.  
  959.    NAME
  960.     GT_PostFilterIMsg -- return the unfiltered message after
  961.                          GT_FilterIMsg() was called, and clean up. (V36)
  962.  
  963.    SYNOPSIS
  964.     imsg = GT_PostFilterIMsg(modimsg)
  965.     D0                       A1
  966.  
  967.     struct IntuiMessage *GT_PostFilterIMsg(struct IntuiMessage *);
  968.  
  969.    FUNCTION
  970.     NOTE WELL:  Extremely few programs will actually need this function.
  971.     You almost certainly should be using GT_GetIMsg() and GT_ReplyIMsg()
  972.     only, and not GT_FilterIMsg() and GT_PostFilterIMsg().
  973.  
  974.     Performs any clean-up necessitated by a previous call to
  975.     GT_FilterIMsg().  The original IntuiMessage is now yours to handle.
  976.     Do not interpret the fields of the original IntuiMessage, but
  977.     rather use only the one you got from GT_FilterIMsg().  You
  978.     may only do message related things at this point, such as queueing
  979.     it up or replying it.  Since you got the message with
  980.     exec.library/GetMsg(), your responsibilities do include replying
  981.     it with exec.library/ReplyMsg(). This function may be safely
  982.     called with a NULL parameter.
  983.  
  984.    INPUTS
  985.     modimsg - a modified IntuiMessage obtained with GT_FilterIMsg(),
  986.               or NULL in which case this function does nothing and
  987.               returns NULL
  988.  
  989.    RESULT
  990.     imsg - a pointer to the original IntuiMessage, if GT_FilterIMsg()
  991.            returned non-NULL.
  992.  
  993.    NOTES
  994.     Be sure to use exec.library/ReplyMsg() on the original IntuiMessage
  995.     you obtained with GetMsg(), (which is the what you passed to
  996.     GT_FilterIMsg()), and not on the parameter of this function.
  997.  
  998.     Starting with V39, this function actually expects and returns
  999.     pointers to ExtIntuiMessage structures, but the prototype was not
  1000.     changed for source code compatibility with older software.
  1001.  
  1002.    SEE ALSO
  1003.     GT_FilterIMsg()
  1004.  
  1005. gadtools.library/GT_RefreshWindow           gadtools.library/GT_RefreshWindow
  1006.  
  1007.    NAME
  1008.     GT_RefreshWindow -- refresh all GadTools gadgets in a window. (V36)
  1009.  
  1010.    SYNOPSIS
  1011.     GT_RefreshWindow(win, req)
  1012.                      A0   A1
  1013.  
  1014.     VOID GT_RefreshWindow(struct Window *, struct Requester *);
  1015.  
  1016.    FUNCTION
  1017.     Perform the initial refresh of all the GadTools gadgets you have
  1018.     created.  After you have opened your window, you must call this
  1019.     function.  Or, if you have opened your window without gadgets,
  1020.     you add the gadgets with intuition.library/AddGList(),
  1021.     refresh them using intuition.library/RefreshGList(), then call
  1022.     this function.
  1023.     You should not need this function at other times.
  1024.  
  1025.    INPUTS
  1026.     win - pointer to the Window containing GadTools gadgets.
  1027.     req - reserved for future use, should always be NULL
  1028.  
  1029.    SEE ALSO
  1030.     GT_BeginRefresh()
  1031.  
  1032. gadtools.library/GT_ReplyIMsg                   gadtools.library/GT_ReplyIMsg
  1033.  
  1034.    NAME
  1035.     GT_ReplyIMsg -- reply a message obtained with GT_GetIMsg(). (V36)
  1036.  
  1037.    SYNOPSIS
  1038.     GT_ReplyIMsg(imsg)
  1039.                  A1
  1040.  
  1041.     VOID GT_ReplyIMsg(struct IntuiMessage *);
  1042.  
  1043.    FUNCTION
  1044.     Reply a modified IntuiMessage obtained with GT_GetIMsg().
  1045.     If you use GT_GetIMsg(), use this function where you would normally
  1046.     have used exec.library/ReplyMsg().
  1047.     You may safely call this routine with a NULL pointer (nothing
  1048.     will be done).
  1049.  
  1050.    INPUTS
  1051.     imsg - a modified IntuiMessage obtained with GT_GetIMsg(), or NULL
  1052.            in which case this function does nothing
  1053.  
  1054.    NOTES
  1055.     When using GadTools, you MUST explicitly GT_ReplyIMsg()
  1056.     all messages you receive.  You cannot depend on CloseWindow()
  1057.     to handle messages you have not replied.
  1058.  
  1059.     Starting with V39, this function actually expects a pointer to an
  1060.     ExtIntuiMessage structure, but the prototype was not changed for
  1061.     source code compatibility with older software.
  1062.  
  1063.    SEE ALSO
  1064.     GT_GetIMsg()
  1065.  
  1066. gadtools.library/GT_SetGadgetAttrsA       gadtools.library/GT_SetGadgetAttrsA
  1067.  
  1068.    NAME
  1069.     GT_SetGadgetAttrsA -- change the attributes of a GadTools gadget. (V36)
  1070.     GT_SetGadgetAttrs -- varargs stub for GT_SetGadgetAttrsA(). (V36)
  1071.  
  1072.    SYNOPSIS
  1073.     GT_SetGadgetAttrsA(gad, win, req, tagList)
  1074.                        A0   A1   A2   A3
  1075.  
  1076.     VOID GT_SetGadgetAttrsA(struct Gadget *, struct Window *,
  1077.                             struct Requester *, struct TagItem *);
  1078.  
  1079.     GT_SetGadgetAttrs(gad, win, req, firsttag, ...)
  1080.  
  1081.     VOID GT_SetGadgetAttrs(struct Gadget *, struct Window *,
  1082.                            struct Requester *, Tag, ...);
  1083.  
  1084.    FUNCTION
  1085.     Change the attributes of the specified gadget, according to the
  1086.     attributes chosen in the tag list. If an attribute is not provided
  1087.     in the tag list, its value remains unchanged.
  1088.  
  1089.    INPUTS
  1090.     gad - pointer to the gadget in question. Starting with V39, this
  1091.           value may be NULL in which case this function does nothing
  1092.     win - pointer to the window containing the gadget. Starting with V39,
  1093.           this value may be NULL in which case the internal attributes of
  1094.           the gadgets are altered but no rendering occurs.
  1095.     req - reserved for future use, should always be NULL
  1096.     tagList - pointer to an array of tags providing optional extra
  1097.           parameters, or NULL.
  1098.  
  1099.    TAGS
  1100.     BUTTON_KIND:
  1101.     GA_Disabled (BOOL) - Set to TRUE to disable gadget, FALSE otherwise.
  1102.         (V36)
  1103.  
  1104.     CHECKBOX_KIND:
  1105.     GA_Disabled (BOOL) - Set to TRUE to disable gadget, FALSE otherwise.
  1106.         (V36)
  1107.     GTCB_Checked (BOOL) - State of checkbox. (V36)
  1108.  
  1109.     CYCLE_KIND:
  1110.     GA_Disabled (BOOL) - Set to TRUE to disable gadget, FALSE otherwise
  1111.         (V37)
  1112.     GTCY_Active (UWORD) - The ordinal number (counting from zero) of
  1113.         the active choice of a cycle gadget. (V36)
  1114.     GTCY_Labels (STRPTR *) - Pointer to NULL-terminated array of strings
  1115.         that are the choices offered by the cycle gadget. (V37)
  1116.  
  1117.     INTEGER_KIND:
  1118.     GA_Disabled (BOOL) - Set to TRUE to disable gadget, FALSE otherwise
  1119.         (V36)
  1120.     GTIN_Number (ULONG) - New value of the integer gadget (V36)
  1121.  
  1122.     LISTVIEW_KIND:
  1123.     GA_Disabled (BOOL) - Set to TRUE to disable gadget, FALSE otherwise
  1124.         (V39)
  1125.     GTLV_Top (WORD) - Top item visible in the listview.  This value
  1126.         will be made reasonable if out-of-range. (V36)
  1127.     GTLV_MakeVisible (WORD) - Number of an item that should be forced
  1128.         within the visible area of the listview by doing minimal scrolling.
  1129.         This tag overrides GTLV_Top. (V39)
  1130.     GTLV_Labels (struct List *) - List of nodes whose ln_Name fields
  1131.         are to be displayed in the listview.  Use a value of ~0 to
  1132.         "detach" your List from the display.  You must detach your list
  1133.         before modifying the List structure, since GadTools reserves
  1134.         the right to traverse it on another task's schedule.  When you
  1135.         are done, attach the list by using the tag pair
  1136.         {GTLV_Labels, list}. (V36)
  1137.     GTLV_Selected (UWORD) - Ordinal number of currently selected
  1138.         item. Starting with V39, you can provide ~0 to cause the currently
  1139.         selected item to be deselected. (V36)
  1140.  
  1141.     MX_KIND:
  1142.     GA_Disabled (BOOL) - Set to TRUE to disable gadget, FALSE otherwise
  1143.         (V39)
  1144.     GTMX_Active (UWORD) - The ordinal number (counting from zero) of
  1145.         the active choice of an mx gadget. (V36)
  1146.  
  1147.     NUMBER_KIND:
  1148.     GTNM_Number (LONG) - A signed long integer to be displayed in
  1149.         the number gadget. (V36)
  1150.     GTNM_FrontPen (UBYTE) - The pen to use when rendering the number. (V39)
  1151.     GTNM_BackPen (UBYTE) - The pen to use when rendering the background
  1152.         of the number. (V39)
  1153.     GTNM_Justification (UBYTE) - Determines how the number is rendered
  1154.         within the gadget box. GTJ_LEFT will make the rendering be
  1155.         flush with the left side of the gadget, GTJ_RIGHT will make it
  1156.         flush with the right side, and GTJ_CENTER will center the number
  1157.         within the gadget box. (V39)
  1158.     GTNM_Format (STRPTR) - C-Style formatting string to apply on the number
  1159.         before display. Be sure to use the 'l' (long) modifier. This string
  1160.         is processed using exec.library/RawDoFmt(), so refer to that
  1161.         function for details. (V39)
  1162.  
  1163.     PALETTE_KIND:
  1164.     GA_Disabled (BOOL) - Set to TRUE to disable gadget, FALSE otherwise
  1165.         (V36)
  1166.     GTPA_Color (UBYTE) - Selected color of the palette. This
  1167.         number is a pen number, and not the ordinal color number within
  1168.         the palette gadget itself. (V36)
  1169.     GTPA_ColorOffset (UBYTE) - First color to use in palette (V39)
  1170.     GTPA_ColorTable (UBYTE *) - Pointer to a table of pen numbers
  1171.         indicating  which colors should be used and edited by the palette
  1172.         gadget. This array must contain as many entries as there are
  1173.         colors displayed in the palette gadget. The array provided with
  1174.         this tag must remain valid for the life of the gadget or until a
  1175.         new table is provided. A NULL table pointer causes a 1-to-1
  1176.         mapping of pen numbers. (V39)
  1177.  
  1178.     SCROLLER_KIND:
  1179.     GA_Disabled (BOOL) - Set to TRUE to disable gadget, FALSE otherwise
  1180.         (V36)
  1181.     GTSC_Top (WORD) - Top visible in scroller. (V36)
  1182.     GTSC_Total (WORD) - Total in scroller area. (V36)
  1183.     GTSC_Visible (WORD) - Number visible in scroller. (V36)
  1184.  
  1185.     SLIDER_KIND:
  1186.     GA_Disabled (BOOL) - Set to TRUE to disable gadget, FALSE otherwise
  1187.         (V36)
  1188.     GTSL_Min (WORD) - Minimum level for slider. (V36)
  1189.     GTSL_Max (WORD) - Maximum level for slider. (V36)
  1190.     GTSL_Level (WORD) - Current level of slider. (V36)
  1191.     GTSL_LevelFormat (STRPTR) - C-Style formatting string for slider
  1192.         level.  Be sure to use the 'l' (long) modifier.  This string
  1193.         is processed using exec.library/RawDoFmt(), so refer to that
  1194.         function for details. (V39)
  1195.     GTSL_DispFunc ( LONG (*function)(struct Gadget *, WORD) ) - Function
  1196.         to calculate level to be displayed.  A number-of-colors slider
  1197.         might want to set the slider up to think depth, and have a
  1198.         (1 << n) function here.  Your function must
  1199.         take a pointer to gadget as the first parameter, the level
  1200.         (a WORD) as the second, and return the result as a LONG. (V39)
  1201.     GTSL_Justification (UBYTE) - Determines how the level display is to
  1202.         be justified within its alotted space. Choose one of GTJ_LEFT,
  1203.         GTJ_RIGHT, or GTJ_CENTER. (V39)
  1204.  
  1205.     STRING_KIND:
  1206.     GA_Disabled (BOOL) - Set to TRUE to disable gadget, FALSE otherwise
  1207.         (V36)
  1208.     GTST_String (STRPTR) - New contents of the string gadget,
  1209.         or NULL to reset the gadget to the empty state. (V36)
  1210.  
  1211.     TEXT_KIND:
  1212.     GTTX_Text - New NULL terminated string to be displayed in the text
  1213.         gadget. NULL means to clear the gadget. (V36)
  1214.     GTTX_FrontPen (UBYTE) - The pen to use when rendering the text. (V39)
  1215.     GTTX_BackPen (UBYTE) - The pen to use when rendering the background
  1216.         of the text. (V39)
  1217.     GTTX_Justification (UBYTE) - Determines how the text is rendered
  1218.         within the gadget box. GTJ_LEFT will make the rendering be
  1219.         flush with the left side of the gadget, GTJ_RIGHT will make it
  1220.         flush with the right side, and GTJ_CENTER will center the text
  1221.         within the gadget box. (V39)
  1222.  
  1223.    NOTES
  1224.     This function may not be called inside of a GT_BeginRefresh() /
  1225.     GT_EndRefresh() session.  (As always, restrict yourself to simple
  1226.     rendering functions).
  1227.  
  1228.    SEE ALSO
  1229.     GT_GetGadgetAttrs()
  1230.  
  1231. gadtools.library/LayoutMenuItemsA           gadtools.library/LayoutMenuItemsA
  1232.  
  1233.    NAME
  1234.     LayoutMenuItemsA -- position all the menu items. (V36)
  1235.     LayoutMenuItems -- varargs stub for LayoutMenuItemsA(). (V36)
  1236.  
  1237.    SYNOPSIS
  1238.     success = LayoutMenuItemsA(menuitem, vi, tagList)
  1239.     D0                         A0        A1  A2
  1240.  
  1241.     BOOL LayoutMenuItemsA(struct MenuItem *, APTR, struct TagItem *);
  1242.  
  1243.     success = LayoutMenuItems(menuitem, vi, firsttag, ...)
  1244.  
  1245.     BOOL LayoutMenuItemsA(struct MenuItem *, APTR, Tag, ...);
  1246.  
  1247.    FUNCTION
  1248.     Lays out all the menu items and sub-items according to
  1249.     the supplied visual information and tag parameters.  You would use this
  1250.     if you used CreateMenusA() to make a single menu-pane (with sub-items,
  1251.     if any), instead of a whole menu strip.
  1252.     This routine attempts to columnize and/or shift the MenuItems in
  1253.     the event that a menu would be too tall or too wide.
  1254.  
  1255.    INPUTS
  1256.     menuitem - pointer to first MenuItem in a linked list of
  1257.                items.
  1258.     vi - pointer returned by GetVisualInfoA().
  1259.     tagList - pointer to an array of tags providing optional extra
  1260.           parameters, or NULL.
  1261.  
  1262.    TAGS
  1263.     GTMN_Menu (struct Menu *) - Pointer to the Menu structure whose
  1264.         FirstItem is the MenuItem supplied above.  If the menu items are
  1265.         such that they need to be columnized or shifted, the Menu
  1266.         structure is needed to perform the complete calculation.
  1267.         It is suggested you always provide this information. (V36)
  1268.  
  1269.     For the following tags, please see the description under
  1270.     LayoutMenusA().  Their behavior is identical when used in
  1271.     LayoutMenuItemsA().
  1272.  
  1273.         GTMN_TextAttr
  1274.         GTMN_NewLookMenus
  1275.         GTMN_Checkmark
  1276.         GTMN_AmigaKey
  1277.         GTMN_FrontPen
  1278.  
  1279.    RESULT
  1280.     success - TRUE if successful, FALSE otherwise (signifies that
  1281.               the TextAttr wasn't openable).
  1282.  
  1283.    BUGS
  1284.     If a menu ends up being wider than the whole screen, it will
  1285.     run off the right-hand side.
  1286.  
  1287.    SEE ALSO
  1288.     CreateMenusA(), GetVisualInfoA()
  1289.  
  1290. gadtools.library/LayoutMenusA                   gadtools.library/LayoutMenusA
  1291.  
  1292.    NAME
  1293.     LayoutMenusA -- position all the menus and menu items. (V36)
  1294.     LayoutMenus -- varargs stub for LayoutMenusA(). (V36)
  1295.  
  1296.    SYNOPSIS
  1297.     success = LayoutMenusA(menu, vi, tagList)
  1298.     D0                     A0    A1  A2
  1299.  
  1300.     BOOL LayoutMenusA(struct Menu *, APTR, struct TagItem *);
  1301.  
  1302.     success = LayoutMenus(menu, vi, firsttag, ...)
  1303.  
  1304.     BOOL LayoutMenus(struct Menu *, APTR, Tag, ...);
  1305.  
  1306.    FUNCTION
  1307.     Lays out all the menus, menu items and sub-items in the supplied
  1308.     menu according to the supplied visual information and tag parameters.
  1309.     This routine attempts to columnize and/or shift the MenuItems in
  1310.     the event that a menu would be too tall or too wide.
  1311.  
  1312.    INPUTS
  1313.     menu - pointer to menu obtained from CreateMenusA().
  1314.     vi - pointer returned by GetVisualInfoA().
  1315.     tagList - pointer to an array of tags providing optional extra
  1316.           parameters, or NULL.
  1317.  
  1318.    TAGS
  1319.     GTMN_TextAttr (struct TextAttr *) - Text Attribute to use for
  1320.         menu-items and sub-items.  If not supplied, the screen's
  1321.         font will be used.  This font must be openable via OpenFont()
  1322.         when this function is called. (V36)
  1323.     GTMN_NewLookMenus (BOOL) - If you ask for WA_NewLookMenus for your
  1324.         window, you should ask for this tag as well.  This informs GadTools
  1325.         to use the appropriate checkmark, Amiga-key, and colors. (V39)
  1326.     GTMN_Checkmark (struct Image *) - If you are using a custom image for a
  1327.         checkmark (WA_Checkmark), also pass it to GadTools, so it can lay
  1328.         the menus out accordingly. (V39)
  1329.     GTMN_AmigaKey (struct Image *) - If you are using a custom image for
  1330.         the Amiga-key in menus (WA_AmigaKey), also pass it to GadTools, so
  1331.         it can lay the menus out accordingly. (V39)
  1332.     GTMN_FrontPen (ULONG) - This tag has existed for CreateMenus(), but now
  1333.         LayoutMenusA() has it too.  If a legitimate pen number is supplied,
  1334.         it is used for coloring the menu items (in preference to
  1335.         anything passed to CreateMenus()).  If GTMN_NewLookMenus
  1336.         has been specified, this tag defaults to using the
  1337.         screen's BARDETAILPEN, else it defaults to "do nothing".
  1338.         For visual consistency, we recommend you omit this tag in all
  1339.         functions, and let the defaults be used. (V39)
  1340.  
  1341.    RESULT
  1342.     success - TRUE if successful, FALSE otherwise (signifies that
  1343.               the TextAttr wasn't openable).
  1344.  
  1345.    NOTES
  1346.     When using this function, there is no need to also call
  1347.     LayoutMenuItemsA().
  1348.  
  1349.    BUGS
  1350.     If a menu ends up being wider than the whole screen, it will
  1351.     run off the right-hand side.
  1352.  
  1353.    SEE ALSO
  1354.     CreateMenusA(), GetVisualInfoA()
  1355.  
  1356.