@database "chooser_gc"
@master "AMIDEV:NDK/Autodocs/chooser_gc.doc"

@Node Main "chooser_gc.doc"
@toc "Autodocs/AG/INDEX/Main"
    @{" --datasheet--() " Link "--datasheet--()"}
    @{" --styleguide--() " Link "--styleguide--()"}
    @{" AllocChooserNodeA() " Link "AllocChooserNodeA()"}
    @{" CHOOSER_GetClass() " Link "CHOOSER_GetClass()"}
    @{" FreeChooserNode() " Link "FreeChooserNode()"}
    @{" GetChooserNodeAttrsA() " Link "GetChooserNodeAttrsA()"}
    @{" SetChooserNodeAttrsA() " Link "SetChooserNodeAttrsA()"}
@EndNode

@Node "--datasheet--()" "chooser_gc/--datasheet--"

@{b}    NAME@{ub}
        chooser_gc -- A pop-up/drop-down small list selection gadget.

@{b}    SUPERCLASS@{ub}
        gadgetclass

@{b}    REQUIRES@{ub}
        bevel.image, glyph.image

@{b}    DESCRIPTION@{ub}
        A chooser is a small-list selection object.  In its inactive mode it
        looks much like a button or cycle gadget.  When the button is pressed
        using the mouse, a menu displaying the items in the list is displayed
.

        The chooser operates in either of two modes, pop-up and drop-down.
        Even though they may operate similarly internally, they are for two
        different functions.  Consult the chooser style guide for
        information on how to use these two modes.

        Advantages that this class provides:

         > Supports window relativity.

         > Supports OS 3.0 BOOPSI @{"Gadget" Link "INCLUDE:intuition/intuition.h/Main" 212} HelpTest.

         > Cycle2Menu style activation.

         > Supports tab-cycle activation and keyboard control.

@{b}    METHODS@{ub}
        @{"OM_NEW" Link "tabs_gc/OM_NEW"} -- Create the chooser gadget.  Passed to superclass.

        @{"OM_SET" Link "tabs_gc/OM_SET"} -- Set object attributes.  Passed to superclass first.

        OM_DISPOSE -- Cancels the chooser menu before being passed to
            superclass.

        OM_UPDATE -- Set object notification attributes & render.
            Passed to superclass first.

        OM_NOTIFY -- Notify object attributes. Passed to superclass last.

        @{"GM_RENDER" Link "tabs_gc/GM_RENDER"} -- Renders the gadget imagery.  Overrides the superclass.

        @{"GM_HITTEST" Link "tabs_gc/GM_HITTEST"} -- Determines if mouse is within the gadget rectangle.
            Overrrides the superclass.

        @{"GM_GOACTIVE" Link "tabs_gc/GM_GOACTIVE"} -- Handles activation, pops up the chooser menu.
            Overrides the superclass.

        GM_HANDLEINPUT -- Handles input events once active.  Overrides the
            superclass.

        GM_GOINACTIVE -- Closes the chooser menu.  Overrides the superclass.

        GM_DOMAIN -- Calculates mix/max sizes. Overrides the superclass.

        GM_KEYACTIVE -- Activates gadget via keyboard, advances pop-up
            selection to the next item, if SHIFT is pressed it selects
            the previous item. Invoked by window.class only.

        GM_KEYINACTIVE -- Deactivates gadget. Invoked by window.class only.

        All other methods are passed to the superclass.

