@database "gadtools"
@master "ADCD_v1.2:Inc&AD2.1/Includes/doc/gadtools.doc"

@Node Main "gadtools.doc"
@TOC 2.1Includes_Autodocs/Autodocs

@{" CreateContext() " Link "CreateContext()"}    @{" FreeVisualInfo() " Link "FreeVisualInfo()"}     @{" GT_PostFilterIMsg() " Link "GT_PostFilterIMsg()"}
@{" CreateGadgetA() " Link "CreateGadgetA()"}    @{" GetVisualInfoA() " Link "GetVisualInfoA()"}     @{" GT_RefreshWindow() " Link "GT_RefreshWindow()"}
@{" CreateMenusA() " Link "CreateMenusA()"}     @{" GT_BeginRefresh() " Link "GT_BeginRefresh()"}    @{" GT_ReplyIMsg() " Link "GT_ReplyIMsg()"}
@{" DrawBevelBoxA() " Link "DrawBevelBoxA()"}    @{" GT_EndRefresh() " Link "GT_EndRefresh()"}      @{" GT_SetGadgetAttrsA() " Link "GT_SetGadgetAttrsA()"}
@{" FreeGadgets() " Link "FreeGadgets()"}      @{" GT_FilterIMsg() " Link "GT_FilterIMsg()"}      @{" LayoutMenuItemsA() " Link "LayoutMenuItemsA()"}
@{" FreeMenus() " Link "FreeMenus()"}        @{" GT_GetIMsg() " Link "GT_GetIMsg()"}         @{" LayoutMenusA() " Link "LayoutMenusA()"}

@EndNode

@Node "CreateContext()" "gadtools.library/CreateContext"

NAME
    CreateContext -- Create a place for GadTools context data. (V36)

SYNOPSIS
    gad = CreateContext(glistpointer);
    D0                  A0

    struct @{"Gadget" Link "ADCD_v1.2:Inc&AD2.1/Includes/intuition/intuition.h/Main" 213} *CreateContext(struct @{"Gadget" Link "ADCD_v1.2:Inc&AD2.1/Includes/intuition/intuition.h/Main" 213} **);

FUNCTION
    Creates a place for GadTools to store any context data it might
    need for your window.  In reality, an unselectable invisible
    gadget is created, with room for the context data.
    This function also establishes the linkage from a glist type
    pointer to the individual gadget pointers.  Call this function
    before any of the other gadget creation calls.

INPUTS
    glistptr - Address of a pointer to a @{"Gadget" Link "ADCD_v1.2:Inc&AD2.1/Includes/intuition/intuition.h/Main" 213}, which was previously
        set to NULL.  When all the gadget creation is done, you may
        use that pointer as your NewWindow.FirstGadget, or
        in @{"intuition.library/AddGList()" Link "ADCD_v1.2:Inc&AD2.1/Autodocs/intuition/AddGList()"}, @{"intuition.library/RefreshGList()" Link "ADCD_v1.2:Inc&AD2.1/Autodocs/intuition/RefreshGList()"},
        @{"FreeGadgets()" Link "FreeGadgets()"}, etc.

RESULT
    gad - Pointer to context gadget, or NULL if failure.

EXAMPLE
    struct @{"Gadget" Link "ADCD_v1.2:Inc&AD2.1/Includes/intuition/intuition.h/Main" 213} *gad;
    struct @{"Gadget" Link "ADCD_v1.2:Inc&AD2.1/Includes/intuition/intuition.h/Main" 213} *glist = NULL;
    gad = CreateContext(&glist);
    /*  Other creation calls go here */
    if (gad)
    {
        myNewWindow.FirstGadget = glist;
        if ( myWindow = OpenWindow(&myNewWindow) )
        {
            GT_RefreshWindow(win);
            /* other stuff */
            CloseWindow(myWindow);
        }
    }
    FreeGadgets(glist);

NOTES

BUGS

SEE ALSO

@EndNode

@Node "CreateGadgetA()" "gadtools.library/CreateGadgetA"

NAME
    CreateGadgetA -- Allocate and initialize a gadtools gadget. (V36)
    CreateGadget -- Varargs stub for CreateGadgetA(). (V36)

SYNOPSIS
    gad = CreateGadgetA(kind, previous, newgad, taglist)
    D0                  D0    A0        A1      A2

    struct @{"Gadget" Link "ADCD_v1.2:Inc&AD2.1/Includes/intuition/intuition.h/Main" 213} *CreateGadgetA(ULONG, struct @{"Gadget" Link "ADCD_v1.2:Inc&AD2.1/Includes/intuition/intuition.h/Main" 213} *,
        struct @{"NewGadget" Link "ADCD_v1.2:Inc&AD2.1/Includes/libraries/gadtools.h/Main" 91} *, struct @{"TagItem" Link "ADCD_v1.2:Inc&AD2.1/Includes/utility/tagitem.h/Main" 29} *);

    gad = CreateGadget(kind, previous, newgad, firsttag, ...)

    struct @{"Gadget" Link "ADCD_v1.2:Inc&AD2.1/Includes/intuition/intuition.h/Main" 213} *CreateGadget(ULONG, struct @{"Gadget" Link "ADCD_v1.2:Inc&AD2.1/Includes/intuition/intuition.h/Main" 213} *,
        struct @{"NewGadget" Link "ADCD_v1.2:Inc&AD2.1/Includes/libraries/gadtools.h/Main" 91} *, Tag, ...);

FUNCTION
    CreateGadgetA() allocates and initializes a new gadget of the
    specified kind, and attaches it to the previous gadget.  The
    gadget is created based on the supplied kind, @{"NewGadget" Link "ADCD_v1.2:Inc&AD2.1/Includes/libraries/gadtools.h/Main" 91} structure,
    and tags.

INPUTS
    kind - to indicate what kind of gadget is to be created.
    previous - pointer to the previous gadget that this new gadget
        is to be attached to.
    newgad - a filled in @{"NewGadget" Link "ADCD_v1.2:Inc&AD2.1/Includes/libraries/gadtools.h/Main" 91} structure describing the desired
        gadget's size, position, label, etc.
    taglist - pointer to a @{"TagItem" Link "ADCD_v1.2:Inc&AD2.1/Includes/utility/tagitem.h/Main" 29} list.

