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

0 OK

1 OK and Cancel

2 Abort, Retry, and Ignore

3 Yes, No, and Cancel

4 Yes and No

5 Retry and Cancel

7 Custom

 

Icon

0 None

16 Stop Sign

32 Question Mark

48 Exclamation Point

64 Information Symbol

 

Default Button

0 First button

256 Second button

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

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

Button Selected

1

OK

2

Cancel

3

Abort

4

Retry

5

Ignore

6

Yes

7

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 [ESCAPE] 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 [ESCAPE] 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 [ESCAPE] 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 !OPTIONS setting 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:

.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 ESCAPE or clicks the close box, this returns 0.

If the user makes no selection within 10 seconds, this returns -1.

N.B. 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.

rem ' msgbox

use java.util.Arrays
use java.util.ArrayList
use java.util.Locale
print 'hide',
sysgui = unt
open (sysgui)"X0"
bbjapi! = bbjapi()
sysgui! = bbjapi!.getSysGui()
window! = sysgui!.addWindow(100,100,730,450,"MSGBOX",$00090003$)
window!.setCallback(window!.ON_CLOSE,"eoj")
LocaleBox! = window!.addListBox(100,10,10,350,340,$$,$$)

x$ = "", y$ = "", w$ = $$, h$ = $$, html = 0
window!.addStaticText(101,0,365,25,25,"X:",$8000$)
x! = window!.addEditBox(102,30,360,50,25,"",$$)
x!.setToolTipText("X location of dialog")
x!.setCallback(x!.ON_EDIT_MODIFY,"x")
window!.addStaticText(103,90,365,25,25,"Y:",$8000$)
y! = window!.addEditBox(104,120,360,50,25,"",$$)
y!.setToolTipText("Y location of dialog")
y!.setCallback(y!.ON_EDIT_MODIFY,"y")
window!.addStaticText(105,180,365,25,25,"W:",$8000$)
w! = window!.addEditBox(106,210,360,50,25,"",$$)
w!.setToolTipText("Maximum width of content")
w!.setCallback(w!.ON_EDIT_MODIFY,"w")
window!.addStaticText(107,270,365,25,25,"H:",$8000$)
h! = window!.addEditBox(108,300,360,50,25,"",$$)
h!.setToolTipText("Maximum height of content")
h!.setCallback(h!.ON_EDIT_MODIFY,"h")

window!.addStaticText(109,360,365,75,25,"Extra rows:",$8000$)
rows! = window!.addInputNSpinner(110,440,360,75,25,0,5000)
rows!.setToolTipText("Extra rows of content")
rows!.setCallback(rows!.ON_SPIN,"rows")
rows!.setCallback(rows!.ON_EDIT_MODIFY,"rows")
rows = 0

window!.addStaticText(111,525,365,75,25,"Extra cols:",$8000$)
cols! = window!.addInputNSpinner(112,605,360,75,25,0,2000)
cols!.setToolTipText("Extra columns of content")
cols!.setCallback(cols!.ON_SPIN,"cols")
cols!.setCallback(cols!.ON_EDIT_MODIFY,"cols")
cols = 0

rem ' config.bbx: SET !OPTIONS=NATIVE_BROWSER_MSGBOX=TRUE
native_dialog$ = stbl("!OPTIONS","NATIVE_BROWSER_MSGBOX")
native_dialog = sgn(pos("TRUE"=native_dialog$))
flags$ = iff(native_dialog,$0004$,$0000$)
native_dialog! = window!.addCheckBox(113,10,400,110,25,"Native dialog",flags$)
native_dialog!.setToolTipText("BUI: Use native browser dialog for OK and OK/Cancel")
native_dialog!.setCallback(native_dialog!.ON_CHECK_ON,"native_dialog_true")
native_dialog!.setCallback(native_dialog!.ON_CHECK_OFF,"native_dialog_false")

use_html! = window!.addCheckBox(114,120,400,120,25,"HTML content",$0000$)
use_html!.setToolTipText("Always set MSGBOX content using html")
use_html!.setCallback(use_html!.ON_CHECK_ON,"use_html_true")
use_html!.setCallback(use_html!.ON_CHECK_OFF,"use_html_false")

window!.addStaticText(115,250,405,50,25,"Timeout:",$8000$)
timeout! = window!.addInputNSpinner(117,310,400,50,25,0,10)
timeout!.setCallback(timeout!.ON_SPIN,"timeout")
timeout!.setCallback(timeout!.ON_EDIT_MODIFY,"timeout")
timeout!.setToolTipText("MSGBOX timeout (seconds)")
timeout = 0

window!.addGroupBox(200,380,10,130,190,"Icon",$$)
Icon0! = window!.addRadioButton(201,400,40,100,25,"No Icon",$0004$)
Icon16! = window!.addRadioButton(202,400,70,100,25,"Stop Sign",$$)
Icon32! = window!.addRadioButton(203,400,100,100,25,"Question",$$)
Icon48! = window!.addRadioButton(204,400,130,100,25,"Exclamation",$$)
Icon64! = window!.addRadioButton(205,400,160,100,25,"Information",$$)
IconGroup! = window!.addRadioGroup()
IconGroup!.add(Icon0!)
IconGroup!.add(Icon16!)
IconGroup!.add(Icon32!)
IconGroup!.add(Icon48!)
IconGroup!.add(Icon64!)