@{b}    ATTRIBUTES@{ub}
        GA_ID (WORD)
            Applicability is (OM_NEW, @{"OM_SET" Link "tabs_gc/OM_SET"}, OM_UPDATE, @{"OM_GET" Link "tabs_gc/OM_GET"}, OM_NOTIFY)

        GA_ReadOnly (BOOL)
            Set to TRUE to make the gadget non-selectable, but without
            a ghost pattern.

            Defaults to FALSE.

            Applicability is (OM_NEW, @{"OM_SET" Link "tabs_gc/OM_SET"}, OM_UPDATE, OM_GET)

        GA_Disabled (BOOL)
            Set to TRUE to disable gadget, FALSE otherwise.

            Defaults to FALSE.

            Applicability is (OM_NEW, @{"OM_SET" Link "tabs_gc/OM_SET"}, OM_UPDATE, OM_GET)

        GA_TextAttr (struct @{"TextAttr" Link "INCLUDE:graphics/text.h/Main" 63} *)
            Font to use for the gadget text.

            Defaults to the screen's font.

            Applicability is (OM_NEW, OM_GET)

        GA_Text (STRPTR)
            Title to appear within the select box when in drop-down mode.
            Same as CHOOSER_Title.

            Defaults to @{"NULL" Link "rexxsupport/NULL"}.

            Applicability is (OM_NEW, @{"OM_SET" Link "tabs_gc/OM_SET"}, OM_UPDATE, OM_GET)

        CHOOSER_PopUp (BOOL)
            Sets the chooser to work in popup mode.
            Generally this mode is used for selecting an application mode or
            a state from a list of possible values.  This item is mutually
            exclusive to CHOOSER_DropDown, one of the two MUST be TRUE.

            Defaults to FALSE.

            Applicability is (OM_NEW, @{"OM_SET" Link "tabs_gc/OM_SET"}, OM_UPDATE, OM_GET)

        CHOOSER_DropDown (BOOL)
            Sets the chooser to work in dropdown mode.  Generally for
            selecting an action to perform from a list of possible actions.
            This item is mutually exclusive to CHOOSER_PopUp, one of the
            two MUST be TRUE.

            Defaults to FALSE.

            Applicability is (OM_NEW, @{"OM_SET" Link "tabs_gc/OM_SET"}, OM_UPDATE, OM_GET)

        CHOOSER_Title (STRPTR)
            Title to appear within the select box when in dropdown mode

            Defaults to @{"NULL" Link "rexxsupport/NULL"}.

            Applicability is (OM_NEW, @{"OM_SET" Link "tabs_gc/OM_SET"}, OM_UPDATE, OM_GET)

        CHOOSER_Labels (struct @{"List" Link "INCLUDE:exec/lists.h/Main" 19} *)
            Exec @{"List" Link "INCLUDE:exec/lists.h/Main" 19} of labels.  Each node must be allocated with the
            @{"AllocChooserNodeA()" Link "AllocChooserNodeA()"} function.

            Applicability is (OM_NEW, @{"OM_SET" Link "tabs_gc/OM_SET"}, OM_UPDATE, OM_GET)

        CHOOSER_LabelArray (STRPTR *) (V45)
            Pointer to NULL-terminated array of strings that are the choices
            offered by the chooser gadget. Use ~0 to add a separator bar to t
he
            list. Example:

            @{"STRPTR" Link "INCLUDE:exec/types.h/Main" 137} options[] = {
               "Coffee", "Tea", ~0L, "Coke", "Beer", @{"NULL" Link "rexxsupport/NULL"}
            };

            The array can be allocated on the stack, the text however won't
            be copied and must stay valid for the lifetime of the chooser obj
ect.

            Applicability is (OM_NEW, @{"OM_SET" Link "tabs_gc/OM_SET"}, OM_UPDATE)

        CHOOSER_Justification (WORD) (V45)
            Specifies the label alignment (CHJ_LEFT, CHJ_CENTER, CHJ_RIGHT).

            Defaults to CHJ_LEFT.

            Applicability is (OM_NEW, OM_SET)

        CHOOSER_MaxLabels (WORD)
            Set the maximum number of labels that will be displayed in the
            chooser, regardless of the size of the list.

            Defaults to 12.

            Applicability is (OM_NEW, @{"OM_SET" Link "tabs_gc/OM_SET"}, OM_UPDATE, OM_GET)

        CHOOSER_Active (WORD) // Obsolete
        CHOOSER_Selected (WORD)
            Index of selected label in the list.

            Applicability is (OM_NEW, @{"OM_SET" Link "tabs_gc/OM_SET"}, OM_UPDATE, @{"OM_GET" Link "tabs_gc/OM_GET"}, OM_NOTIFY)

        CHOOSER_Width (WORD)
            The width of the chooser menu.

            Defaults to the width of the gadget select box.

            Applicability is (OM_NEW, @{"OM_SET" Link "tabs_gc/OM_SET"}, OM_UPDATE, OM_GET)

        CHOOSER_AutoFit (BOOL)
            Set the width of the chooser menu so that it fits the widest
            label in the list.

            Defaults to FALSE.

            Applicability is (OM_NEW, @{"OM_SET" Link "tabs_gc/OM_SET"}, OM_UPDATE, OM_GET)

@EndNode

@Node "--styleguide--()" "chooser_gc/--styleguide--"

@{b}    CHOOSER STYLE@{ub}
        The chooser has two very distinct modes of operation, pop-up and
        drop-down.  It is important to understand the differences between
        these two modes and to use the proper mode in the proper context.