TAGS
    All kinds:
    GT_Underscore (GadTools V37 and higher only).
        Indicates the symbol that precedes the character in the gadget
        label to be underscored.  This would be to indicate keyboard
        equivalents for gadgets (note that GadTools does not process
        the keys - it just displays the underscore).
        Example: To underscore the "M" in "Mode"...
            ng.ng_GadgetText = "_Mode:";
            gad = CreateGadget(..._KIND, &ng, prev,
                    GT_Underscore, '_',
                    ...
                    );

    BUTTON_KIND (action buttons):
    GA_Disabled (BOOL) - Set to TRUE to disable gadget, FALSE otherwise
        (defaults to FALSE).

    CHECKBOX_KIND (on/off items):
    GTCB_Checked (BOOL) - Initial state of checkbox, defaults to FALSE.
    GA_Disabled (BOOL) - Set to TRUE to disable gadget, FALSE otherwise
        (defaults to FALSE).

    CYCLE_KIND (multiple state selections):
    GTCY_Labels (STRPTR *) - Pointer to NULL-terminated array of strings
        that are the choices offered by the cycle gadget (required).
    GTCY_Active (UWORD) - The ordinal number (counting from zero) of
        the initially active choice of a cycle gadget (defaults to zero).
    GA_Disabled (BOOL) - (GadTools V37 and higher only)
        Set to TRUE to disable gadget, FALSE otherwise
        (defaults to FALSE).

    INTEGER_KIND (numeric entry):
    GTIN_Number (ULONG) - The initial contents of the integer gadget
        (default zero).
    GTIN_MaxChars (UWORD) - The maximum number of digits that the
        integer gadget is to hold (defaults to 10).
    GA_Disabled (BOOL) - Set to TRUE to disable gadget, FALSE otherwise
        (defaults to FALSE).
    STRINGA_ExitHelp (BOOL) - (New for V37) Set to TRUE to have the
        help-key cause an exit from the integer gadget.  You will
        then receive a GADGETUP with code = 0x5F (rawkey for help).
    GA_TabCycle (BOOL) - (New for V37) Set to TRUE so that pressing
        <TAB> or <Shift-TAB> will activate the next or previous
        such gadget. (defaults to TRUE, unlike regular Intuition string
        gadgets, which default to FALSE).

    LISTVIEW_KIND (scrolling list):
    GTLV_Top (UWORD) - Top item visible in the listview (defaults to zero).
    GTLV_Labels (struct @{"List" Link "ADCD_v1.2:Inc&AD2.1/Includes/exec/lists.h/Main" 19} *) - @{"List" Link "ADCD_v1.2:Inc&AD2.1/Includes/exec/lists.h/Main" 19} of labels whose ln_Name fields
        are to be displayed in the listview.
    GTLV_ReadOnly (BOOL) - If TRUE, then listview is read-only.
    GTLV_ScrollWidth (UWORD) - Width of scroll bar for listview.
        Must be greater than zero (defaults to 16).
    GTLV_ShowSelected (struct @{"Gadget" Link "ADCD_v1.2:Inc&AD2.1/Includes/intuition/intuition.h/Main" 213} *) - NULL to have the currently
        selected item displayed beneath the listview, or pointer to
        an already-created GadTools STRING_KIND gadget to have an
        editable display of the currently selected item.
    GTLV_Selected (UWORD) - Ordinal number of currently selected
        item, or ~0 to have no current selection (defaults to ~0).
    LAYOUTA_Spacing - Extra space to place between lines of listview
        (defaults to zero).

    MX_KIND (mutually exclusive, radio buttons):
    GTMX_Labels (STRPTR *) - Pointer to a NULL-terminated array of
        strings which are to be the labels beside each choice in a
        set of mutually exclusive gadgets.
    GTMX_Active (UWORD) - The ordinal number (counting from zero) of
        the initially active choice of an mx gadget (Defaults to zero).
    GTMX_Spacing (UWORD) - The amount of space between each choice
        of a set of mutually exclusive gadgets.  This amount is added
        to the font height to produce the vertical shift between
        choices. (defaults to one).
    LAYOUTA_Spacing - FOR COMPATIBILITY ONLY.  Use GTMX_Spacing instead.
        The number of extra pixels to insert between
        each choice of a mutually exclusive gadget.  This is added
        to the present gadget image height (9) to produce the
        true spacing between choices.  (defaults to
        FontHeight-8, which is zero for 8-point font users).

    NUMBER_KIND (read-only numeric):
    GTNM_Number - A signed long integer to be displayed as a read-only
         number (default 0).
    GTNM_Border (BOOL) - If TRUE, this flag asks for a recessed
        border to be placed around the gadget.

    PALETTE_KIND (color selection):
    GTPA_Depth (UWORD) - Number of bitplanes in the palette
        (defaults to 1).
    GTPA_Color (UBYTE) - Initially selected color of the palette
        (defaults to 1).
    GTPA_ColorOffset (UBYTE) - First color to use in palette
        (defaults to zero).
    GTPA_IndicatorWidth (UWORD) - The desired width of the current-color
        indicator, if you want one to the left of the palette.
    GTPA_IndicatorHeight (UWORD) - The desired height of the current-color
        indicator, if you want one above the palette.
    GA_Disabled (BOOL) - Set to TRUE to disable gadget, FALSE otherwise
        (defaults to FALSE).

    SCROLLER_KIND (for scrolling through areas or lists):
    GTSC_Top (WORD) - Top visible in area scroller represents
        (defaults to zero).
    GTSC_Total (WORD) - Total in area scroller represents
        (defaults to zero).
    GTSC_Visible (WORD) - Number visible in scroller (defaults to 2).
    GTSC_Arrows (UWORD) - Asks for arrows to be attached to the scroller.
        The value supplied will be taken as the width of each arrow button
        for a horizontal scroller, or the height of each button for a
        vertical scroller (the other dimension will match the whole
        scroller).
    PGA_Freedom - Whether scroller is horizontal or vertical.
        Choose LORIENT_VERT or LORIENT_HORIZ (defaults to horiz).
    GA_Immediate (BOOL) - Hear every IDCMP_GADGETDOWN event from scroller
        (defaults to FALSE).
    GA_RelVerify (BOOL) - Hear every IDCMP_GADGETUP event from scroller
        (defaults to FALSE).
    GA_Disabled (BOOL) - Set to TRUE to disable gadget, FALSE otherwise
        (defaults to FALSE).

    SLIDER_KIND (to indicate level or intensity):
    GTSL_Min (WORD) - Minimum level for slider (default 0).
    GTSL_Max (WORD) - Maximum level for slider (default 15).
    GTSL_Level (WORD) - Current level of slider (default 0).
    GTSL_MaxLevelLen (UWORD) - Max. length in characters of level string
        when rendered beside slider.
    GTSL_LevelFormat (STRPTR) - C-Style formatting string for slider
        level.  Be sure to use the 'l' (long) modifier.  This string
        is processed using @{"exec/RawDoFmt()" Link "ADCD_v1.2:Inc&AD2.1/Autodocs/exec/RawDoFmt()"}, so refer to that function
        for details.
    GTSL_LevelPlace - One of PLACETEXT_LEFT, PLACETEXT_RIGHT,
        PLACETEXT_ABOVE, or PLACETEXT_BELOW, indicating where the level
        indicator is to go relative to slider (default to PLACETEXT_LEFT).
    GTSL_DispFunc ( LONG (*function)(struct @{"Gadget" Link "ADCD_v1.2:Inc&AD2.1/Includes/intuition/intuition.h/Main" 213} *, WORD) ) - Function
        to calculate level to be displayed.  A number-of-colors slider
        might want to set the slider up to think depth, and have a
        (1 << n) function here.  Defaults to none.  Your function must
        take a pointer to gadget as the first parameter, the level
        (a WORD) as the second, and return the result as a LONG.
    GA_Immediate (BOOL) - If you want to hear each slider IDCMP_GADGETDOWN
        event.
    GA_RelVerify (BOOL) - If you want to hear each slider IDCMP_GADGETUP
        event.
    PGA_Freedom - Set to LORIENT_VERT or LORIENT_HORIZ to have a
        vertical or horizontal slider.
    GA_Disabled (BOOL) - Set to TRUE to disable gadget, FALSE otherwise
        (defaults to FALSE).

    STRING_KIND (text-entry):
    GTST_String (STRPTR) - The initial contents of the string gadget,
         or NULL (default) if string is to start empty.
    GTST_MaxChars (UWORD) - The maximum number of characters that the
        string gadget is to hold.
    GA_Disabled (BOOL) - Set to TRUE to disable gadget, FALSE otherwise
        (defaults to FALSE).
    STRINGA_ExitHelp (BOOL) - (New for V37) Set to TRUE to have the
        help-key cause an exit from the string gadget.  You will
        then receive a GADGETUP with code = 0x5F (rawkey for help).
    GA_TabCycle (BOOL) - (New for V37) Set to TRUE so that pressing
        <TAB> or <Shift-TAB> will activate the next or previous
        such gadget. (defaults to TRUE, unlike regular Intuition string
        gadgets, which default to FALSE).

    TEXT_KIND (read-only text):
    GTTX_Text - Pointer to a NULL terminated string to be displayed,
        as a read-only text-display gadget, or NULL. defaults to NULL.
    GTTX_CopyText (BOOL) -  This flag instructs the text-display gadget
        to copy the supplied text string, instead of using only
        pointer to the string.  This only works for the initial value
        of GTTX_Text set at CreateGadget() time.  If you subsequently
        change GTTX_Text, the new text will be referenced by pointer,
        not copied.  Do not use this tag with a NULL GTTX_Text.
    GTTX_Border (BOOL) - If TRUE, this flag asks for a recessed
        border to be placed around the gadget.

