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. 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.0 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)
305

Buttons

Value	BBjSysGui Constant (BBj 21.0 and higher)	Buttons
0	MSGBOX_BUTTONS_OK	OK
1	MSGBOX_BUTTONS_OK_CANCEL	OK and Cancel
2	MSGBOX_BUTTONS_ABORT_RETRY_IGNORE	Abort, Retry, and Ignore
3	MSGBOX_BUTTONS_YES_NO_CANCEL	Yes, No, and Cancel
4	MSGBOX_BUTTONS_YES_NO	Yes and No
5	MSGBOX_BUTTONS_RETRY_CANCEL	Retry and Cancel
7	MSGBOX_BUTTONS_CUSTOM	Custom

Icon

Value	BBjSysGuiConstant (BBj 21.0 and higher)	Icon
0	MSGBOX_ICON_NONE	None
16	MSGBOX_ICON_STOP	Stop Sign
32	MSGBOX_ICON_QUESTION	Question Mark
48	MSGBOX_ICON_EXCLAMATION	Exclamation Point
64	MSGBOX_ICON_INFORMATION	Information Symbol

Default Button

Value	BBjSysGui Constant	Default Button
0	MSGBOX_DEFAULT_FIRST	First Button
256	MSGBOX_DEFAULT_SECOND	Second Button
512	MSGBOX_DEFAULT_THIRD	Third Button
65536		Do not allow the currently highlighted button to be selected with `Enter`.

Render HTML (BBj 11.0 and higher)

0	Render title and/or message as HTML if the string starts with <html>.
32768	Disable HTML processing. Render both title and message as raw text, even if the string starts with <html>.

Modal Value

0	Application modal. Requires users to respond to the message box before continuing work in the current application.
262144	System modal. Not available in BBj.

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.

str2

Dialog box title text. If this parameter is omitted, the program name is used as the title.

button1

Custom text for the first button.

button2

Custom text for the second button.

button3

Custom text for the third button.

ERR=lineref

Branch to be taken if an error occurs during execution.

MODE="STYLE=name"

In BBj 14.0 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.0 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="property=value"

In BBj 21.10 and higher, the mode string can specify arbitrary DWC properties (e.g., "theme=danger"). Themes can also be applied to individual buttons (e.g., "button-0-theme=success, button-1-theme=info, button-2-theme=danger").

TIM=int

In BBj 17.0 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.0 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.0 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:

i = msgbox("This is the message",64+1,"BBjMsgBox")

The MSGBOX() function defines the following style names:

.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:

Copy

BBjMsgBox

.BBjMsgBox
{
  border-width: 0px !important;
  -webkit-border-radius: 10px;
  -moz-border-radius: 10px;
  border-radius: 10px;
  border: 1px solid black;
  -webkit-box-shadow: #C6C6C6 2px 2px 2px;
  -moz-box-shadow: #C6C6C6 2px 2px 2px;
  box-shadow: #C6C6C6 2px 2px 2px;
}

.BBjMsgBox-title
{
}

.BBjMsgBox-icon
{
}

.BBjMsgBox-message
{
}

.BBjMsgBox-button
{
  background: rgb(255,255,255);
  background: -moz-linear-gradient(top,  rgba(255,255,255,1) 0%, rgba(229,229,229,1) 100%);
  background: -webkit-gradient(linear, left top, left bottom, color-stop(0%,rgba(255,255,255,1)), color-stop(100%,rgba(229,229,229,1)));
  background: -webkit-linear-gradient(top,  rgba(255,255,255,1) 0%,rgba(229,229,229,1) 100%);
  background: -o-linear-gradient(top,  rgba(255,255,255,1) 0%,rgba(229,229,229,1) 100%);
  background: -ms-linear-gradient(top,  rgba(255,255,255,1) 0%,rgba(229,229,229,1) 100%);
  background: linear-gradient(to bottom,  rgba(255,255,255,1) 0%,rgba(229,229,229,1) 100%);
  filter: progid:DXImageTransform.Microsoft.gradient( startColorstr='#ffffff', endColorstr='#e5e5e5',GradientType=0 );
}

.BBjMsgBox-button-panel
{
}

.BBjMsgBox .dialogContent
{
  background: rgb(206,220,231);
  background: -moz-linear-gradient(top,  rgba(206,220,231,1) 0%, rgba(89,106,114,1) 100%);
  background: -webkit-gradient(linear, left top, left bottom, color-stop(0%,rgba(206,220,231,1)), color-stop(100%,rgba(89,106,114,1)));
  background: -webkit-linear-gradient(top,  rgba(206,220,231,1) 0%,rgba(89,106,114,1) 100%);
  background: -o-linear-gradient(top,  rgba(206,220,231,1) 0%,rgba(89,106,114,1) 100%);
  background: -ms-linear-gradient(top,  rgba(206,220,231,1) 0%,rgba(89,106,114,1) 100%);
  background: linear-gradient(to bottom,  rgba(206,220,231,1) 0%,rgba(89,106,114,1) 100%);
  filter: progid:DXImageTransform.Microsoft.gradient( startColorstr='#cedce7', endColorstr='#596a72',GradientType=0 );
}

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.0 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 options.