chooser.gadget Reference

Comprehensive function reference for chooser.gadget, synthesised from the AmigaOS NDK 3.2 Release 4 (Autodocs/chooser).

This page documents 6 functions of chooser.gadget. Each function entry follows the canonical autodoc format. struct Name, union Name, enum Name are clickable links to the type definition in the types reference.

Function index

chooser_gc()

**chooser_gc -- A pop-up/drop-down small list selection gadget.

SUPERCLASS
    gadgetclass

REQUIRES
    bevel.image, glyph.image

DESCRIPTION
    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 HelpTest.

     > Cycle2Menu style activation.

     > Supports tab-cycle activation and keyboard control.

METHODS
    OM_NEW -- Create the chooser gadget.  Passed to superclass.

    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 -- Renders the gadget imagery.  Overrides the superclass.

    GM_HITTEST -- Determines if mouse is within the gadget rectangle.
        Overrrides the superclass.

    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.

ATTRIBUTES
    GA_ID (WORD)
        Applicability is (OM_NEW, OM_SET, OM_UPDATE, 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, OM_UPDATE, OM_GET)

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

        Defaults to FALSE.

        Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)

    GA_TextAttr (struct TextAttr *)
        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.

        Applicability is (OM_NEW, 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, 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, OM_UPDATE, OM_GET)

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

        Defaults to NULL.

        Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)

    CHOOSER_Labels (struct List *)
        Exec List of labels.  Each node must be allocated with the
        AllocChooserNodeA() function.

        Applicability is (OM_NEW, 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 options[] = {                        
           "Coffee", "Tea", ~0L, "Coke", "Beer", 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, 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, OM_UPDATE, OM_GET)

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

        Applicability is (OM_NEW, OM_SET, OM_UPDATE, 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, 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, OM_UPDATE, OM_GET)**

AllocChooserNodeA()

AllocChooserNodeA -- Allocate a chooser node.

Synopsis

struct Node * AllocChooserNode(Tag, ...)
node = AllocChooserNode(columns, Tag, ...)
struct Node * AllocChooserNodeA(struct TagItem *)
node = AllocChooserNodeA(taglist)

Function

    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.

Inputs

    taglist - Attributes for the node, passed onto SetChooserNodeAttrsA()

.

RESULT
    node - A node that can be added into the Exec list of labels for
        a chooser gadget.

See also

    FreeChooserNode(), SetChooserNodeAttrsA()

CHOOSER_GetClass()

CHOOSER_GetClass -- Gets the pointer to the chooser class.

Synopsis

chooser_class = CHOOSER_GetClass();
D0

Class * CHOOSER_GetClass(VOID);

Function

    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().  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.

Inputs

    Nothing.

RESULT
    chooser_class - Pointer to the chooser gadget class.

FreeChooserNode()

FreeChooserNode -- Free a chooser node.

Synopsis

VOID FreeChooserNode(struct Node *)
FreeChooserNode(node)

Function

    Frees a chooser node allocated with AllocChooserNodeA().

Inputs

    node - The node to free.

See also

    AllocChooserNodeA()

GetChooserNodeAttrsA()

GetChooserNodeAttrsA -- Get attributes of a chooser node.

Synopsis

VOID GetChooserNodeAttrs(struct Node *, Tag, ...)
GetChooserNodeAttrs(node, firsttag, ...)
VOID GetChooserNodeAttrsA(struct Node *, struct TagItem *)
GetChooserNodeAttrsA(node, taglist)

Function

    The chooser uses a private node structure and all attributes
    are hidden, and must therefore be accessed with this function.

Inputs

    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.

See also

    SetChooserNodeAttrsA()

SetChooserNodeAttrsA()

SetChooserNodeAttrsA -- Set attributes of a chooser node.

Synopsis

VOID SetChooserNodeAttrs(struct Node *, Tag, ...)
SetChooserNodeAttrs(node, firsttag, ...)
VOID SetChooserNodeAttrsA(struct Node *, struct TagItem *)
SetChooserNodeAttrsA(node, taglist)

Function

    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.

TAGS
    CNA_Text (STRPTR)
    Text string to appear as a line in the chooser menu. This tag
    must be supplied for the node.

    CNA_Image (struct Image *)
    Image to be placed to the left of the CNA_Text in the chooser menu.

    CNA_SelImage (struct Image *)
    Selected state Image 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.

Inputs

    node - Node whose attributes you are changing.
    taglist - Tag list of attributes to change.

See also

    GetChooserNodeAttrsA()