RESULT
    gad - pointer to the new gadget, or NULL if the allocation failed
        or if previous was NULL.

EXAMPLE

NOTES
    Note that the ng_VisualInfo and ng_TextAttr fields of the
    @{"NewGadget" Link "ADCD_v1.2:Inc&AD2.1/Includes/libraries/gadtools.h/Main" 91} structure must be set to valid VisualInfo and
    @{"TextAttr" Link "ADCD_v1.2:Inc&AD2.1/Includes/graphics/text.h/Main" 64} pointers, or this function will fail.

    Starting with V37, string and integer gadgets have the GFLG_TABCYCLE
    feature automatically.  If the user presses Tab or Shift-Tab while
    in a string or integer gadget, the next or previous one in
    sequence will be activated.  You will hear a GADGETUP with a code
    of 0x09.  Use {GA_TabCycle, FALSE} to supress this.

BUGS

SEE ALSO
    @{"FreeGadgets()" Link "FreeGadgets()"}, GT_SetGadgetAttrs(), GetVisualInfo().

@EndNode

@Node "CreateMenusA()" "gadtools.library/CreateMenusA"

NAME
    CreateMenusA -- Allocate and fill out a menu structure. (V36)
    CreateMenus -- Varargs stub for CreateMenus(). (V36)

SYNOPSIS
    menu = CreateMenusA(newmenu, taglist)
    D0                  A0       A1

    struct @{"Menu" Link "ADCD_v1.2:Inc&AD2.1/Includes/intuition/intuition.h/Main" 59} *CreateMenusA(struct @{"NewMenu" Link "ADCD_v1.2:Inc&AD2.1/Includes/libraries/gadtools.h/Main" 120} *, struct @{"TagItem" Link "ADCD_v1.2:Inc&AD2.1/Includes/utility/tagitem.h/Main" 29} *);

    menu = CreateMenus(newmenu, firsttag, ...)

    struct @{"Menu" Link "ADCD_v1.2:Inc&AD2.1/Includes/intuition/intuition.h/Main" 59} *CreateMenus(struct @{"NewMenu" Link "ADCD_v1.2:Inc&AD2.1/Includes/libraries/gadtools.h/Main" 120} *, Tag, ...);

FUNCTION
    CreateMenusA() allocates and initializes a complete menu
    structure based on the supplied array of @{"NewMenu" Link "ADCD_v1.2:Inc&AD2.1/Includes/libraries/gadtools.h/Main" 120} structures.
    Optionally, CreateMenusA() can allocate and initialize a complete
    set of menu items and sub-items for a single menu title.  This
    is dictated by the contents of the array of NewMenus.

INPUTS
    newmenu - Pointer to an array of initialized struct NewMenus.
    taglist - Pointer to a @{"TagItem" Link "ADCD_v1.2:Inc&AD2.1/Includes/utility/tagitem.h/Main" 29} list.

TAGS
    GTMN_FrontPen (UBYTE) - Pen number to be used for menu text.
        (defaults to zero).
    GTMN_FullMenu (BOOL) - (GadTools V37 and higher only)
        Requires that the @{"NewMenu" Link "ADCD_v1.2:Inc&AD2.1/Includes/libraries/gadtools.h/Main" 120} specification describes a complete
        menu strip, not a fragment.  If a fragment is found,
        CreateMenusA() will fail with a secondary error of
        GTMENU_INVALID.  (defaults to FALSE).
    GTMN_SecondaryError (ULONG *) - (GadTools V37 and higher only)
        Supply a pointer to a NULL-initialized ULONG to receive a
        descriptive error code.  Possible values:
        GTMENU_INVALID - @{"NewMenu" Link "ADCD_v1.2:Inc&AD2.1/Includes/libraries/gadtools.h/Main" 120} structure describes an illegal
            menu.  (CreateMenusA() will fail with a NULL result).
        GTMENU_TRIMMED - @{"NewMenu" Link "ADCD_v1.2:Inc&AD2.1/Includes/libraries/gadtools.h/Main" 120} structure has too many menus, items,
            or subitems (CreateMenusA() will succeed, returning a
            trimmed-down menu structure).
        GTMENU_NOMEM - CreateMenusA() ran out of memory.

RESULT
    menu - Pointer to the resulting initialized menu structure (or
        the resulting FirstItem), with all the links for menu items
        and subitems in place.
        The result will be NULL if CreateMenusA() could not allocate
        memory for the menus, or if the @{"NewMenu" Link "ADCD_v1.2:Inc&AD2.1/Includes/libraries/gadtools.h/Main" 120} array had an
        illegal arrangement (eg. NM_SUB following NM_TITLE).
        (see also the GTMN_SecondaryError tag above).

EXAMPLE

NOTES
    The strings you supply for menu text are not copied, and must
    be preserved for the life of the menu.
    The resulting menus have no positional information.  You will
    want to call @{"LayoutMenusA()" Link "LayoutMenusA()"} (or @{"LayoutMenuItemsA()" Link "LayoutMenuItemsA()"}) to supply that.
    CreateMenusA() automatically provides you with a UserData field
    for each menu, menu-item or sub-item.  Use the GTMENU_USERDATA(menu)
    or GTMENUITEM_USERDATA(menuitem) macro to access it.

BUGS
    At present, if you put images into menus using IM_ITEM
    or IM_SUB for a NewMenu->Type, the image you supply must
    be an ordinary struct @{"Image" Link "ADCD_v1.2:Inc&AD2.1/Includes/intuition/intuition.h/Main" 619}.  You may not use a 'custom
    image' (eg. one obtained from a boopsi image-class).