window!.addGroupBox(300,380,220,130,130,"Default Button",$$)
Default0! = window!.addRadioButton(301,400,250,100,25,"First",$0004$)
Default256! = window!.addRadioButton(302,400,280,100,25,"Second",$$)
Default512! = window!.addRadioButton(303,400,310,100,25,"Third",$$)
DefaultGroup! = window!.addRadioGroup()
DefaultGroup!.add(Default0!)
DefaultGroup!.add(Default256!)
DefaultGroup!.add(Default512!)

window!.addGroupBox(400,530,10,190,340,"Buttons",$$)
Buttons0! = window!.addRadioButton(401,550,40,150,25,"OK",$0004$)
Buttons1! = window!.addRadioButton(402,550,70,150,25,"OK/Cancel",$$)
Buttons2! = window!.addRadioButton(403,550,100,150,25,"Abort/Retry/Ignore",$$)
Buttons3! = window!.addRadioButton(404,550,130,150,25,"Yes/No/Cancel",$$)
Buttons4! = window!.addRadioButton(405,550,160,150,25,"Yes/No",$$)
Buttons5! = window!.addRadioButton(406,550,190,150,25,"Retry/Cancel",$$)
Buttons7! = window!.addRadioButton(407,550,220,150,25,"Custom",$$)
ButtonsGroup! = window!.addRadioGroup()
ButtonsGroup!.add(Buttons0!)
ButtonsGroup!.add(Buttons1!)
ButtonsGroup!.add(Buttons2!)
ButtonsGroup!.add(Buttons3!)
ButtonsGroup!.add(Buttons4!)
ButtonsGroup!.add(Buttons5!)
ButtonsGroup!.add(Buttons7!)

Custom1! = window!.addEditBox(501,570,250,130,25,"",$$)
Custom2! = window!.addEditBox(502,570,280,130,25,"",$$)
Custom3! = window!.addEditBox(503,570,310,130,25,"",$$)

Close! = window!.addButton(2,380,400,100,25,"Close")
Close!.setCallback(Close!.ON_BUTTON_PUSH,"eoj")
OK! = window!.addButton(1,490,400,100,25,"MSGBOX")
OK!.setCallback(OK!.ON_BUTTON_PUSH,"msgbox")
Result! = window!.addStaticText(3,600,400,120,25,"")
Result!.setBackColor(BBjColor.YELLOW)

gosub init

process_events
eoj:
release

native_dialog_true:
  native_dialog$="TRUE"
  native_dialog$ = stbl("!OPTIONS","NATIVE_BROWSER_MSGBOX="+native_dialog$)
return

native_dialog_false:
  native_dialog$="FALSE"
  native_dialog$ = stbl("!OPTIONS","NATIVE_BROWSER_MSGBOX="+native_dialog$)
return

use_html_true:
  html = 1
return

use_html_false:
  html = 0
return

msgbox:
  Locale = LocaleBox!.getSelectedIndex()
  if Locale<0 then
     Locale$ = stbl("!LOCALE",Locale.getDefault().toString())
     Locale! = Locale.getDefault()
     Message! = Locale!.getDisplayName(Locale!)
     Title! = Locale!.getDisplayName()
  else
     Locale$ = stbl("!LOCALE",Locales!.get(Locale))
     Locale! = LocaleList!.get(Locale)
     Message! = localNameList!.get(Locale)
     Title! = defaultNameList!.get(Locale)
  endif

  Title$ = fnhtml$(Title!,html)

  if rows then
     for i = 1 to rows
      extra$ = fill(cols,"row"+str(i)+",")
      Message! = Message!.concat($0a$).concat(extra$)
     next i
  endif

  Message$ = fnhtml$(Message!,html)
  expr = 0, custom = 0
  switch ButtonsGroup!.getSelected().getID()
    case Buttons0!.getID(); break
    case Buttons1!.getID(); expr=1; break
    case Buttons2!.getID(); expr=2; break
    case Buttons3!.getID(); expr=3; break
    case Buttons4!.getID(); expr=4; break
    case Buttons5!.getID(); expr=5; break
    case Buttons7!.getID(); expr=7,custom=1; break
    case default; escape
  swend
  
  switch IconGroup!.getSelected().getID()
    case Icon0!.getID(); break
    case Icon16!.getID(); expr=expr+16; break
    case Icon32!.getID(); expr=expr+32; break
    case Icon48!.getID(); expr=expr+48; break
    case Icon64!.getID(); expr=expr+64; break
    case default; escape
  swend
 
  switch DefaultGroup!.getSelected().getID()
    case Default0!.getID(); break
    case Default256!.getID(); expr=expr+256; break
    case Default512!.getID(); expr=expr+512; break
    case default; escape
  swend
 
  mode$ = "x=50,y=50,w=500,h=500"
  mode$ = "w=500,h=500"
  mode$ = "x="+x$+",y="+y$+",w="+w$+",h="+h$