@{b}    POP-UP CHOOSERS@{ub}
        A pop-up is generally used for setting an application mode or state,
        and in many cases it can replace a cycle gadget or MX (radio button)
        gadget.  In this mode, there is a currently active item in the list
        of selections, which will be displayed in the gadget select button.
        This has the same advantage of a cycle menu in that it is compact,
        with the further advantage that all values can be displayed at once
        and therefore the list of values can be much larger, though generally
        no more than a dozen items should be displayed.

@{b}    DROP-DOWN CHOOSERS@{ub}
        A drop-down chooser is for performing an action from a list of
        available actions.  In this mode, the gadget select box contains a
        title indicating what the actions are for.  These actions should all
        be closely related, and specific to a certain context within the
        application.  This can be used to replace a group of buttons, or a
        cycle gadget and a button where the cycle gadget modifies the
        behaviour of the button.  Since using the chooser in this mode makes
        functions effectively hidden, it should generally only be used where
        compactness is a significant issue.

        An alternate use for a drop-down is to use it as a means of accessing
        a "hot list" for a string or integer gadget.  For example, in a word
        processor you might have a string gadget at the top of the screen for
        entering the text point size.  Beside that you could have a drop-down
        chooser that lists some common point sizes that would then be copied
        into your integer gadget and change the text size when you make a
        selection.  When a drop-down is used this way, it is generally
        desirable not to have the drop-down display a title within the gadget
        box (pass @{"NULL" Link "rexxsupport/NULL"} for CHOOSER_Title) and to make the gadget thin enough
        so that just the arrow is displayed (use about 20 for GA_Width if not
        using the chooser within a layout group).

@EndNode

@Node "AllocChooserNodeA()" "chooser_gc/AllocChooserNodeA"

@{b}    NAME@{ub}
        AllocChooserNodeA -- @{"Allocate" Link "exec/Allocate()"} a chooser node.

@{b}    SYNOPSIS@{ub}
        struct @{"Node" Link "INCLUDE:exec/nodes.h/Main" 21} * AllocChooserNode(Tag, ...)
        node = AllocChooserNode(columns, @{"Tag" Link "INCLUDE:utility/tagitem.h/Main" 28}, ...)

        struct @{"Node" Link "INCLUDE:exec/nodes.h/Main" 21} * AllocChooserNodeA(struct @{"TagItem" Link "INCLUDE:utility/tagitem.h/Main" 30} *)
        node = AllocChooserNodeA(taglist)

@{b}    FUNCTION@{ub}
        Allocates a node that can be added to the Exec linked list of
        labels in the chooser.  This is the only way to allocate a
        node for this list, you cannot allocate nodes yourself because
        the chooser class uses a private node structure.

@{b}    INPUTS@{ub}
        taglist - Attributes for the node, passed onto @{"SetChooserNodeAttrsA()" Link "SetChooserNodeAttrsA()"}
.

@{b}    RESULT@{ub}
        node - A node that can be added into the Exec list of labels for
            a chooser gadget.

@{b}    SEE ALSO@{ub}
        @{"FreeChooserNode()" Link "FreeChooserNode()"}, @{"SetChooserNodeAttrsA()" Link "SetChooserNodeAttrsA()"}

@EndNode

@Node "CHOOSER_GetClass()" "chooser_gc/CHOOSER_GetClass"

@{b}    NAME@{ub}
        CHOOSER_GetClass -- Gets the pointer to the chooser class.

@{b}    SYNOPSIS@{ub}
        chooser_class = CHOOSER_GetClass();
        D0

        Class * CHOOSER_GetClass(VOID);

@{b}    FUNCTION@{ub}
        This function is only available in runtime linked version of the
        class, and is not in the compiler linker library chooser_gc.lib.

        Obtains the pointer to the chooser gadget class for use with
        @{"NewObject()" Link "intuition/NewObject()"}.  This function always returns a valid pointer so
        you do not need to check it.  The reason is that if the library
        opens fine, then the pointer returned is already setup.  (Of course
        this implies that if opening the library fails, you shouldn't be
        calling this.)

        Note that this function does not create the class, that is done
        when the class library is opened.

@{b}    INPUTS@{ub}
        Nothing.

@{b}    RESULT@{ub}
        chooser_class - Pointer to the chooser gadget class.

@{b}    SEE ALSO@{ub}

@EndNode

@Node "FreeChooserNode()" "chooser_gc/FreeChooserNode"

@{b}    NAME@{ub}
        FreeChooserNode -- Free a chooser node.

@{b}    SYNOPSIS@{ub}
        VOID FreeChooserNode(struct @{"Node" Link "INCLUDE:exec/nodes.h/Main" 21} *)
        FreeChooserNode(node)

