MultiChoice
New to Analytica 5.0
MultiChoice( I, n..., allowNone, separator )
MultiChoice is used to create a user-input control that allows multiple options to be selected, similar to a Choice. It evaluates to a list of the selected items.
To act as an input control, MultiChoice must appear at the top-level of a Definition. It cannot be used as a control in a Table, and cannot be used 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).
Examples
In this example, the possible choices are in the index Option. Because «allowNone» is not specified the empty selection is prohibited, but since «n» is also not specified, the first item is implicitly selected.
MultiChoice(Option)
Next, nothing is selected:
MultiChoice(Option, allowNone:true)
In this example, a single item, the third option, is selected.
MultiChoice(Option, 3)
Here, the first five items are selected. The empty selection is permitted.
MultiChoice(Option, 1,2,3,4,5, allowNone:true)
In this case, the options come from the variable or index's own Domain. Two items are selected.
MultiChoice(Self, 7,12)
In the next example, separators are used 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, the Title or Identifier of the object pointed to is shown in the control (as is also the case with a Choice) and the value returned is always the handle itself, never the value of the variable pointed to.
Enable comment auto-refresher