MultiChoice
| Release: |
4.6 • 5.0 • 5.1 • 5.2 • 5.3 • 5.4 • 6.0 • 6.1 • 6.2 • 6.3 • 6.4 • 6.5 |
|---|
New to Analytica 5.0
MultiChoice( I, n..., allowNone, separator, returnList, returnSet, labels, selectionLabels, nestUnder )
MultiChoice creates a user-input control that lets you select one, none, some, or All from a list of options, unlike the similar Choice control that lets you select only one or All. It returns the list of selected options. MultiChoice must appear as the top-level of a Definition or in a Table. In a Table, it returns a Set -- a reference to a list of the selected values,
It doesn't work as a user input when the legacy Preference setting Domain acts as self index is on.
Parameters
- «
I»: Either an index identifier, or the keyword Self. When it is an index identifier, the index elements are the possible options. When the keyword Self is used, the possible options are obtained from the Domain. - «n»: The currently selected options, listed by position. For example,
MultiChoice( I, 2, 3, 7 )records that the 2nd, 3rd, and 7th items are selected. - «allowNone»: (Optional) A Boolean that specifies whether the empty selection is allowed. By default, the empty selection is disallowed. To allow the empty selection, use named-parameter syntax, e.g.,
MultiChoice(Self, allowNone:True). When the empty selection is disallowed and «n» contains no valid options, the first item is returned. - «separator»: (Optional) When an element in the list of options matches the value specified here, it displays as a non-selectable separator (a horizontal line between items).
- «returnList»: (Optional) When true, returns a list even when a single item is selected. It that case, the result is a one-element list. This is useful when you define an index with the Multichoice. When «returnList» is false or omitted, «returnSet» is not true, and only a single item is selected, then the single item is returned.
- «returnSet»: (Optional) When true, returns a reference to a list (i.e., a set). When MultiChoice appears in a table cell, this is the default, since it avoids the combination of dimensions from every cell with a multichoice selector.
- «labels»: (Optional) The values that appears on the popup menu (or as the selected value on the control if «selectionLabels» isn't also specified). Use this parameter if you want these to be different from the index values (the result). This should be indexed by «
I», or can be a list when using a Self-choice. These can be (thumbnail) images. - «selectionLabels»: (Optional) The values that you want to appear in the control as the selected value. This should be indexed by «
I», or can be a list when using a Self-choice. Specify this when you want this to be different from «labels». These can be (thumbnail) images. - «nestUnder»: (Optional) A 1-D array indexed by «
I» of submenu names (or Null). When specified, the options are organized hierarchically as submenus. Multiple submenu levels can be separated by the '>' character, for example"California > Santa Clara Co."would place the corresponding item two levels deep.
Examples
In these examples, the index Option contains the possible choices.
Index Option := ['Apple', 'Pear', 'Orange']
A Multichoice with one option selected returns the value of that option:
MultiChoice(Option, 3) → 'Orange'
A Multichoice with multiple options selected returns the values of those options as a list, indexed by the variable containing the Multichoice:
MultiChoice(Option, 1, 3) → ['Apple', 'Orange']
A Multichoice with no options selected returns the first item by default:
MultiChoice(Option) →
Unless you specify optional parameter «allowNone» as True, in which case it lets the user choose no option, and returns an empty list indexed by the variable containing the Multichoice:
MultiChoice(Option, allowNone: True) → []
In this case, the options come from the variable or index's own Domain. Two items are selected.
MultiChoice(Self, 7,12)
This example uses separators, specified as '--', to group the options. Currently 'cherry', 'egg plant' and 'peanut' are selected.
- Index Produce_item :=
['apple', 'banana', 'cherry', '--', 'egg plant', 'lettuce', 'squash', '--', 'almond', 'peanut', 'walnut'] - Domain of Produce := {Copy from index}
Produce_item - Index Produce :=
MultiChoice( Self, 3, 5, 10, separator:'--' )
Using the MultiChoice control
Usually, if you define a variable or index to be a MultiChoice, you will create an input node for that variable. The input node then displays the control on your diagram. The control looks pretty much the same as a Choice control. When a single item is selected, the selected item appears in the control. When multiple items are selected, the control displays «Multiple» or «All», and if no items are selected, it displays «None».
When you click on the control, the list of options pops up. Keyboard actions include:
- [ESC] key: Cancels the current input and closes the popup, restoring the original selection.
- [Enter] key: Closes the popup, accepting the current selections.
- [Up] and [Down] arrows: Moves the highlighted selection (no impact on which items are selected).
- [Space] key: Toggles the highlighted selection. Leaves popup open.
- [Ctrl+A]: Selects all, or if all options are already selected, deselects all (but leaves one selected if «allowNone» is not on).
Mouse actions include:
- Click on item: Toggles item. Leaves popup open.
- Click outside the control: Accepts selections and closes popup.
- Click - drag - release: Select or deselect several items. The item where the mouse down occurs determines whether the drag selects or deselects.
When «allowNone» is not on, the actions that toggle the selection state will not deselect the last selected item.
Handles
When the options are handles to variables (or other objects), it shows the Title or Identifier of each object in the menu (as with Choice) and returns the handle, not the value of the variable.
Enable comment auto-refresher