SEE ALSO
    @{"LayoutMenusA()" Link "LayoutMenusA()"}, @{"FreeMenus()" Link "FreeMenus()"}, gadtools.h/GTMENU_USERDATA(),
    gadtools.h/GTMENUITEM_USERDATA()

@EndNode

@Node "DrawBevelBoxA()" "gadtools.library/DrawBevelBoxA"

NAME
    DrawBevelBoxA -- Draws a bevelled box. (V36)
    DrawBevelBox -- Varargs stub for DrawBevelBox(). (V36)

SYNOPSIS
    DrawBevelBoxA(rport, left, top, width, height, taglist)
                  A0     D0    D1   D2     D3      A1

    VOID DrawBevelBoxA(struct @{"RastPort" Link "ADCD_v1.2:Inc&AD2.1/Includes/graphics/rastport.h/Main" 53} *, WORD, WORD, WORD, WORD,
        struct @{"TagItem" Link "ADCD_v1.2:Inc&AD2.1/Includes/utility/tagitem.h/Main" 29} *taglist);

    DrawBevelBox(rport, left, top, width, height, firsttag, ...)

    VOID DrawBevelBox(struct @{"RastPort" Link "ADCD_v1.2:Inc&AD2.1/Includes/graphics/rastport.h/Main" 53} *, WORD, WORD, WORD, WORD,
        Tag, ...);

FUNCTION
    DrawBevelBoxA() renders a bevelled box of specified dimensions
    into the supplied @{"RastPort" Link "ADCD_v1.2:Inc&AD2.1/Includes/graphics/rastport.h/Main" 53}.

INPUTS
    rport - The @{"RastPort" Link "ADCD_v1.2:Inc&AD2.1/Includes/graphics/rastport.h/Main" 53} into which the box is to be drawn.
    left - The left edge of the box.
    top - The top edge of the box.
    width - The width of the box.
    height - The height of the box.
    taglist - Pointer to a @{"TagItem" Link "ADCD_v1.2:Inc&AD2.1/Includes/utility/tagitem.h/Main" 29} list.

TAGS
    GTBB_Recessed (BOOL):  Set to anything for a recessed-looking box.
        If absent, the box defaults, it would be raised.
    GT_VisualInfo (APTR):  You MUST supply the value you obtained
        from an earlier call to @{"GetVisualInfoA()" Link "GetVisualInfoA()"}.

RESULT
    None.

EXAMPLE

NOTES
    DrawBevelBox() is a rendering operation, not a gadget.  That
    means you must refresh it at the appropriate time, like any
    other rendering operation.

BUGS

SEE ALSO
    @{"GetVisualInfoA()" Link "GetVisualInfoA()"}

@EndNode

@Node "FreeGadgets()" "gadtools.library/FreeGadgets"

NAME
    FreeGadgets -- Free a linked list of gadgets. (V36)

SYNOPSIS
    FreeGadgets(glist)
                A0

    VOID FreeGadgets(struct @{"Gadget" Link "ADCD_v1.2:Inc&AD2.1/Includes/intuition/intuition.h/Main" 213} *glist);
                     A0

FUNCTION
    Frees any GadTools gadgets found on the linked list of gadgets
    beginning with the specified one.  Frees all the memory that was
    allocated by @{"CreateGadgetA()" Link "CreateGadgetA()"}.  This function will return safely
    with no action if it receives a NULL parameter.

INPUTS
    glist - pointer to first gadget in list to be freed.

RESULT
    none

EXAMPLE

NOTES

BUGS

SEE ALSO
    @{"CreateGadgetA()" Link "CreateGadgetA()"}

@EndNode

@Node "FreeMenus()" "gadtools.library/FreeMenus"

NAME
    FreeMenus -- Frees memory allocated by @{"CreateMenusA()" Link "CreateMenusA()"}. (V36)

SYNOPSIS
    FreeMenus(menu)
              A0

    VOID FreeMenus(struct @{"Menu" Link "ADCD_v1.2:Inc&AD2.1/Includes/intuition/intuition.h/Main" 59} *);

FUNCTION
    Frees the menus allocated by @{"CreateMenusA()" Link "CreateMenusA()"}.  It is safe to
    call this function with a NULL parameter.

INPUTS
    menu - Pointer to menu structure (or first MenuItem) obtained
    from @{"CreateMenusA()" Link "CreateMenusA()"}.

RESULT
    None.

EXAMPLE

NOTES

BUGS

SEE ALSO
    @{"CreateMenusA()" Link "CreateMenusA()"}

@EndNode

@Node "FreeVisualInfo()" "gadtools.library/FreeVisualInfo"

NAME
    FreeVisualInfo -- Return any resources taken by GetVisualInfo. (V36)

SYNOPSIS
    FreeVisualInfo(vi)
                   A0

    VOID FreeVisualInfo(APTR);

FUNCTION
    FreeVisualInfo() returns any memory or other resources that
    were allocated by @{"GetVisualInfoA()" Link "GetVisualInfoA()"}.  You should only call this function
    once you are done with using the gadgets (i.e. after @{"CloseWindow()" Link "ADCD_v1.2:Inc&AD2.1/Autodocs/intuition/CloseWindow()"}),
    but while the screen is still valid (i.e. before @{"CloseScreen()" Link "ADCD_v1.2:Inc&AD2.1/Autodocs/intuition/CloseScreen()"} or
    @{"UnlockPubScreen()" Link "ADCD_v1.2:Inc&AD2.1/Autodocs/intuition/UnlockPubScreen()"}).

INPUTS
    vi - Pointer that was obtained by calling @{"GetVisualInfoA()" Link "GetVisualInfoA()"}.

RESULT
    None.

EXAMPLE

NOTES

BUGS

SEE ALSO
    @{"GetVisualInfoA()" Link "GetVisualInfoA()"}

@EndNode

@Node "GetVisualInfoA()" "gadtools.library/GetVisualInfoA"

NAME
    GetVisualInfoA -- Get information GadTools needs for visuals. (V36)
    GetVisualInfo -- Varargs stub for GetVisualInfoA(). (V36)

SYNOPSIS
    vi = GetVisualInfoA(screen, taglist)
    D0                  A0      A1

    APTR vi = GetVisualInfoA(struct @{"Screen" Link "ADCD_v1.2:Inc&AD2.1/Includes/intuition/screens.h/Main" 95} *, struct @{"TagItem" Link "ADCD_v1.2:Inc&AD2.1/Includes/utility/tagitem.h/Main" 29} *);

    vi = GetVisualInfo(screen, firsttag, ...)

    APTR vi = GetVisualInfo(struct @{"Screen" Link "ADCD_v1.2:Inc&AD2.1/Includes/intuition/screens.h/Main" 95} *, Tag, ...);

FUNCTION
    Get a pointer to a (private) block of data containing various bits
    of information that GadTools needs to ensure the best quality
    visuals.  Use the result in the @{"NewGadget" Link "ADCD_v1.2:Inc&AD2.1/Includes/libraries/gadtools.h/Main" 91} structure of any gadget
    you create, or as a parameter to the various menu calls.  Once the
    gadgets/menus are no longer needed (after the last CloseWindow),
    call @{"FreeVisualInfo()" Link "FreeVisualInfo()"}.

