MSGBOX.SBR now supports up to five buttons, customizeable button labels or icons, tool tips, time delay, time out, hyperlink field, colors, fonts, etc. New syntax:

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}}

The original arguments msg thru rtncde remain as before. If 6 or fewer arguments are specified, it continues to use the original MSGBOX implementation, based on the standard Windows Message Box for GUI environments, or INMEMO for plain text environments.

Otherwise (i.e. if the mxflags argument is specified), the routine uses a new implementation entirely internal to A-Shell. For GUI environments, the new implementation is similar to an extended version of the standard Message Box; for plain text environments it uses the same INMEMO implementation as before. Note that many of the new features will be ignored in the plain text version (icons, tooltips, fonts, hyperlinks, etc.)

New Parameters

mxflags  (num)  [in]

flags related to extended options:

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.

url  (str)  [in]

optionally specified 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-double quotes (""). The second example, without the extra quotes is supported for convenience.

iconspec  (str)  [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 no 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  (s,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  (str)  [in]

optional tool tips for up to 5 buttons.

fontface  (str)  [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.

Comments

Aside from the features documented above, another advantage of the enhanced message box (vs the standard Windows 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.

Pausing the countdown: in the case of a countdown (see timeout), the user may want to pause the countdown in order to allow more time to study the message, seek help etc. This can be accomplished by right-clicking on the affected button, which suspends the countdown and displays a simple context menu containing the single option "Resume". Although this may not be obvious to the interested user, if you don't supply your own button tooltip, one will assigned automatically saying "Right-click to pause countdown". It may still not be obvious to the user but at least they have a fighting chance of stumbling on it. If you supply your own tooltip, you may want to include wording to the same effect.