# MSGBOX _Updated January 2021; see History_ **xcall MSGBOX, msg, title, btnflag, iconflag ** **\{, miscflags, rtncde** **\{, mxflags, timeout, timein, url, iconspec, ** ** btn1, btn2, btn3, btn4, btn5, ** ** tip1, tip2, tip3, tip4, tip5, ** **fontface, fontscale, fgc, bgc\}\}** Note that in the syntax shown above, spaces and line breaks have no meaning—i.e., they do not and should not exist in the actual program. They are used here strictly as visual aides to illustate the structure of the commands. MSGBOX displays a message in a popup dialog, with a variety of standard or customized response button options. Depending on the environment and parameter options, one of four implementations may be used: • Standard Windows Message Box. Used in GUI environments prior to A-Shell 6.3.1543 or when no extended options are requested. • Enhanced A-Shell Message Box using a dialog built with the AUI\_CONTROL API. Used in A-Shell 6.3.1543 and later GUI environments when the _mxflags_ parameter is specified. • [INMEMO](inmemo.md)** **free-form menu. This is used in plain text environments or when forced with the MBX\_FRCTXT flag. • HTML. In CGI mode, the message is simply sent to the browser in HTML format as the CGI response. **(./images/hmtoggle_plus1.gif) Parameters** _msg _([String](string.md)) \[in\] Specifies the message to display. The width of the message box will be adjusted (within certain reasonable limits) to the size of the message, which will them be wrapped as needed. You can also force your own line breaks and blank lines by inserting CHR\$(13) characters. _title _([String](string.md)) \[in\] Specifies the title that will appear in the title bar of the message box. _btnflag _([Num](num.md)) \[in\] Select one of the following values to specify the set of response buttons that will appear in the message box. Note that you can change the button text via the _btn1-btn5_ parameters. When using custom buttons, you can set the _btnflag_ to 0, which is equivalent to a single "OK" button in the standard case; if custom buttons are defined, will be interpreted accordingly. See Comments below for more details on defining custom buttons. | | | | |------|------|------| | **Symbol** | **Value** | **Description** | | MBTN\_OK | 0 | OK button only, or customized buttons; see comments. | | MBTN\_OK\_CANCEL | 1 | OK and CANCEL buttons | | MBTN\_ABORT\_RETRY\_IGNORE | 2 | ABORT, RETRY, and IGNORE buttons | | MBTN\_YES\_NO\_CANCEL | 3 | YES, NO, and CANCEL buttons | | MBTN\_YES\_NO | 4 | YES and NO buttons | | MBTN\_RETRY\_CANCEL | 5 | RETRY and CANCEL buttons | | MBTN\_CANCEL\_TRY\_CONTINUE | 6 | See note in _History_, below | | | | | | MBTN\_HELP | \&h4000 | Add a HELP button. Combine with any other MBTN\_xxx option. | | **Definition File: [ashell.def](ashell.md)** | | [Hex-Decimal Values](hex-decimalvalues.md) _iconflag _([Num](num.md)) \[in\] Select one of the following to specify the standard Windows icon that appears in the message box (in a GUI environment). 0 specifies no icon. See _iconspec _to specify a custom icon. | | | | |------|------|------| | **Symbol** | **Value** | **Description** | | MBICON\_STOP | \&h0010 | Stop (Red X) | | MBICON\_QUESTION | \&h0020 | Question (?) | | MBICON\_EXCLAMATION | \&h0030 | Exclamation (\!) | | MBICON\_ICON | \&h0040 | Information (i) | | **Definition File: [ashell.def](ashell.md)** | | [Hex-Decimal Values](hex-decimalvalues.md) _miscflags _([Num](num.md)) \[in\] Combine zero or more of the following to specify misc options: | | | | |------|------|------| | **Symbol** | **Value** | **Description** | | MBMISC\_DFLT2 | \&h0100 | Make the second button be the default. (Normally the first button will be the default button.) | | MBMISC\_DFLT3 | \&h0200 | Make the third button be the default. | | MBMISC\_DFLT4 | \&h0300 | Make the fourth button be the default | | MBMISC\_DFLT5 | \&h0400 | Make the fifth button be the default | | MBMISC\_SYSMODAL | \&h1000 | System modal. Suspends all Windows applications until the dialog box is responded to. (Windows only) | | MBMISC\_TASKMODAL | \&h2000 | Task modal. Suspends the A-Shell session until the dialog box is responded to. (Windows only) | | MBMISC\_TOPMOST | \&h8000 | Force message dialog to remain on top until closed. This prevents a problem where it can get hidden by other windows, even though it has the focus, making the other windows appear to be dead. | | | | **Definition File: [ashell.def](ashell.md)** | [Hex-Decimal Values](hex-decimalvalues.md) _rtncde _([Num](num.md)) \[out\] Returns a code indicating what button was pushed to respond to the message, from the list below: | | | | |------|------|------| | **Symbol** | **Value** | **Description** | | MBRC\_OK | 1 | OK button | | MBRC\_CANCEL | 2 | CANCEL button | | MBRC\_ABORT | 3 | ABORT button | | MBRC\_RETRY | 4 | RETRY button | | MBRC\_IGNORE | 5 | IGNORE button | | MBRC\_YES | 6 | YES button | | MBRC\_NO | 7 | NO button | | MBRC\_CLOSE | 8 | Dialog closed; see notes below | | MBRC\_HELP | 9 | HELP button | | MBRC\_TRYAGAIN | 10 | TRY AGAIN button | | MBRC\_CONTINUE | 11 | CONTINUE button | | MBRC\_CTRLC | 12 | Control-C; see notes below | | | 101 | First custom button; see mxflags MBX\_RCBTNO | | | 102 | Second " " " " | | | 103 | Third " " " " | | | 104 | Fourth " " " " | | | 105 | Fifth " " " " | | **Definition File: [ashell.def](ashell.md)** | | A return code of 8 indicates that the message box was closed without clicking on one of the button choices (either the X button in the corner of the dialog under Windows/ATE or the Escape key under Unix/text mode). Note, however, that at least under Windows, the internal message box logic may try to translate the close option to one of the existing buttons if it makes logical sense. For example, closing an OK/CANCEL dialog may return as if CANCEL clicked. The MBRC\_xxx values are associated with standard buttons sets as specified by the MBTN\_xxx values in btnflag while the values 101-105 are used for custom button sets; see mxflags MBX\_RCBTNO flag and Comments below. Note that Control-C will set the Control-C flag (triggering ASB error 1) if Control-C is enabled; otherwise it will return MBRC\_CTRLC. Also note that for the standard Windows Message Box, Control-C while the box is displayed may be ignored (acting instead as the Windows Copy command); but if the Control and C keys are down when the message box is created or destroyed, it will be detected and processed, providing a way out of situations where an error message box is being displayed in an endless loop. Hold down the Control and C buttons with one hand and dismiss the message box using the mouse with the other hand. _mxflags_ ([Num](num.md)) \[in\] flags related to extended options: | **Symbol** | **Value** | **Description** | |------|------|------| | MBX\_RCBTNO | \&h10000000 | return 101-105 for buttons 1-5 | | MBX\_FRCTXT | \&h20000000 | force plain text version | | MBX\_TI1 | \&h00100000 | time-in delay on button 1 | | MBX\_TI2 | \&h00200000 | time-in delay on button 2 | | MBX\_TI3 | \&h00400000 | time-in delay on button 3 | | MBX\_TI4 | \&h00800000 | time-in delay on button 4 | | MBX\_TI5 | \&h01000000 | time-in delay on button 5 | [Hex-Decimal Values](hex-decimalvalues.md) _timeout_ ([Num](num.md)) \[in\] if not zero, sets the timeout (in seconds) on the default button, at which point the button is auto-clicked. Except in the case of icon buttons, the button will show the countdown progress. _timein _ ([Num](num.md)) \[in\] used in conjunction with the MBX\_TIx flags (see mxflags) to specify a time (in seconds) before which one or more buttons are unable to be clicked (i.e. disabled). This is useful when you want to make sure the message box stays on the screen for at least a certain number of seconds, either so that the user can read the message, or perhaps to prevent the possibility of accidentally clicking a button before understanding the consequences. Note that if _timeout_ is not zero, it overrides the _timein_ for the default button. _url _ ([String](string.md)) \[in\] optionally specifies a clickable hyperlink that appears beneath the message text and above the buttons. The visible text may be the same as the target url, or you may use HTML format to display something other than the actual link, e.g. http://www.microsabio.com MicroSabio Home Page MicroSabio Home Page The third example shows the proper HTML format—i.e., with the url field quoted. Note that to embed quotes within a quoted string in BASIC you have to use double quotes (""). The second example, without the extra quotes is supported for convenience. See History note of May 2017. _iconspec _ ([String](string.md)) \[in\] optionally specifies an icon (native Windows filespec or iconname::icondll, e.g. "warning::ashico1") to be used instead of the standard one based on the iconflag value, which will be ignored if _iconspec_ is non-null. If neither an _iconflag_ nor an _iconspec_ is specified, the message box will have no icon. Note the standard icons specified via the _iconflag_ parameter do not change size with _fontscale_, but custom icons (specified via _iconspec_) do scale. _btn1 - btn5_ ([String](string.md), 32) \[in\] optional text or icon to display for up to 5 buttons—assuming you want to override the default button text corresponding to the _btnflag_ parameter. Although you can mix text buttons and icon buttons, it probably works (or looks) best if you stick to one or the other. For icons, you can use the native Windows filespec of the .ico file or the iconname::icondll format for an icon within an icon library (like ashico1.dll). Note the 32 byte limit on the length of each field; for ico filespecs, to fit within 32 characters you may need to drop the directory from the path and either put the icon in the current directory or in the default A-Shell icon search path—e.g. the cache, permcache, or icons subdirectories. _tip1 - tip5 _ ([String](string.md)) \[in\] optional tool tips for up to 5 buttons. _fontface _ ([String](string.md)) \[in\] optional font to use _fontscale_ ([Num](num.md)) \[in\] optional font scale adjustment in percent. 0 is treated the same as 100 percent. In modern high-res environments, you may find that increasing the font size makes for a more readable message. Note that the font scale does not affect the title bar, but it does affect nearly everything else in the message box. See note under _iconspec_. _fgc _ ([Num](num.md)) \[in\] optional RGB value to use for the message text. _bgc_ ([Num](num.md)) \[in\] optional RGB value to use for the background of the message. **(./images/hmtoggle_plus1.gif) Examples** Standard Abort/Retry/Ignore message box in both GUI and plain text versions: xcall MSGBOX, "Best man tried on ring, can't get it off\!", "Wedding Crisis", 2, \&h0030, 0, rtncde _(./images/ashref_img174.png)_ _(./images/ashref_img175.png)_ Enhanced version with custom buttons, hyperlink colors... msg\$ = "Obamacare repealed - how do you want to pay? (Click link below to complain)" title\$ = "Emergency Room Cashier Encounter" link\$ = "White House" icon\$ = "first\_aid::ashico1" btn1\$ = "Cash" : btn2\$ = "Medicare" : btn3\$ = "Private Ins"  : btn4\$ = "" : btn5\$ = "" tip1\$ = "If you got it"  : tip2\$ = "Ages 65+ only" : tip3\$ = "If you can afford it" font\$ = "" fontscale = 150 bgc = \&hddddff  \! pink background xcall MSGBOX, msg\$, title\$, 0, 0, 0, rtncde, 0, 0, 0, link\$, icon\$, btn1\$, btn2\$, btn3\$, btn4\$, btn5\$, tip1\$, tip2\$, tip3\$, tip4\$, tip5\$, font\$, fontscale, fgc, bgc Enhanced version with icon buttons... title\$ = "Music Player" msg\$ = "Current selection: "+chr(13)+chr(13) "I've been working on the A-Shell..." icon\$ = "music::ashico1" link\$ = "" btn1\$ = "media\_beginning::ashico1" : btn2\$ = "media\_rewind::ashico1" : btn3\$ = "media\_play::ashico1" btn4\$ = "media\_fast\_forward::ashico1" : btn5\$ = "media\_end::ashico1" tip1\$ = "beginning" : tip2\$ = "rewind" : tip3\$ = "play" : tip4\$ = "fast forward" : tip5\$ = "end" font\$ = "Comic Sans MS" fontscale = 200 xcall MSGBOX, msg\$, title\$, 0, 0, 0, rtncde, 0, 0, 0, link\$, icon\$, btn1\$, btn2\$, btn3\$, btn4\$, btn5\$, tip1\$, tip2\$, tip3\$, tip4\$, tip5\$, font\$, fontscale **Comments** **Standard vs custom buttons:** the original version of the message box offered several standard sets of buttons (OK, YES/NO, etc) as specified by the _btnflag_ parameter, and returned a code unique to each button's meaning, rather than its position. So MBRC\_CANCEL means the same regardless of whether the CANCEL button was in the 2nd or 3rd position. The enhanced version allows you to specify an arbitrary set of up to 5 buttons, and gives you the choice of treating those as substitutes for the standard button labels, still using the MBRC\_xxx rtncde values, or as totally arbitrary buttons (identified by button position in rtncde values 101-105), based on the mxflag MBX\_RCBTNO flag. For example, if you set btnflag to MBTN\_YES\_NO, but specify btn1="Good" and btn2="Bad", unless you set the MBX\_RCBTNO flag, the "Good" button will act as the YES button (returning MBRC\_YES) and the "Bad" button will act as NO (returning MBRC\_NO). This might make sense in some cases, but in general it will probably be best to explicitly set the MBX\_RCBTNO flag to return the button number (101 thru 105) when using customized labels. There are two cases where the MBX\_RCBTNO flag will be implicitly set. The first occurs when the number of custom buttons defined is more than the number in the standard set as specified by btnflag. In that case, the additional buttons will always return the position code (101-105). The second occurs when btnflag is set to zero and more than one custom button label is defined (i.e. when btn2 is non empty). Although btnflag value zero is equivalent to MBTN\_OK, it seems clear that if two or more custom buttons are defined, the intended meaning of btnflag zero is not MBTN\_OK but "custom buttons only". This allows you to leave both btnflag and mxflag at zero with a set of custom buttons while avoiding the confusion of the first button returning MBRC\_OK while the other buttons return values 102 thru 105. Aside from the features documented above, an advantage of the enhanced message box is that although it forces you to respond to the message box before returning to the application (i.e. it is task modal), it allows you to access the A-Shell menu bar, for example, to use the Print Screen utility. **See Also** • [Display Standard Message Dialog](ag_messageboxstd.md) u **History** 2021 January, A-Shell 6.5.1697: The _timein_ parameter now applies selectively to each of the buttons (based on the xflags MBX\_TIx bits), and is independent of the _timeout_ value, except that the _timeout_ value overrides the _timein_ value for the default button. Previously the _timein_ needed to be applied to all buttons for it to work at all, and there was no visual indication of the _timein_ countdown. 2019 September, A-Shell 6.5.1667: Calls using MBICON\_QUESTION are no longer logged to the ashlog. Only MBICON\_STOP or MBICON\_EXCLAMATION trigger the logging. 2017 May, A-Shell 6.4.1550: All parameters after _mxflags_ are now optional.Previously, if _mxflags_ was specified, but _url_ and _iconspec_ were not also specified, the routine was likely to crash. 2017 January, A-Shell 6.3.1543: Major enhancements and internal rewriting. Add support for up to five buttons, customizeable button labels or icons, tool tips, time delay, time out, optional hyperlink field, colors, fonts, etc. 2011 August, A-Shell 5.1.1231: Right-click on the box now reveals a context menu option to print the screen (if the bas:aprntscrn.cfg is configured for print screen). 2011 April, A-Shell 5.1.1210: MBTN\_CANCEL\_TRY\_CONTINUE produces the buttons "Cancel", "Try Again", and "Continue", and returns two new status values MBRC\_TRYAGAIN and MBRC\_CONTINUE. This is actually just an alternate style to the older ABORT/RETRY/IGNORE message box (with ABORT being replaced by CANCEL, RETRY being replaced by TRY AGAIN, and IGNORE being replaced by CONTINUE). The new variation has been used in Windows since W2000, in preference to the older style. Actually, no change to MSGBOX was necessary to support this new style - it was just a matter of defining symbols for the new codes in [ashell.def](ashell.md). The only internal change is that if you specify the new style but are not running in GUI mode, it continues to display in the old style, while behaving compatibly with the new style. 2011 April, A-Shell 5.1.1210: MSGBOX now checks if the Ctrl and C keys are down, both on entrance and exit. If so, and CTRLC is enabled for the job, error 1 is triggered. Otherwise, it returns the new return status code 12 (MBRC\_CTRLC). This should help alleviate a frustrating situation where a program was putting up error message boxes too fast to allow the Ctrl+C keyboard status to be detected between the MSGBOX calls (and Ctrl+C is not recognized as an abort by the standard Windows message box itself). 2009 November, A-Shell 5.1.1164: MBMISC\_DEFLT2 and MBMISC\_DEFLT3 flags (to select the default button) are now supported in text mode. (Previously text mode always selected the first button.) Also, the Windows version now uses the LDF to get the button labels (the Unix version has done this for a long time). 2006 March, A-Shell 4.9.953: The text version of MSGBOX now gets button text from LDF. 2006 Jan, A-Shell 4.9.950: MSGBOX is now implemented as an internal subroutine (effectively replacing MSGBOX.SBX). There should be no other change in the behavior. If, for some reason, you want to keep using the MSGBOX.SBX, then rename it to something else (e.g. MSGBXX.SBX) and then create an ALIAS[sp](keyword-types.md): ALIAS=MSGBOX:MSGBXX That way, when your application does call MSGBOX, the ALIAS[sp](keyword-types.md) will convert this to MSGBXX, which will find the SBX.