Difference between revisions of "AskMsgChoice"
(encouragement of community design) |
m |
||
| (8 intermediate revisions by 2 users not shown) | |||
| Line 1: | Line 1: | ||
[[Category:User-interface functions]] | [[Category:User-interface functions]] | ||
| − | |||
| − | '' | + | == AskMsgChoice(question, ''title'', optionList'', default, showAll, comboBox'') == |
| + | A [[Dialog Functions|Dialog Function]] that creates a dialog box asking the user to select from a drop-down of possible choices. | ||
| − | + | Parameters: | |
| + | ;<code>«question»</code> : Text that appears in the dialog body itself, above the choice pulldown. | ||
| + | ;<code>«title»</code>: The caption for the dialog. | ||
| + | ;<code>«optionList»</code>: An unindexed list, or a 1-D array, containing the possible options. It can be an expression that computes such a list. Numbers are coerced to text using the number format for the variable currently being evaluated. | ||
| + | ;<code>«default»</code>: (optional): The item from the choice list that should be selected initially. | ||
| + | ;<code>«showAll»</code> : (optional boolean, default: false): Indicates whether the "All" option should appear on the dropdown. | ||
| + | ;<code>«comboBox»</code> : (optional boolean, default:false): When this is true, a ComboBox is displayed. The «optionList» is a dropdown with suggested values, but any value may be typed. When true, «default» does not have to be in the «optionList». | ||
| + | |||
| + | The result returned is the selected label from «optionList», unless "All" is selected, in which case the result is the same value supplied as «optionList». | ||
| + | |||
| + | The dialog includes an '''OK''' and a '''Cancel''' button. When '''Cancel''' is pressed, the current in-process computation is aborted. | ||
| − | When | + | When called from [[ADE]], this function does not present any UI, and simply returns the default selection. |
| − | + | When «comboBox» is not specified, or is false, a straight pull-down is displayed. In this case, «default» must be in «optionList» or be the textual value <code>"All"</code>, or an error is issued. When «default» is omitted, it defaults to "All" when «showAll» is true, or to the first selection otherwise. | |
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | The | + | When «comboBox» is true, a combo box is displayed, which contains both a single-line text entry field and a pulldown. The pulldown serves as list of suggestions, but any (single-line) of text may be entered. When an item on the pulldown is selected, its value appears in the text field. The «default» value does NOT need to be in «optionList». When omitted, "All" is selected if «showAll» is true, otherwise the initial field is blank. |
| − | + | When «default» is the textual value <code>"All"</code>, and «showAll» is true, then the "All" option is selected ''unless'' the textual value <code>"All"</code> exists in «optionList». In that case, the item is selected rather than the "All" option. This special case creates a special case behavior, which is undesirable, but it also is intuitive. | |
| − | + | == Examples == | |
| + | :<code>AskMsgChoice("What is your favorite color?", "Select color", ["Black", "Blue", "Brown", "Cyan", "Green", "Orange", "Red", "White", "Yellow"], default: "Green", comboBox: true)</code> | ||
| − | + | User can select a color or type something else. | |
| − | + | :[[Image:AskMsgChoice-combo.png]] | |
| − | + | :<code>AskMsgChoice("What is your favorite color?", "Select color", ["Black", "Blue", "Brown", "Cyan", "Green", "Orange", "Red", "White", "Yellow"], default: "Green")</code> | |
| − | + | User selects from the pulldown of possible choices. | |
| − | + | :[[Image:AskMsgChoice-pulldown.png]] | |
| − | = | + | == From ADE == |
| + | When evaluated in [[ADE|the Analytica Decision Engine (ADE)]], it calls [[IAdeUICallbacks::AskMsgChoice]](...). From within that callback, the parent application can display a dialog, collect input from the end-user, and return that as the return value. To receive the callback, the parent application must have previously registered the callback with ADE using [[CAEngine::SetCallbackObject]]( ). | ||
| − | + | ==History== | |
| − | + | This function was introduced in [[Analytica 4.5]]. | |
| − | + | The ADE callback was introduced in [[Analytica 4.6|ADE 4.6]]. | |
| + | == See Also == | ||
| + | * [[Dialog Functions]] | ||
* [[AskMsgNumber]] | * [[AskMsgNumber]] | ||
* [[AskMsgText]] | * [[AskMsgText]] | ||
* [[Choice]] | * [[Choice]] | ||
* [[MsgBox]] | * [[MsgBox]] | ||
| + | * [[Creating Interfaces for End Users]] | ||
Latest revision as of 19:56, 11 March 2022
AskMsgChoice(question, title, optionList, default, showAll, comboBox)
A Dialog Function that creates a dialog box asking the user to select from a drop-down of possible choices.
Parameters:
«question»- Text that appears in the dialog body itself, above the choice pulldown.
«title»- The caption for the dialog.
«optionList»- An unindexed list, or a 1-D array, containing the possible options. It can be an expression that computes such a list. Numbers are coerced to text using the number format for the variable currently being evaluated.
«default»- (optional): The item from the choice list that should be selected initially.
«showAll»- (optional boolean, default: false): Indicates whether the "All" option should appear on the dropdown.
«comboBox»- (optional boolean, default:false): When this is true, a ComboBox is displayed. The «optionList» is a dropdown with suggested values, but any value may be typed. When true, «default» does not have to be in the «optionList».
The result returned is the selected label from «optionList», unless "All" is selected, in which case the result is the same value supplied as «optionList».
The dialog includes an OK and a Cancel button. When Cancel is pressed, the current in-process computation is aborted.
When called from ADE, this function does not present any UI, and simply returns the default selection.
When «comboBox» is not specified, or is false, a straight pull-down is displayed. In this case, «default» must be in «optionList» or be the textual value "All", or an error is issued. When «default» is omitted, it defaults to "All" when «showAll» is true, or to the first selection otherwise.
When «comboBox» is true, a combo box is displayed, which contains both a single-line text entry field and a pulldown. The pulldown serves as list of suggestions, but any (single-line) of text may be entered. When an item on the pulldown is selected, its value appears in the text field. The «default» value does NOT need to be in «optionList». When omitted, "All" is selected if «showAll» is true, otherwise the initial field is blank.
When «default» is the textual value "All", and «showAll» is true, then the "All" option is selected unless the textual value "All" exists in «optionList». In that case, the item is selected rather than the "All" option. This special case creates a special case behavior, which is undesirable, but it also is intuitive.
Examples
AskMsgChoice("What is your favorite color?", "Select color", ["Black", "Blue", "Brown", "Cyan", "Green", "Orange", "Red", "White", "Yellow"], default: "Green", comboBox: true)
User can select a color or type something else.
AskMsgChoice("What is your favorite color?", "Select color", ["Black", "Blue", "Brown", "Cyan", "Green", "Orange", "Red", "White", "Yellow"], default: "Green")
User selects from the pulldown of possible choices.
From ADE
When evaluated in the Analytica Decision Engine (ADE), it calls IAdeUICallbacks::AskMsgChoice(...). From within that callback, the parent application can display a dialog, collect input from the end-user, and return that as the return value. To receive the callback, the parent application must have previously registered the callback with ADE using CAEngine::SetCallbackObject( ).
History
This function was introduced in Analytica 4.5.
The ADE callback was introduced in ADE 4.6.
See Also
Comments
Enable comment auto-refresher