INPUTS
    screen - Pointer to the screen you will be opening on.
    taglist - Pointer to list of TagItems.

RESULT
    vi - Pointer to private data.

EXAMPLE

NOTES

BUGS

SEE ALSO
    @{"FreeVisualInfo()" Link "FreeVisualInfo()"}, @{"intuition/LockPubScreen()" Link "ADCD_v1.2:Inc&AD2.1/Autodocs/intuition/LockPubScreen()"},
    @{"intuition/UnlockPubScreen()" Link "ADCD_v1.2:Inc&AD2.1/Autodocs/intuition/UnlockPubScreen()"}

@EndNode

@Node "GT_BeginRefresh()" "gadtools.library/GT_BeginRefresh"

NAME
    GT_BeginRefresh -- Begin refreshing friendly to GadTools. (V36)

SYNOPSIS
    GT_BeginRefresh(win)
                    A0

    VOID GT_BeginRefresh(struct @{"Window" Link "ADCD_v1.2:Inc&AD2.1/Includes/intuition/intuition.h/Main" 795} *);

FUNCTION
    Invokes the @{"intuition.library/BeginRefresh()" Link "ADCD_v1.2:Inc&AD2.1/Autodocs/intuition/BeginRefresh()"} function in a manner
    friendly to the @{"Gadget" Link "ADCD_v1.2:Inc&AD2.1/Includes/intuition/intuition.h/Main" 213} Toolkit.  This function call permits the
    GadTools gadgets to refresh themselves at the correct time.
    Call @{"GT_EndRefresh()" Link "GT_EndRefresh()"} function when done.

INPUTS
    win - Pointer to @{"Window" Link "ADCD_v1.2:Inc&AD2.1/Includes/intuition/intuition.h/Main" 795} structure for which a IDCMP_REFRESHWINDOW
        IDCMP event was received.

RESULT
    None.

EXAMPLE

NOTES
    The nature of GadTools precludes the use of the IDCMP flag
    WFLG_NOCAREREFRESH.  You must handle IDCMP_REFRESHWINDOW events
    in at least the minimal way, namely:

            case IDCMP_REFRESHWINDOW:
                GT_BeginRefresh(win);
                GT_EndRefresh(win, TRUE);
                break;

BUGS

SEE ALSO
    @{"intuition.library/BeginRefresh()" Link "ADCD_v1.2:Inc&AD2.1/Autodocs/intuition/BeginRefresh()"}

@EndNode

@Node "GT_EndRefresh()" "gadtools.library/GT_EndRefresh"

NAME
    GT_EndRefresh -- End refreshing friendly to GadTools. (V36)

SYNOPSIS
    GT_EndRefresh(win, complete)
                  A0   D0

    VOID GT_EndRefresh(struct @{"Window" Link "ADCD_v1.2:Inc&AD2.1/Includes/intuition/intuition.h/Main" 795} *, BOOL complete);

FUNCTION
    Invokes the @{"intuition.library/EndRefresh()" Link "ADCD_v1.2:Inc&AD2.1/Autodocs/intuition/EndRefresh()"} function in a manner
    friendly to the @{"Gadget" Link "ADCD_v1.2:Inc&AD2.1/Includes/intuition/intuition.h/Main" 213} Toolkit.  This function call permits
    GadTools gadgets to refresh themselves at the correct time.
    Call this function to @{"EndRefresh()" Link "ADCD_v1.2:Inc&AD2.1/Autodocs/intuition/EndRefresh()"} when you have used
    @{"GT_BeginRefresh()" Link "GT_BeginRefresh()"}.

INPUTS
    win - Pointer to @{"Window" Link "ADCD_v1.2:Inc&AD2.1/Includes/intuition/intuition.h/Main" 795} structure for which a IDCMP_REFRESHWINDOW
        IDCMP event was received.
    complete - TRUE when done with refreshing.

RESULT
    None.

EXAMPLE

NOTES

BUGS

SEE ALSO
    @{"intuition.library/EndRefresh()" Link "ADCD_v1.2:Inc&AD2.1/Autodocs/intuition/EndRefresh()"}

@EndNode

@Node "GT_FilterIMsg()" "gadtools.library/GT_FilterIMsg"

NAME
    GT_FilterIMsg -- Filter an @{"IntuiMessage" Link "ADCD_v1.2:Inc&AD2.1/Includes/intuition/intuition.h/Main" 677} through GadTools. (V36)

SYNOPSIS
    modimsg = GT_FilterIMsg(imsg)
    D0                      A1

    struct @{"IntuiMessage" Link "ADCD_v1.2:Inc&AD2.1/Includes/intuition/intuition.h/Main" 677} *GT_FilterIMsg(struct @{"IntuiMessage" Link "ADCD_v1.2:Inc&AD2.1/Includes/intuition/intuition.h/Main" 677} *);

FUNCTION
    NOTE WELL:  Extremely few programs will actually need this function.
    You almost certainly should be using @{"GT_GetIMsg()" Link "GT_GetIMsg()"} and @{"GT_ReplyIMsg()" Link "GT_ReplyIMsg()"}
    only, and not GT_FilterIMsg() and @{"GT_PostFilterIMsg()" Link "GT_PostFilterIMsg()"}.

    GT_FilterIMsg() takes the supplied @{"IntuiMessage" Link "ADCD_v1.2:Inc&AD2.1/Includes/intuition/intuition.h/Main" 677} and asks the
    @{"Gadget" Link "ADCD_v1.2:Inc&AD2.1/Includes/intuition/intuition.h/Main" 213} Toolkit to consider and possibly act on it.  Returns
    NULL if the message was only of significance to a GadTools gadget
    (i.e. not to you), else returns a pointer to a modified IDCMP
    message, which may contain additional information.
    You should examine the Class, Code, and IAddress fields of
    the returned message to learn what happened.  Do not make
    interpretations based on the original imsg.
    You should use @{"GT_PostFilterIMsg()" Link "GT_PostFilterIMsg()"} to revert to the original
    @{"IntuiMessage" Link "ADCD_v1.2:Inc&AD2.1/Includes/intuition/intuition.h/Main" 677} once you are done with the modified one.

INPUTS
    imsg - An @{"IntuiMessage" Link "ADCD_v1.2:Inc&AD2.1/Includes/intuition/intuition.h/Main" 677} you obtained from a Window's UserPort.

RESULT
    modimsg - A modified @{"IntuiMessage" Link "ADCD_v1.2:Inc&AD2.1/Includes/intuition/intuition.h/Main" 677}, possibly with extra information
        from GadTools, or NULL.

EXAMPLE

NOTES

BUGS

SEE ALSO
    @{"GT_GetIMsg()" Link "GT_GetIMsg()"}, @{"GT_PostFilterIMsg()" Link "GT_PostFilterIMsg()"}

@EndNode

@Node "GT_GetIMsg()" "gadtools.library/GT_GetIMsg"

NAME
    GT_GetIMsg -- Get an @{"IntuiMessage" Link "ADCD_v1.2:Inc&AD2.1/Includes/intuition/intuition.h/Main" 677}, with GadTools processing. (V36)

