chooser.gadget
A pop-up/drop-down small list selection gadget.FUNCTIONS
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:
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.
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 *)
-
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. Example:
STRPTR options[] = {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 object.
};"Coffee", "Tea", ~0L, "Coke", "Beer", NULL
Applicability is (OM_NEW, OM_SET, OM_UPDATE) (V45)
- CHOOSER_Justification (WORD)
-
Specifies the label alignment (CHJ_LEFT, CHJ_CENTER, CHJ_RIGHT).
Defaults to CHJ_LEFT.
Applicability is (OM_NEW, OM_SET) (V45)
- 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)
NOTES
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.
Pop up - A pop-up is generally used for setting an application mode or state,
Pop up - 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 - 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).
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).