@{b}    FUNCTION@{ub}
        Frees a chooser node allocated with @{"AllocChooserNodeA()" Link "AllocChooserNodeA()"}.

@{b}    INPUTS@{ub}
        node - The node to free.

@{b}    SEE ALSO@{ub}
        @{"AllocChooserNodeA()" Link "AllocChooserNodeA()"}

@EndNode

@Node "GetChooserNodeAttrsA()" "chooser_gc/GetChooserNodeAttrsA"

@{b}    NAME@{ub}
        GetChooserNodeAttrsA -- Get attributes of a chooser node.

@{b}    SYNOPSIS@{ub}
        VOID GetChooserNodeAttrs(struct @{"Node" Link "INCLUDE:exec/nodes.h/Main" 21} *, @{"Tag" Link "INCLUDE:utility/tagitem.h/Main" 28}, ...)
        GetChooserNodeAttrs(node, firsttag, ...)

        VOID GetChooserNodeAttrsA(struct @{"Node" Link "INCLUDE:exec/nodes.h/Main" 21} *, struct @{"TagItem" Link "INCLUDE:utility/tagitem.h/Main" 30} *)
        GetChooserNodeAttrsA(node, taglist)

@{b}    FUNCTION@{ub}
        The chooser uses a private node structure and all attributes
        are hidden, and must therefore be accessed with this function.

@{b}    INPUTS@{ub}
        node - The chooser node to get the information on.
        taglist - A tag list of attributes to get.  ti_Tag is the attribute
            to get and ti_Data is a pointer to a location to copy the result
            to.  The exception is LBNA_Column, which is used to specify a
            column to get attributes on.

@{b}    SEE ALSO@{ub}
        @{"SetChooserNodeAttrsA()" Link "SetChooserNodeAttrsA()"}

@EndNode

@Node "SetChooserNodeAttrsA()" "chooser_gc/SetChooserNodeAttrsA"

@{b}    NAME@{ub}
        SetChooserNodeAttrsA -- Set attributes of a chooser node.

@{b}    SYNOPSIS@{ub}
        VOID SetChooserNodeAttrs(struct @{"Node" Link "INCLUDE:exec/nodes.h/Main" 21} *, @{"Tag" Link "INCLUDE:utility/tagitem.h/Main" 28}, ...)
        SetChooserNodeAttrs(node, firsttag, ...)

        VOID SetChooserNodeAttrsA(struct @{"Node" Link "INCLUDE:exec/nodes.h/Main" 21} *, struct @{"TagItem" Link "INCLUDE:utility/tagitem.h/Main" 30} *)
        SetChooserNodeAttrsA(node, taglist)

@{b}    FUNCTION@{ub}
        Changes attributes for a chooser node.  Since the chooser
        class uses a private node structure, this is the only way to change
        node attributes.

        You may NOT change node attributes when the node is in a list
        attached to a chooser gadget.  You must first detach the list
        with CHOOSER_Labels, ~0 before you can change attributes, and
        then re-attach the list.

@{b}    TAGS@{ub}
        CNA_Text (STRPTR)
        @{"Text" Link "graphics/Text()"} string to appear as a line in the chooser menu. This tag
        must be supplied for the node.

        CNA_Image (struct @{"Image" Link "INCLUDE:intuition/intuition.h/Main" 710} *)
        @{"Image" Link "INCLUDE:intuition/intuition.h/Main" 710} to be placed to the left of the CNA_Text in the chooser menu.

        CNA_SelImage (struct @{"Image" Link "INCLUDE:intuition/intuition.h/Main" 710} *)
        Selected state @{"Image" Link "INCLUDE:intuition/intuition.h/Main" 710} to be placed to the left of the CNA_Text in
        the chooser menu.

        CNA_ReadOnly (BOOL) (V41.4)
        Item will not be rendered highlighted when selected.

        CNA_Disabled (BOOL) (V41.5)
        Item cannot be selected. No GADGETUP message is generated.

        CNA_Separator (BOOL) (V41.7)
        Separator bar (~~~~). Item cannot be selected. Similar to the
        separator bars in Intuition menus. No GADGETUP message is generated.

@{b}    INPUTS@{ub}
        node - @{"Node" Link "INCLUDE:exec/nodes.h/Main" 21} whose attributes you are changing.
        taglist - @{"Tag" Link "INCLUDE:utility/tagitem.h/Main" 28} list of attributes to change.

@{b}    SEE ALSO@{ub}
        @{"GetChooserNodeAttrsA()" Link "GetChooserNodeAttrsA()"}

@EndNode