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 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 () [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 () [in]
Specifies the title that will appear in the title bar of the message box.
btnflag () [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:
|
iconflag () [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:
|
miscflags () [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:
|
rtncde () [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:
|
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 () [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
|
timeout () [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 () [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 () [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 () [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 (, 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 () [in]
optional tool tips for up to 5 buttons.
fontface () [in]
optional font to use
fontscale () [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 () [in]
optional RGB value to use for the message text.
bgc () [in]
optional RGB value to use for the background of the message.
|
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
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$ = "<a href="http://www.whitehouse.gov">White House</a>"
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
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 . 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:
ALIAS=MSGBOX:MSGBXX
That way, when your application does call MSGBOX, the ALIAS will convert this to MSGBXX, which will find the SBX.
|
