PROMPT() Function - Prompt For String Value
Syntax
PROMPT(message{,default{,title{,expr}}}{,MODE="options"}{,TIM=int}{,ERR=lineref})
Description
In BBj 22.13 and higher, the PROMPT() function prompts the user to type a value into a dialog box, then returns that string to the application. If the user cancels the dialog by clicking Cancel or pressing Esc, it returns "::CANCEL::", like the FILEOPEN() and FILESAVE() functions.
Parameters
|
Parameter |
Description |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
message |
Dialog box message text. Lines are automatically broken at the right edge of the dialog box. To force a line break, insert a line-feed character ($0A$) before the first character of a line. In BBj 23.03 and higher, set STBL("!PROMPT_SPLIT",str(integer)) to break a long message text into chunks of the specified maximum number of characters. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
default |
Default value. If not specified, the default value is "". |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
title |
Dialog box title text. If not specified, the program name is used as the title. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
expr |
Numeric expression that adds an optional icon to the dialog.
MDI (BBj 23.05 and higher)
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| ERR=lineref | Branch to be taken if an error occurs during execution. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| MODE="STYLE=name" | An optional style name, equivalent to BBjControl::addStyle. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| MODE="X=int,Y=int" | Displays the dialog at a specific screen location. Either or both may be specified. By default, the dialog is centered. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| MODE="W=int,H=int" | Specifies the maximum width and height of the dialog window. Either or both may be specified. The dialog size is also limited by the size of the screen or browser. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| MODE="SPLIT=int" | In BBj 23.03 and higher, the optional SPLIT value specifies the maximum number of characters to show on a line before inserting a line break. This value overrides the STBL("!PROMPT_SPLIT") setting. The default is 100 characters. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| MODE="attr=value" |  The mode string can specify selected DWC component attributes (e.g. "theme=primary, blurred=true"). DWC button attributes can be applied to the OK and Cancel buttons using the format "button-0-theme=success, button-1-theme=danger".
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| MODE="input-type=type" |
In BBj 23.03 and higher, the input-type attribute can specify an alternative input type. If a specified type is unsupported in the current client, the default "text" is used.
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| MODE="property=value" | The mode string can specify arbitrary DWC properties (e.g. "theme=info"). Themes can also be applied to individual buttons (e.g. "button-0-theme=success, button-1-theme=danger"). |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
MODE="ICON=imagefile MODE="ICON=url" |
The optional ICON value specifies a custom icon image, either an image file or a URL that will be reachable from the client (e.g. a DATA URL). | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| MODE="ICONWIDTH=int" | The optional ICONWIDTH value specifies an integer width to scale the specified ICON. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| MODE="ICONHEIGHT=int" | The optional ICONHEIGHT value specifies an integer height to scale the specified ICON. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| TIM=int | The optional TIM=int option will cause the PROMPT dialog to timeout, returning the default value, if the user does not make a selection within int seconds. TIM=0 is equivalent to not specifying the TIM=int option at all; it will not timeout. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| ERR=lineref | Branch to be taken if an error occurs during execution. |
CSS
The visual appearance of BUI controls is defined using CSS (cascading style sheets) rules. Easily change the default colors, border, and other settings by customizing these rules, all without changing any application code. See CSS API for a high-level overview of BUI CSS.
Here is a sample prompt dialog:
name$ = prompt("Enter your name","John Doe","Name",64)
The PROMPT() function defines the following style names:
| .BBjPrompt | the top level of the dialog window |
| .BBjPrompt-title | the title bar |
| .BBjPrompt-panel | the body area |
| .BBjPrompt-message-panel | a horizontal panel that contains the icon and message |
| .BBjPrompt-icon | the icon |
| .BBjPrompt-icon-error | stop sign / error icon (16) |
| .BBjPrompt-icon-question | question icon (32) |
| .BBjPrompt-icon-warning | warning / exclamation icon (48) |
| .BBjPrompt-icon-info | info icon (64) |
| .BBjPrompt-message | the message |
| .BBjPrompt-input | the text input field |
| .BBjPrompt-button-panel | a horizontal panel that contains the buttons |
| .BBjPrompt-button | an individual button |
With the default CSS styles, the prompt looks like this:
And with the CSS file below, the same prompt looks like this:
|
Examples
Example 1
The following creates a dialog with a prompt value of "Enter your name", a title of the program name, an input field for the user to type a name, an OK button and a Cancel button:
let name$ = prompt("Enter your name")
Example 2
The following creates a dialog with a prompt value of "Enter your name", a title of the program name, an input field for the user to type a name, an OK button and a Cancel button. The input field is initialized to the specified default value of "John Doe":
let name$ = prompt("Enter your name","John Doe")
Example 3
The following creates a dialog with a prompt value of "Enter your name", a title of "Customer Name", an input field for the user to type a name, an OK button and a Cancel button. The input field is initialized to the specified default value of "John Doe":
let name$ = prompt("Enter your name","John Doe","Customer Name")
Example 4
The following creates a dialog with an information icon, a prompt value of "Enter your name", a title of "Customer Name", an input field for the user to type a name, an OK button and a Cancel button. The input field is initialized to the specified default value of "John Doe":
let name$ = prompt("Enter your name","John Doe","Customer Name",64)
Example 5
The following creates a dialog with a prompt value of "Enter your name", a title of "Customer Name", an input field for the user to type a name, an OK button and a Cancel button. The input field is initialized to the specified default value of "John Doe". If the user doesn't click OK within 10 seconds, the current value of the input field is returned.
let name$ = prompt("Enter your name","John Doe","Customer Name",TIM=10)
Example 6
In BBj 23.03 and higher, the following creates a dialog with a prompt value of "Enter your password", a title of the program name, a password input field for the user to type a password, an OK button and a Cancel button:
let password$ = prompt("Enter your password",mode="input-type=password")
Example 7
The prompt function works very much like the msgbox function, and accepts some of the same options. The following test program can be used to interactively test various options with both functions.
|
See Also
Alphabetic Listing - Functions