TABLE OF CONTENTS chooser.gadget/--datasheet-- chooser.gadget/--styleguide-- chooser.gadget/AllocChooserNodeA chooser.gadget/CHOOSER_GetClass chooser.gadget/FreeChooserNode chooser.gadget/GetChooserNodeAttrsA chooser.gadget/SetChooserNodeAttrsA chooser.gadget/--datasheet-- chooser.gadget/--datasheet-- NAME chooser.gadget -- Pop-up/drop-down small list selection gadget. SUPERCLASS gadgetclass REQUIRES bevel.image, glyph.image, penmap.image, sysiclass 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 a menu displaying the items in the list is displayed. The chooser operates in either of two modes: pop-up or 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. METHODS OM_NEW -- Create the chooser gadget. Passed to superclass. OM_SET -- Set object attributes. Passed to superclass first. OM_DISPOSE -- Delete the chooser menu. 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. GM_GOACTIVE -- Handles activation and pops up the chooser menu. GM_HANDLEINPUT -- Handles input events once active. GM_GOINACTIVE -- Closes the chooser menu. GM_DOMAIN -- Calculates mix/max sizes. GM_HELPTEST -- Determine if gadget help was hit. GM_LAYOUT -- Calculate relative gadget coordinates. GM_EXTENT -- Reports gadget rendering extent. GM_CLIPRECT -- Installs ClipRect for virtual group support. All other methods are passed to the superclass. ATTRIBUTES GA_ID (uint16) Unique ID number for the gadget. Defaults to 0. Applicability is (OM_NEW, OM_SET, OM_GET, OM_NOTIFY) GA_Disabled (BOOL) Set to TRUE to disable gadget, FALSE otherwise. Defaults to FALSE. Applicability is (OM_NEW, OM_SET, OM_GET) GA_ReadOnly (BOOL) (V53.19) Set to TRUE to make the gadget read-only. Defaults to FALSE. Applicability is (OM_NEW, OM_SET) GA_TextAttr (struct TextAttr *) Font to use for the gadget text. Defaults to the screen's font. Applicability is (OM_NEW, OM_SET, OM_GET) GA_BackFill (struct Hook *) A layer backfill hook to provide a more complex background pattern. See InstallLayerHook() for more details about the backfill hook. Defaults to NULL. Applicability is (OM_NEW, OM_SET) GA_Underscore (uint8) Underscore/escape character for keyboard shortcuts. Defaults to the '_' character. Applicability is (OM_NEW, OM_SET, OM_GET) GA_Image (struct Image *) Image to appear within the select box when in drop-down mode. GA_Text overrides this attribute. Defaults to NULL. Applicability is (OM_NEW, OM_SET, OM_GET) GA_HintInfo (CONST_STRPTR) Specify the text to use as the hint info for this gadget. You can change this attribute at any time, and it will over- ride any text specified in the windows HintInfo array. See window.class autodoc for more information. Defaults to NULL. Applicability is (OM_NEW, OM_SET). GA_Text (CONST_STRPTR) CHOOSER_Title (CONST_STRPTR) Title to appear within the select box when in drop-down mode. Defaults to NULL. Applicability is (OM_NEW, OM_SET, OM_GET) CHOOSER_PopUp (BOOL) Sets the chooser to work in pop-up 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_GET) CHOOSER_DropDown (BOOL) Sets the chooser to work in drop-down 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_GET) CHOOSER_Hidden (BOOL) (V41.101) If set, the chooser will not render its main body and you may then use the WM_ACTIVATEGADGET method or similar to activate the gadget and make the chooser appear. Hidden choosers are handled in drop-down mode only. Note that when using a hidden chooser the only way to communicate with the chooser is via IDCMP_IDCMPUPDATE. Defaults to FALSE. Applicability is (OM_NEW, OM_SET, OM_GET) CHOOSER_Labels (struct List *) 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 the list. For example: CONST_STRPTR options[] = { "Coffee", "Tea", ~0L, "Coke", "Beer", NULL }; The array can be allocated on the stack. However, the text won't be copied and must stay valid for the lifetime of the chooser object. Applicability is (OM_NEW, OM_SET) CHOOSER_Justification (int16) (V45) Specifies the label alignment: CHJ_LEFT, CHJ_CENTER or CHJ_RIGHT. Defaults to CHJ_LEFT. Applicability is (OM_NEW, OM_SET) CHOOSER_ImageJustification (int16) (V51) Specifies the item image alignment: CHJ_LEFT, CHJ_CENTER or CHJ_RIGHT. Defaults to CHJ_LEFT. Applicability is (OM_NEW, OM_SET) CHOOSER_MaxLabels (int16) 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_GET) CHOOSER_Offset (int16) (V41) Add a fixed value offset to the CHOOSER_Selected value for notification methods. This is useful in connecting a Chooser with item IDs 0 thru 11 to a Calendar's month which is 1 thru 12. In that situation, a CHOOSER_Offset of 1 would be used to match the starting offsets of the respective tags. Defaults to 0. Applicability is (OM_NEW, OM_SET) CHOOSER_Selected (int16) Index of selected label in the list. Applicability is (OM_NEW, OM_SET, OM_GET, OM_UPDATE, OM_NOTIFY) CHOOSER_SelectedNode (struct Node *) (V52.5) Gets the selected node by node pointer or NULL if nothing has been selected. This attribute has had OM_NOTIFY support since V53.7. This attribute is now settable since V53.15. Applicability is (OM_GET, OM_SET, OM_NOTIFY) CHOOSER_Width (int16) The width of the chooser menu. Defaults to the width of the gadget select box. Applicability is (OM_NEW, OM_SET, OM_GET) CHOOSER_AutoFit (BOOL) Set the width of the chooser menu so that it fits the widest label in the list. This tag is obsolete as of V51.2 and does absolutely nothing. Defaults to FALSE. Applicability is (OM_NEW, OM_SET, OM_GET) chooser.gadget/--styleguide-- chooser.gadget/--styleguide-- CHOOSER STYLE The chooser has two very distinct modes of operation, drop-down and pop-up. It is important to understand the differences between these two modes and to use the proper mode in the proper context. POP-UP CHOOSERS 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. DROP-DOWN CHOOSERS 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 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). chooser.gadget/AllocChooserNodeA chooser.gadget/AllocChooserNodeA NAME AllocChooserNodeA -- Allocate a chooser node. SYNOPSIS struct Node *node = AllocChooserNodeA(struct TagItem *taglist); struct Node *node = AllocChooserNode(Tag tag1, ...); 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 to SetChooserNodeAttrsA(). RESULT node - A node that can be added into the list of labels or NULL on error. SEE ALSO FreeChooserNode(), SetChooserNodeAttrsA() chooser.gadget/CHOOSER_GetClass chooser.gadget/CHOOSER_GetClass NAME CHOOSER_GetClass -- Gets pointer to the chooser class. SYNOPSIS Class * class = CHOOSER_GetClass(); FUNCTION This function is deprecated as of V52. Use the "chooser.gadget" public class ID instead. RESULT class - Pointer to the chooser class. chooser.gadget/FreeChooserNode chooser.gadget/FreeChooserNode NAME FreeChooserNode -- Free a chooser node. SYNOPSIS void FreeChooserNode(struct Node *node); FUNCTION Frees a chooser node allocated with AllocChooserNodeA(). INPUTS node - The node to free. Safe to call with a NULL pointer since V53.9. NOTES ALWAYS ensure that you Remove() the node before calling this function to save a potential corruption of the list. SEE ALSO AllocChooserNodeA() chooser.gadget/GetChooserNodeAttrsA chooser.gadget/GetChooserNodeAttrsA NAME GetChooserNodeAttrsA -- Get attributes of a chooser node. SYNOPSIS void GetChooserNodeAttrsA(struct Node *node, struct TagItem *taglist); void GetChooserNodeAttrs(struct Node *node, Tag tag1, ...); 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 about. 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. NOTES Do not forget that the ti_Data pointer must point to a uint32 sized storage location no matter what type you are getting. SEE ALSO SetChooserNodeAttrsA() chooser.gadget/SetChooserNodeAttrsA chooser.gadget/SetChooserNodeAttrsA NAME SetChooserNodeAttrsA -- Set attributes of a chooser node. SYNOPSIS void SetChooserNodeAttrsA(struct Node *node, struct TagItem *taglist); void SetChooserNodeAttrs(struct Node *node, Tag tag1, ...); 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_CopyText (BOOL) (V53.11) Specifies that you want the CNA_Text copied to an internal buffer by Chooser. This tag must precede CNA_Text in the tag list. For example, ... CNA_CopyText, TRUE, CNA_Text, "Amiga", // Text will be copied ... Defaults to FALSE. CNA_Text (CONST_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_UserData (APTR) Arbitrary user data for this node. 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. CNA_FGPen (WORD) (V51.2) Item text color. CNA_BGPen (WORD) (V51.2) Item background color. INPUTS node - Node whose attributes you are changing. taglist - Tag list of attributes to change. SEE ALSO GetChooserNodeAttrsA()