print mode$

  if custom then
    Button1! = Custom1!.getText().trim(),Button1$=fnhtml$(Button1!,html)
    Button2! = Custom2!.getText().trim(),Button2$=fnhtml$(Button2!,html)
    Button3! = Custom3!.getText().trim(),Button3$=fnhtml$(Button3!,html)
    if Button3!.length() then
       result = msgbox(Message$,expr,Title$,Button1$,Button2$,Button3$,tim=timeout,mode=mode$,err=oops)
    else
       if Button2!.length() then
          result = msgbox(Message$,expr,Title$,Button1$,Button2$,tim=timeout,mode=mode$,err=oops)
       else
          if Button1!.length() then
             result = msgbox(Message$,expr,Title$,Button1$,tim=timeout,mode=mode$,err=oops)
          else
             result = msgbox(Message$,expr,Title$,tim=timeout,mode=mode$,err=oops)
          endif
       endif
    endif
    switch result
      case -1; result$ = "Timeout"; break
      case 0; result$ = "None"; break
      case 1; result$ = Button1$; break
      case 2; result$ = Button2$; break
      case 3; result$ = Button3$; break
      case default; result$ = "Undefined"
    swend
  else
    result = msgbox(Message$,expr,Title$,tim=timeout,mode=mode$,err=oops)
    switch result
      case -1; result$ = "Timeout"; break
      case 0; result$ = "None"; break
      case 1; result$ = "OK"; break
      case 2; result$ = "Cancel"; break
      case 3; result$ = "Abort"; break
      case 4; result$ = "Retry"; break
      case 5; result$ = "Ignore"; break
      case 6; result$ = "Yes"; break
      case 7; result$ = "No"; break
      case default; result$ = "Undefined"
    swend
  endif
  result$ = result$ + " ("+str(result)+")"
  Result!.setText(result$)
return

oops:
result = msgbox(errmes(-1),48,"*** ERROR ***")
return

init:
  default$ = Locale.getDefault().toString()
  default = 0
  vector! = bbjapi().makeVector()
  list! = stbl("!LOCALES")
  Locales! = Arrays.asList(list!.split($0a$))
  localeList! = new ArrayList()
  localNameList! = new ArrayList()
  defaultNameList! = new ArrayList()
  for i=0 to Locales!.size()-1
    if Locales!.get(i).equals(default$) then default=i
    temp! = Arrays.asList(Locales!.get(i).split("_",3))
    switch temp!.size()
      case 3; Locale! = new Locale(temp!.get(0),temp!.get(1),temp!.get(2)); break
      case 2; Locale! = new Locale(temp!.get(0),temp!.get(1)); break
      case 1; Locale! = new Locale(temp!.get(0)); break
      case default; Locale! = Locale.getDefault(); break
    swend
    localeList!.add(Locale!)
    language$ = Locale!.getLanguage()
    localName! = new String(Locale!.getDisplayName(Locale!).getBytes("UTF-8"),"UTF-8")
    defaultName! = new String(Locale!.getDisplayName().getBytes("UTF-8"),"UTF-8")
    unicode! = localName!.concat(" - ").concat(defaultName!)
    vector!.add(unicode!)
    localNameList!.add(localName!)
    defaultNameList!.add(defaultName!)
  next i
  LocaleBox!.insertItems(-1,vector!)
  LocaleBox!.selectIndex(default)
return

def fnhtml$(string!,_html)
  html! = new StringBuffer("")
  if string!.length() then
    for i=0 to string!.length()-1
      c = string!.codePointAt(i)
      if c<128 then html!.append(chr(c)) else html!.append("&#").append(str(c)).append(";"); _html=1
    next i
    if _html then
       html!.insert(0,"<html>")
    endif
  endif
  print string!," = ",html!
  if _html then return html!.toString().replaceAll($0a$,"<br>")
  return html!.toString()
fnend

timeout:
  event! = sysgui!.getLastEvent()
  timeout = num(event!.getText())
return

rows:
  event! = sysgui!.getLastEvent()
  rows = num(event!.getText())
return

cols:
  event! = sysgui!.getLastEvent()
  cols = num(event!.getText())
return

x:
  event! = sysgui!.getLastEvent()
  x$ = event!.getText()
return

y:
  event! = sysgui!.getLastEvent()
  y$ = event!.getText()
return

w:
  event! = sysgui!.getLastEvent()
  w$ = event!.getText()
return

h:
  event! = sysgui!.getLastEvent()
  h$ = event!.getText()
return

See Also

Functions - Alphabetical Listing

STBL("!OPTIONS","NATIVE_BROWSER_MSGBOX")

______________________________________________________________________________________

Copyright BASIS International Ltd. BBj®, Visual PRO/5®, PRO/5®, and BBx® are registered trademarks.