MSGBOX() Function
For this topic's original documentation, see the MSGBOX() Function - Create Message Box Dialog.
BBj-Specific Information
Syntax
MSGBOX(str1{,expr{,str2{,button1{,button2{,button3}}}}}{,MODE="options"}{,TIM=int}{,ERR=lineref})
In BBj, the MSGBOX() function places a dialog in the center of the SYSGUI
window. In Visual PRO/5, it places the dialog in the center of the screen.
The system modal flag 262144 is not available in BBj. All message boxes are application modal.
| Parameter | Description | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| str1 | Dialog box message text or HTML. 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 14.00 and higher, set STBL("!MSGBOX_SPLIT",str(integer)) to break a long message text into chunks of the specified maximum number of characters. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| expr |
Numeric expression that identifies the dialog's buttons, icons, default button, and modal setting. The values are additive. For example, the following expression indicates that the dialog has OK and Cancel buttons and an exclamation mark icon. The Cancel button is the default: (1+48+256+0) Buttons
Icon
Default Button
Render HTML (BBj 11.00 and higher)
Modal Value
By default, MSGBOX(), FILEOPEN() and FILESAVE() dialogues are modal over the windows of the current interpreter. Setting the GROUP_MODAL_DIALOGS!COMPAT setting to TRUE will cause dialogs to be modal over all client windows. MDI (BBj 23.05 and higher)
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| str2 | Dialog box title text. If this parameter is omitted, the program name is used as the title. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| button1 | Custom text or HTML for the first button. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| button2 | Custom text or HTML for the second button. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| button3 | Custom text or HTML for the third button. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| ERR=lineref | Branch to be taken if an error occurs during execution. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| MODE="STYLE=name" | In BBj 14.00 and higher, this sets a MSGBOX style name, equivalent to BBjControl::addStyle. This can be used to apply custom CSS styling to a BUI MSGBOX. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| MODE="X=int,Y=int" | In BBj 15.00 and higher, the optional X and Y values display the dialog at a specific screen location. Either or both may be specified. By default, the MSGBOX dialog is centered. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| MODE="W=int,H=int" |
In BBj 19.10 and higher, the optional W and H values specify the maximum width and height of the dialog window. Either or both may be specified. The MSGBOX dialog size is also limited by the size of the screen or browser. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| MODE="SPLIT=int" | In BBj 20.11 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("!MSGBOX_SPLIT") setting. The default is 100 characters. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| MODE="attr=value" |  In BBj 21.10 and higher, the mode string can specify selected DWC component attributes (e.g. "theme=primary,blurred=true"). DWC button attributes can be applied to selected buttons using the format "button-0-theme=success, button-1-theme=danger". |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
MODE="ICON=imagefile" MODE="ICON=url" |
In BBj 22.0 and higher, 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" | In BBj 22.00 and higher, the optional ICONWIDTH value specifies an integer width to scale the specified ICON. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| MODE="ICONHEIGHT=int" | In BBj 22.00 and higher, the optional ICONHEIGHT value specifies an integer height to scale the specified ICON. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| TIM=int |
In BBj 17.00 and higher, the optional TIM=int option will cause the MSGBOX to timeout, returning a value of -1, 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. |
Returned Values
For function types 0 through 5, the value returned by MSGBOX() identifies which button the user selects, as follows:
| Value | BBjSysGui Constant | Button Selected |
|---|---|---|
| 1 | MSGBOX_RETURN_OK | OK |
| 2 | MSGBOX_RETURN_CANCEL | Cancel |
| 3 | MSGBOX_RETURN_ABORT | Abort |
| 4 | MSGBOX_RETURN_RETRY | Retry |
| 5 | MSGBOX_RETURN_IGNORE | Ignore |
| 6 | MSGBOX_RETURN_YES | Yes |
| 7 | MSGBOX_RETURN_NO | No |
For a custom message box, function type 7, the value returned corresponds to the button number, as follows:
| Value | Button Selected |
|---|---|
| 1 | First Button |
| 2 | Second Button |
| 3 | Third Button |
For function type 1 (OK and Cancel), 3 (Yes, No and Cancel) or 5 (Retry and Cancel), if the user closes the message box by hitting the Esc key or by clicking the close box, the effect is the same as if the user clicked the Cancel button; the return value is 2.
For function type 0 (OK) or 7 (Custom), if the user closes the message box by hitting the Esc key or by clicking the close box, the return value is 0 to indicate that no selection was made.
For function type 2 (Abort, Retry, Ignore) or 4 (Yes, No), the user must select one of the buttons; the message box cannot be closed by hitting the Esc key or by clicking the close box.
In BBj 17.00 and above, if a TIM=int option was specified and the user made no selection within the specified number of seconds, the return value is -1.
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.
In BBj 13.00 and higher, setting the NATIVE_BROWSER_MSGBOX !OPTIONSsetting to TRUE tells BUI to generate native browser alert() and confirm() dialogs for OK and OK/Cancel MSGBOX styles. This can provide a more native-looking appearance on mobile phone and tablet browsers.
Here is a sample msgbox:
|
The MSGBOX() function defines the following style names:
| Style Name | Description |
|---|---|
| .BBjMsgBox |
(the top level of the dialog window) |
|
.BBjMsgBox-title |
(the title bar) |
|
.BBjMsgBox-panel |
(the body area) |
|
.BBjMsgBox-message-panel |
(a horizontal panel that contains the icon and message) |
|
.BBjMsgBox-icon |
(the icon) |
|
.BBjMsgBox-icon-error |
(stop sign / error icon (16)) |
|
.BBjMsgBox-icon-question |
(question icon (32)) |
|
.BBjMsgBox-icon-warning |
(warning / exclamation icon (48)) |
|
.BBjMsgBox-icon-info |
(info icon (64)) |
|
.BBjMsgBox-message |
(the message) |
|
.BBjMsgBox-button-panel |
(a horizontal panel that contains the buttons) |
|
.BBjMsgBox-button |
(an individual button) |
With the default CSS styles, the msgbox looks like this:
And with the CSS file below, the same msgbox looks like this:
|
See STBL("!OPTIONS","NATIVE_BROWSER_MSGBOX"). Refer to the BUI Showcase for a more complete MSGBOX sample (demo, code).
Example 1
The following creates a dialog with the message "Ja oder nein" and two buttons with customized text, "Ja" and "Nein". It returns 6 if the user hits [RETURN] or clicks "Ja". It returns 7 if the user clicks "Nein", or 0 if the user hits [ESCAPE].
let x=msgbox("Ja oder nein",4,"","Ja","Nein")
Example 2
The following creates a customized dialog with the message "Accept print job?" and three buttons, "Yes", "Reprint" and "Fax". This returns 1 if the user clicks "Yes", 2 if the user clicks "Reprint" or 3 if the user clicks "Fax".
let x=msgbox("Accept print job?",7,"Printing is complete","Yes","Reprint","Fax")
For more examples from this topic's original documentation, see the MSGBOX() Function - Create Message Box Dialog.
Example 3
In BBj 3.02 and higher, the MSGBOX() function is automatically localized for several languages. The following example is functionally identical to Example 1; it creates a German Yes/No dialog.
let locale$=stbl("!LOCALE","de")
let x=msgbox("Ja oder nein",4)
For more examples from this topic's original documentation, see the MSGBOX() Function - Create Message Box Dialog.
Example 4
In BBj 17.00 and higher, the MSGBOX() function supports an optional TIM=int option.
let x=msgbox("OK",TIM=10)
If the user clicks the OK button, this returns 1.
If the user hits Esc or clicks the close box, this returns 0.
If the user makes no selection within 10 seconds, this returns -1.
Note:
The timeout is ignored in BUI when the NATIVE_BROWSER_MSGBOX option is selected.
Example 5
In BBj 19.10 and higher, the MSGBOX() function supports optional W=int and H=int mode options.
In BBj 22.00 and higher, the MSGBOX() function supports optional ICON=filename, ICONWIDTH=int, and ICONHEIGHT=int mode options.
|
Example 6
The custom button labels can be specified as HTML or Unicode strings.
|
See Also
DWC Component: dwc-dialog