Difference between revisions of "AskMsgText"
(added example) |
m (→See Also) |
||
| (15 intermediate revisions by 5 users not shown) | |||
| Line 1: | Line 1: | ||
[[category:User-interface functions]] | [[category:User-interface functions]] | ||
| + | [[Category:Doc Status C]] <!-- For Lumina use, do not change --> | ||
| + | {{ReleaseBar}} | ||
| − | ( | + | == AskMsgText(question, ''title, maxText, default, password{{Release|5.4||, checkboxText, initialCheck}}{{Release|6.1||, multiline}}'') == |
| − | [[ | + | A [[Dialog Functions|Dialog Function]] that creates a dialog box with «title», «question» and a text box. |
| + | It returns the text entered by the user into the text box, or the default if none. For example: | ||
| − | + | :<code>AskMsgText("Enter your model access key", title: "License Entry", maxText: 15)</code> | |
| − | + | :[[image:AskMsgTextDialog.jpg]] | |
| − | + | The box displays '''OK''' and '''Cancel''' buttons. Pressing '''Cancel''' causes the current computation to abort. | |
| − | The message box appears only when this function is evaluated. Since Analytica caches results once they are computed, if you embed this in a variable, you will not see the question every time you view the result. To trigger the question again, you must change something upstream that the variable depends on, so the result is invalidated. If you place it inside a button | + | The message box appears only when this function is evaluated. Since Analytica caches results once they are computed, if you embed this in a variable, you will not see the question every time you view the result. To trigger the question again, you must change something upstream that the variable depends on, so the result is invalidated. If you place it inside an [[OnClick]] in a button or [[OnChange]] attribute in a variable, it shows the message box every time the button is pressed. |
| − | + | === Optional parameters === | |
| − | + | «title»: A title for the dialog box. (Default: empty.) | |
| − | AskMsgText( "Enter | + | «default»: The default text shown in the message box. (Default: empty.) {{Release|6.1||If the default has multiple lines -- i.e., one or more [[Chr]](13) characters -- the text box will be placed in multiline entry mode (unless «multiline» is specified as 0). }} |
| + | |||
| + | «maxText»: The maximum number of characters accepted. (Default: unlimited) | ||
| + | |||
| + | «password»: If set to true, it obscures the characters typed, showing asterisks rather than the typed characters. | ||
| + | |||
| + | {{Release|5.4||«checkboxText»: If specified, shows this text with a checkbox. (Default: empty and it does not show the checkbox.) | ||
| + | (''New to [[Analytica 5.4]]'') When you specify «checkboxText», it returns two return values: The text from the text box, and the Boolean state of the checkbox. To capture both, use for example | ||
| + | ::<code>[[Local]] (enteredText, checked) :{{=}} [[AskMsgText]]("Enter the plant name", checkboxText:"Is a co-generation facility");</code> | ||
| + | |||
| + | «initialCheck»: Initial state (true or false) of checkbox. (Default: False i.e. Off). | ||
| + | }} | ||
| + | |||
| + | {{Release|6.1||«multiline»: The number of lines for the text box. Forces it into multi-line entry mode. A value of 0 forces single-line entry mode even if the «default» text has multiple lines.}} | ||
| + | |||
| + | === From ADE === | ||
| + | |||
| + | When evaluated in [[ADE|the Analytica Decision Engine (ADE)]], it calls [[IAdeUICallbacks::AskMsgText]](...). 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]]( ). If it has not registered a callback, then «default» is returned. | ||
| + | |||
| + | == See Also == | ||
| + | * [[Dialog Functions]] | ||
| + | * [[MsgBox]] | ||
| + | * [[AskMsgNumber]] | ||
| + | * [[AskMsgChoice]] | ||
| + | * [[Creating Interfaces for End Users]] | ||
Latest revision as of 17:16, 19 March 2022
| 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 |
|---|
AskMsgText(question, title, maxText, default, password, checkboxText, initialCheck, multiline)
A Dialog Function that creates a dialog box with «title», «question» and a text box. It returns the text entered by the user into the text box, or the default if none. For example:
AskMsgText("Enter your model access key", title: "License Entry", maxText: 15)
The box displays OK and Cancel buttons. Pressing Cancel causes the current computation to abort.
The message box appears only when this function is evaluated. Since Analytica caches results once they are computed, if you embed this in a variable, you will not see the question every time you view the result. To trigger the question again, you must change something upstream that the variable depends on, so the result is invalidated. If you place it inside an OnClick in a button or OnChange attribute in a variable, it shows the message box every time the button is pressed.
Optional parameters
«title»: A title for the dialog box. (Default: empty.)
«default»: The default text shown in the message box. (Default: empty.) If the default has multiple lines -- i.e., one or more Chr(13) characters -- the text box will be placed in multiline entry mode (unless «multiline» is specified as 0).
«maxText»: The maximum number of characters accepted. (Default: unlimited)
«password»: If set to true, it obscures the characters typed, showing asterisks rather than the typed characters.
«checkboxText»: If specified, shows this text with a checkbox. (Default: empty and it does not show the checkbox.) (New to Analytica 5.4) When you specify «checkboxText», it returns two return values: The text from the text box, and the Boolean state of the checkbox. To capture both, use for example
Local (enteredText, checked) := AskMsgText("Enter the plant name", checkboxText:"Is a co-generation facility");
«initialCheck»: Initial state (true or false) of checkbox. (Default: False i.e. Off).
«multiline»: The number of lines for the text box. Forces it into multi-line entry mode. A value of 0 forces single-line entry mode even if the «default» text has multiple lines.
From ADE
When evaluated in the Analytica Decision Engine (ADE), it calls IAdeUICallbacks::AskMsgText(...). 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( ). If it has not registered a callback, then «default» is returned.
Enable comment auto-refresher