A-Shell Reference

Revised December 2023; see History

xcall MSBOXX, strow, stcol, endrow, endcol, boxcod {, boxsts, boxclr}

MSBOXX is nearly equivalent to the version under AMOS (developed by MicroSabio as part of the TRACKER package), except that it does not support the boxmap and boxctl parameters of the AMOS version. For complete details, you should consult the TRACKER User's Guide. Here, however, is a brief summary:  

Parameters

strow, stcol, endrow, endcol

specify the coordinates of the upper left and lower right corner of the box to be drawn. It is important to note that if a border is applicable, it is drawn OUTSIDE of the coordinates specified for the box. (Thus the interior, or usable part of the box is the same size whether or not the border option is specified.)

boxcod

specifies one or more options (added together). These are generally referenced symbolically via the msboxx.bsi include file.

Hex-Decimal Values

 

boxsts

optionally returns a code indicating if the operation succeeded. 0 indicates success.

boxclr

optionally defines the set of colors to use for the parts of the box:

MAP1 BOXCLR

  MAP2 BRDR'FG,B,1    ! Border foreground

  MAP2 BRDR'BG,B,1    ! Border background

  MAP2 IBOX'FG,B,1    ! Interior foreground

  MAP2 IBOX'BG,B,1    ! Interior background

 

Comments

Since TRACKER is built-in to A-Shell, you can always count on the ability to save and restore screen areas with MSBOXX. You can also perform all of these box drawing and save/restore operations using individual TAB(x,y) commands, but with considerably more effort.

History

2023 November, A-Shell 7.0.1751.4:  Hot spots created with Tab(-1,162) are now saved and restored in ATE environments as well as pure Windows.  Note however that in the ATE environment, the application needs to send a Tab() command with an explicit termination following the Tab(-1,162) in order to get a clean save/restore. Tab(-1,254); (flush) is the simplest way to satisfy the requirement.

2011 April, A-Shell 5.1.1210:  New flag BOX_PAR may be used with BOX_WIN and BOX_SVA/BOX_RSA to automatically make the pop-up panel act as the parent to any controls (including TPRINT statements) created until the box is removed (with BOX_RSA+BOX_WIN+BOX_PAR). You could have done this yourself using MX_AUTOPARENT except that MSBOXX does not return an identifier for the panel; the BOX_PAR option overcomes that issue and automatically issues the necessary MX_AUTOPARENT calls.

Note that with BOX_WIN, the box/panel is a GUI control, and thus you cannot output plain text on top of it; use TPRINT, DPRINT, AUI_CONTROL, and other GUI control generation statements instead of PRINT. Furthermore, with BOX_PAR, since the panel acts like a parent, the cursor position of controls and text to be placed on it must be adjusted to be relative to the box/panel rather than the screen. (The overall effect is similar to using a regular dialog box.)

2011 April, 5.1.1210: BOX_SVA with the BOX_WIN option now saves underlying controls, as well as text, and BOX_RSA+BOX_WIN will restore them. This allows BOX_WIN panels to effectively overlay areas containing either plain text or GUI controls, or both.♥B