SYNOPSIS
    imsg = GT_GetIMsg(intuiport)
    D0                A0

    struct @{"IntuiMessage" Link "ADCD_v1.2:Inc&AD2.1/Includes/intuition/intuition.h/Main" 677} *GT_GetIMsg(struct @{"MsgPort" Link "ADCD_v1.2:Inc&AD2.1/Includes/exec/ports.h/Main" 27} *);

FUNCTION
    Use GT_GetIMsg() in place of the usual @{"exec.library/GetMsg()" Link "ADCD_v1.2:Inc&AD2.1/Autodocs/exec/GetMsg()"} when
    reading IntuiMessages from your window's UserPort.  If needed,
    the GadTools dispatcher will be invoked, and suitable processing
    will be done for gadget actions.  This function returns a pointer
    to a modified @{"IntuiMessage" Link "ADCD_v1.2:Inc&AD2.1/Includes/intuition/intuition.h/Main" 677} (which is a copy of the original,
    possibly with some supplementary information from GadTools).
    If there are no messages (or if the only messages are meaningful
    only to GadTools, NULL will be returned.

INPUTS
    intuiport - The Window->UserPort of a window that is using the
        @{"Gadget" Link "ADCD_v1.2:Inc&AD2.1/Includes/intuition/intuition.h/Main" 213} Toolkit.

RESULT
    imsg - Pointer to modified @{"IntuiMessage" Link "ADCD_v1.2:Inc&AD2.1/Includes/intuition/intuition.h/Main" 677}, or NULL if there are
        no applicable messages.

EXAMPLE

NOTES
    Be sure to use @{"GT_ReplyIMsg()" Link "GT_ReplyIMsg()"} and not @{"exec.library/ReplyMsg()" Link "ADCD_v1.2:Inc&AD2.1/Autodocs/exec/ReplyMsg()"} on
    messages obtained with GT_GetIMsg().
    If you intend to do more with the resulting message than read
    its fields, act on it, and reply it, you may find @{"GT_FilterIMsg()" Link "GT_FilterIMsg()"}
    more appropriate.

BUGS

SEE ALSO
    @{"GT_ReplyIMsg()" Link "GT_ReplyIMsg()"}, @{"GT_FilterIMsg()" Link "GT_FilterIMsg()"}

@EndNode

@Node "GT_PostFilterIMsg()" "gadtools.library/GT_PostFilterIMsg"

NAME
    GT_PostFilterIMsg -- Return the unfiltered message after
        @{"GT_FilterIMsg()" Link "GT_FilterIMsg()"} was called, and clean up. (V36)

SYNOPSIS
    imsg = GT_PostFilterIMsg(modimsg)
    D0                       A1

    struct @{"IntuiMessage" Link "ADCD_v1.2:Inc&AD2.1/Includes/intuition/intuition.h/Main" 677} *GT_PostFilterIMsg(struct @{"IntuiMessage" Link "ADCD_v1.2:Inc&AD2.1/Includes/intuition/intuition.h/Main" 677} *);

FUNCTION
    NOTE WELL:  Extremely few programs will actually need this function.
    You almost certainly should be using @{"GT_GetIMsg()" Link "GT_GetIMsg()"} and @{"GT_ReplyIMsg()" Link "GT_ReplyIMsg()"}
    only, and not @{"GT_FilterIMsg()" Link "GT_FilterIMsg()"} and GT_PostFilterIMsg().

    Performs any clean-up necessitated by a previous call to
    @{"GT_FilterIMsg()" Link "GT_FilterIMsg()"}.  The original @{"IntuiMessage" Link "ADCD_v1.2:Inc&AD2.1/Includes/intuition/intuition.h/Main" 677} is now yours to handle.
    Do not interpret the fields of the original @{"IntuiMessage" Link "ADCD_v1.2:Inc&AD2.1/Includes/intuition/intuition.h/Main" 677}, but
    rather use only the one you got from @{"GT_FilterIMsg()" Link "GT_FilterIMsg()"}.  You
    may only do message related things at this point, such as queueing
    it up or replying it.  Since you got the message with
    @{"exec.library/GetMsg()" Link "ADCD_v1.2:Inc&AD2.1/Autodocs/exec/GetMsg()"}, your responsibilities do include replying
    it with @{"exec.library/ReplyMsg()" Link "ADCD_v1.2:Inc&AD2.1/Autodocs/exec/ReplyMsg()"}. This function may be safely
    called with a NULL parameter.

INPUTS
    modimsg - A modified @{"IntuiMessage" Link "ADCD_v1.2:Inc&AD2.1/Includes/intuition/intuition.h/Main" 677} obtained with @{"GT_FilterIMsg()" Link "GT_FilterIMsg()"}.

RESULT
    imsg - A pointer to the original @{"IntuiMessage" Link "ADCD_v1.2:Inc&AD2.1/Includes/intuition/intuition.h/Main" 677}, if @{"GT_FilterIMsg()" Link "GT_FilterIMsg()"}
        returned non-NULL.

EXAMPLE

NOTES
    Be sure to use @{"exec.library/ReplyMsg()" Link "ADCD_v1.2:Inc&AD2.1/Autodocs/exec/ReplyMsg()"} on the original @{"IntuiMessage" Link "ADCD_v1.2:Inc&AD2.1/Includes/intuition/intuition.h/Main" 677}
    you obtained with @{"GetMsg()" Link "ADCD_v1.2:Inc&AD2.1/Autodocs/exec/GetMsg()"}, (which is the what you passed to
    @{"GT_FilterIMsg()" Link "GT_FilterIMsg()"}), and not on the parameter of this function.

BUGS

SEE ALSO
    @{"GT_FilterIMsg()" Link "GT_FilterIMsg()"}

@EndNode

@Node "GT_RefreshWindow()" "gadtools.library/GT_RefreshWindow"

NAME
    GT_RefreshWindow -- Refresh all the GadTools gadgets. (V36)

SYNOPSIS
    GT_RefreshWindow(win, req)
                     A0   A1

    VOID GT_RefreshWindow(struct @{"Window" Link "ADCD_v1.2:Inc&AD2.1/Includes/intuition/intuition.h/Main" 795} *, struct @{"Requester" Link "ADCD_v1.2:Inc&AD2.1/Includes/intuition/intuition.h/Main" 143} *);

FUNCTION
    Perform the initial refresh of all the GadTools gadgets you have
    created.  After you have opened your window, you must call this
    function.  Or, if you have opened your window without gadgets,
    you add the gadgets with @{"intuition.library/AddGList()" Link "ADCD_v1.2:Inc&AD2.1/Autodocs/intuition/AddGList()"},
    refresh them using @{"intuition.library/RefreshGList()" Link "ADCD_v1.2:Inc&AD2.1/Autodocs/intuition/RefreshGList()"}, then call
    this function.
    You should not need this function at other times.

INPUTS
    win - Pointer to the @{"Window" Link "ADCD_v1.2:Inc&AD2.1/Includes/intuition/intuition.h/Main" 795} containing GadTools gadgets.
    req - Pointer to requester, or NULL if not a requester (currently
        ignored - use NULL).

RESULT
    None.

EXAMPLE

NOTES
    req must currently be NULL.  GadTools gadgets are not supported
    in requesters.  This field may allow such support at a future date.

BUGS

SEE ALSO
    @{"GT_BeginRefresh()" Link "GT_BeginRefresh()"}

@EndNode

@Node "GT_ReplyIMsg()" "gadtools.library/GT_ReplyIMsg"

NAME
    GT_ReplyIMsg -- Reply a message obtained with @{"GT_GetIMsg()" Link "GT_GetIMsg()"}. (V36)

SYNOPSIS
    GT_ReplyIMsg(imsg)
                 A1

    VOID GT_ReplyIMsg(struct @{"IntuiMessage" Link "ADCD_v1.2:Inc&AD2.1/Includes/intuition/intuition.h/Main" 677} *);

FUNCTION
    Reply a modified @{"IntuiMessage" Link "ADCD_v1.2:Inc&AD2.1/Includes/intuition/intuition.h/Main" 677} obtained with @{"GT_GetIMsg()" Link "GT_GetIMsg()"}.
    If you use @{"GT_GetIMsg()" Link "GT_GetIMsg()"}, use this function where you would normally
    have used @{"exec.library/ReplyMsg()" Link "ADCD_v1.2:Inc&AD2.1/Autodocs/exec/ReplyMsg()"}.
    You may safely call this routine with a NULL pointer (nothing
    will be done).

INPUTS
    imsg - A modified @{"IntuiMessage" Link "ADCD_v1.2:Inc&AD2.1/Includes/intuition/intuition.h/Main" 677} obtained with @{"GT_GetIMsg()" Link "GT_GetIMsg()"}.

RESULT
    None.

EXAMPLE

NOTES
    When using GadTools, you MUST explicitly GT_ReplyIMsg()
    all messages you receive.  You cannot depend on @{"CloseWindow()" Link "ADCD_v1.2:Inc&AD2.1/Autodocs/intuition/CloseWindow()"}
    to handle messages you have not replied.

BUGS

SEE ALSO
    @{"GT_GetIMsg()" Link "GT_GetIMsg()"}

@EndNode

@Node "GT_SetGadgetAttrsA()" "gadtools.library/GT_SetGadgetAttrsA"

NAME
    GT_SetGadgetAttrsA -- Change the attributes of a GadTools gadget. (V36)
    GT_SetGadgetAttrs -- Varargs stub for GT_SetGadgetAttrsA(). (V36)

SYNOPSIS
    GT_SetGadgetAttrsA(gad, win, req, taglist)
                       A0   A1   A2   A3

    VOID GT_SetGadgetAttrsA(struct @{"Gadget" Link "ADCD_v1.2:Inc&AD2.1/Includes/intuition/intuition.h/Main" 213} *, struct @{"Window" Link "ADCD_v1.2:Inc&AD2.1/Includes/intuition/intuition.h/Main" 795} *,
        struct @{"Requester" Link "ADCD_v1.2:Inc&AD2.1/Includes/intuition/intuition.h/Main" 143} *, struct @{"TagItem" Link "ADCD_v1.2:Inc&AD2.1/Includes/utility/tagitem.h/Main" 29} *);

    GT_SetGadgetAttrs(gad, win, req, firsttag, ...)

    VOID GT_SetGadgetAttrs(struct @{"Gadget" Link "ADCD_v1.2:Inc&AD2.1/Includes/intuition/intuition.h/Main" 213} *, struct @{"Window" Link "ADCD_v1.2:Inc&AD2.1/Includes/intuition/intuition.h/Main" 795} *,
        struct @{"Requester" Link "ADCD_v1.2:Inc&AD2.1/Includes/intuition/intuition.h/Main" 143} *, Tag, ...);

FUNCTION
    Change the attributes of the specified gadget, according to the
    attributes chosen in the tag list.

INPUTS
    gad - Pointer to the gadget in question.
    win - Pointer to the window containing the gadget.
    req - Pointer to the requester containing the gadget, or NULL if
        not in a requester.  (Not yet implemented, use NULL).
    taglist - Pointer to @{"TagItem" Link "ADCD_v1.2:Inc&AD2.1/Includes/utility/tagitem.h/Main" 29} list.

TAGS
    BUTTON_KIND:
    GA_Disabled (BOOL) - Set to TRUE to disable gadget, FALSE otherwise
        (defaults to FALSE).

    CHECKBOX_KIND:
    GTCB_Checked (BOOL) - Initial state of checkbox, defaults to FALSE.
    GA_Disabled (BOOL) - Set to TRUE to disable gadget, FALSE otherwise
        (defaults to FALSE).

    CYCLE_KIND:
    GTCY_Active (UWORD) - The ordinal number (counting from zero) of
        the active choice of a cycle gadget (defaults to zero).
    GTCY_Labels (STRPTR *) - (GadTools V37 and higher only)
        Pointer to NULL-terminated array of strings
        that are the choices offered by the cycle gadget.
    GA_Disabled (BOOL) - (GadTools V37 and higher only)
        Set to TRUE to disable gadget, FALSE otherwise
        (defaults to FALSE).

    INTEGER_KIND:
    GTIN_Number (ULONG) - The initial contents of the integer gadget
        (default zero).
    GA_Disabled (BOOL) - Set to TRUE to disable gadget, FALSE otherwise
        (defaults to FALSE).

    LISTVIEW_KIND:
    GTLV_Top (UWORD) - Top item visible in the listview (defaults to zero).
    GTLV_Labels (struct @{"List" Link "ADCD_v1.2:Inc&AD2.1/Includes/exec/lists.h/Main" 19} *) - @{"List" Link "ADCD_v1.2:Inc&AD2.1/Includes/exec/lists.h/Main" 19} of labels whose ln_Name fields
        are to be displayed in the listview.  Use a value of ~0 to
        "detach" your @{"List" Link "ADCD_v1.2:Inc&AD2.1/Includes/exec/lists.h/Main" 19} from the display.  You must detach your list
        before modifying the @{"List" Link "ADCD_v1.2:Inc&AD2.1/Includes/exec/lists.h/Main" 19} structure, since GadTools reserves
        the right to traverse it on another task's schedule.  When you
        are done, attach the list by using the tag pair
        {GTLV_Labels, list}.
    GTLV_Selected (UWORD) - Ordinal number of currently selected
        item (defaults to zero if GTLV_ShowSelected is set).

    MX_KIND:
    GTMX_Active (UWORD) - The ordinal number (counting from zero) of
        the active choice of an mx gadget (Defaults to zero).

    NUMBER_KIND:
    GTNM_Number - A signed long integer to be displayed as a read-only
         number (default 0).

    PALETTE_KIND:
    GTPA_Color (UBYTE) - Initially selected color of the palette
        (defaults to 1).
    GA_Disabled (BOOL) - Set to TRUE to disable gadget, FALSE otherwise
        (defaults to FALSE).

    SCROLLER_KIND:
    GTSC_Top (WORD) - Top visible in scroller (defaults to zero).
    GTSC_Total (WORD) - Total in scroller area (defaults to zero).
    GTSC_Visible (WORD) - Number visible in scroller (defaults to 2).
    GA_Disabled (BOOL) - Set to TRUE to disable gadget, FALSE otherwise
        (defaults to FALSE).

    SLIDER_KIND:
    GTSL_Min (WORD) - Minimum level for slider (default 0).
    GTSL_Max (WORD) - Maximum level for slider (default 15).
    GTSL_Level (WORD) - Current level of slider (default 0).
    GA_Disabled (BOOL) - Set to TRUE to disable gadget, FALSE otherwise
        (defaults to FALSE).

    STRING_KIND:
    GTST_String (STRPTR) - The initial contents of the string gadget,
         or NULL (default) if string is to start empty.
    GA_Disabled (BOOL) - Set to TRUE to disable gadget, FALSE otherwise
        (defaults to FALSE).

    TEXT_KIND:
    GTTX_Text - Pointer to a NULL terminated string to be displayed,
        as a read-only text-display gadget, or NULL. defaults to NULL.

RESULT
    None.

EXAMPLE

NOTES
    req must currently be NULL.  GadTools gadgets are not supported
    in requesters.  This field may allow such support at a future date.

    This function may not be called inside of a @{"GT_BeginRefresh()" Link "GT_BeginRefresh()"} /
    @{"GT_EndRefresh()" Link "GT_EndRefresh()"} session.  (As always, restrict yourself to simple
    rendering functions).

BUGS

SEE ALSO

@EndNode

@Node "LayoutMenuItemsA()" "gadtools.library/LayoutMenuItemsA"

NAME
    LayoutMenuItemsA -- Position all the menu items. (V36)
    LayoutMenuItems -- Varargs stub for LayoutMenuItemsA(). (V36)

SYNOPSIS
    success = LayoutMenuItemsA(menuitem, vi, taglist)
    D0                         A0        A1  A2

    BOOL LayoutMenuItemsA(struct @{"MenuItem" Link "ADCD_v1.2:Inc&AD2.1/Includes/intuition/intuition.h/Main" 87} *, APTR, struct @{"TagItem" Link "ADCD_v1.2:Inc&AD2.1/Includes/utility/tagitem.h/Main" 29} *);

    success = LayoutMenuItems(menuitem, vi, firsttag, ...)

    BOOL LayoutMenuItemsA(struct @{"MenuItem" Link "ADCD_v1.2:Inc&AD2.1/Includes/intuition/intuition.h/Main" 87} *, APTR, Tag, ...);

FUNCTION
    Lays out all the menu items and sub-items according to
    the supplied visual information and tag parameters.  You would use this
    if you used @{"CreateMenusA()" Link "CreateMenusA()"} to make a single menu-pane (with sub-items,
    if any), instead of a whole menu strip.
    This routine attempts to columnize and/or shift the MenuItems in
    the event that a menu would be too tall or too wide.

INPUTS
    menuitem - Pointer to first @{"MenuItem" Link "ADCD_v1.2:Inc&AD2.1/Includes/intuition/intuition.h/Main" 87} in a linked list of
        items.
    vi - Pointer returned by @{"GetVisualInfoA()" Link "GetVisualInfoA()"}.
    taglist - Pointer to a @{"TagItem" Link "ADCD_v1.2:Inc&AD2.1/Includes/utility/tagitem.h/Main" 29} list.

TAGS
    GTMN_TextAttr (struct @{"TextAttr" Link "ADCD_v1.2:Inc&AD2.1/Includes/graphics/text.h/Main" 64} *) - Text Attribute to use for
        menu-items and sub-items.  If not supplied, the screen's
        font will be used.  This font must be openable via @{"OpenFont()" Link "ADCD_v1.2:Inc&AD2.1/Autodocs/graphics/OpenFont()"}
        when this function is called.
    GTMN_Menu (struct @{"Menu" Link "ADCD_v1.2:Inc&AD2.1/Includes/intuition/intuition.h/Main" 59} *) - Pointer to the @{"Menu" Link "ADCD_v1.2:Inc&AD2.1/Includes/intuition/intuition.h/Main" 59} structure whose
        FirstItem is the @{"MenuItem" Link "ADCD_v1.2:Inc&AD2.1/Includes/intuition/intuition.h/Main" 87} supplied above.  If the menu items are
        such that they need to be columnized or shifted, the @{"Menu" Link "ADCD_v1.2:Inc&AD2.1/Includes/intuition/intuition.h/Main" 59}
        structure is needed to perform the complete calculation.
        It is suggested you always provide this information.

RESULT
    success - TRUE if successful, false otherwise (signifies that
        the @{"TextAttr" Link "ADCD_v1.2:Inc&AD2.1/Includes/graphics/text.h/Main" 64} wasn't openable).

EXAMPLE

NOTES

BUGS
    If a menu ends up being wider than the whole screen, it will
    run off the right-hand side.

SEE ALSO
    @{"CreateMenusA()" Link "CreateMenusA()"}, @{"GetVisualInfoA()" Link "GetVisualInfoA()"}

@EndNode

@Node "LayoutMenusA()" "gadtools.library/LayoutMenusA"

NAME
    LayoutMenusA -- Position all the menus and menu items. (V36)
    LayoutMenus -- Varargs stub for LayoutMenusA(). (V36)

SYNOPSIS
    success = LayoutMenusA(menu, vi, taglist)
    D0                     A0    A1  A2

    BOOL LayoutMenusA(struct @{"Menu" Link "ADCD_v1.2:Inc&AD2.1/Includes/intuition/intuition.h/Main" 59} *, APTR, struct @{"TagItem" Link "ADCD_v1.2:Inc&AD2.1/Includes/utility/tagitem.h/Main" 29} *);

    success = LayoutMenus(menu, vi, firsttag, ...)

    BOOL LayoutMenus(struct @{"Menu" Link "ADCD_v1.2:Inc&AD2.1/Includes/intuition/intuition.h/Main" 59} *, APTR, Tag, ...);

FUNCTION
    Lays out all the menus, menu items and sub-items in the supplied
    menu according to the supplied visual information and tag parameters.
    This routine attempts to columnize and/or shift the MenuItems in
    the event that a menu would be too tall or too wide.

INPUTS
    menu - Pointer to menu obtained from @{"CreateMenusA()" Link "CreateMenusA()"}.
    vi - Pointer returned by @{"GetVisualInfoA()" Link "GetVisualInfoA()"}.
    taglist - Pointer to a @{"TagItem" Link "ADCD_v1.2:Inc&AD2.1/Includes/utility/tagitem.h/Main" 29} list.

TAGS
    GTMN_TextAttr (struct @{"TextAttr" Link "ADCD_v1.2:Inc&AD2.1/Includes/graphics/text.h/Main" 64} *) - Text Attribute to use for
        menu-items and sub-items.  If not supplied, the screen's
        font will be used.  This font must be openable via @{"OpenFont()" Link "ADCD_v1.2:Inc&AD2.1/Autodocs/graphics/OpenFont()"}
        when this function is called.

RESULT
    success - TRUE if successful, false otherwise (signifies that
        the @{"TextAttr" Link "ADCD_v1.2:Inc&AD2.1/Includes/graphics/text.h/Main" 64} wasn't openable).

EXAMPLE

NOTES
    When using this function, there is no need to also call
    @{"LayoutMenuItemsA()" Link "LayoutMenuItemsA()"}.

BUGS
    If a menu ends up being wider than the whole screen, it will
    run off the right-hand side.

SEE ALSO
    @{"CreateMenusA()" Link "CreateMenusA()"}, @{"GetVisualInfoA()" Link "GetVisualInfoA()"}

@EndNode

