MSGBOX

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

Parameters

msg (String) [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) [in]

Specifies the title that will appear in the title bar of the message box.

btnflag (Num) [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	&h0000	OK button only, or customized buttons; see comments.
MBTN_OK_CANCEL	&h0001	OK and CANCEL buttons
MBTN_ABORT_RETRY_IGNORE	&h0002	ABORT, RETRY, and IGNORE buttons
MBTN_YES_NO_CANCEL	&h0003	YES, NO, and CANCEL buttons
MBTN_YES_NO	&h0004	YES and NO buttons
MBTN_RETRY_CANCEL	&h0005	RETRY and CANCEL buttons
MBTN_HELP	&h4000	Add a HELP button
MBTN_CANCEL_TRY_CONTINUE	&h0006	See note in History, below
Definition File: ashell.def

Hex-Decimal Values

iconflag (Num) [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

Hex-Decimal Values

miscflags (Num) [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

Hex-Decimal Values

rtncde (Num) [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
<no symbol>	101	First custom button; see mxflags MBX_RCBTNO
	102	Second " " " "
	103	Third " " " "
	104	Fourth " " " "
	105	Fifth " " " "
Definition File: ashell.def

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 BASIC 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) [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

timeout (Num) [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) [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) [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

<a href=http://www.microsabio.com>MicroSabio Home Page</a>

<a href="http://www.microsabio.com">MicroSabio Home Page</a>

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) [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, 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) [in]

optional tool tips for up to 5 buttons.

fontface (String) [in]

optional font to use

fontscale (Num) [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) [in]

optional RGB value to use for the message text.

bgc (Num) [in]

optional RGB value to use for the background of the message.

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.

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. 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.SBR 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.SBR now gets button text from LDF.

2006 Jan, A-Shell 4.9.950: MSGBOX.SBR 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:

ALIAS=MSGBOX:MSGBXX

That way, when your application does call MSGBOX, the ALIAS will convert this to MSGBXX, which will find the SBX.

MSGBOX

Parameters

Examples

History