# MSBOXX

> [HTML Version](msboxxsbr.htm)

_Revised December 2023; see History_

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

MSBOXX performs text-based box drawing operations, including the ability to save and restore the area underneath the box.

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

| **Symbol** | **Value** | **Meaning** |
|------|------|------|
| BOX\_ERA | \&h00000001 | Clear interior of the box |
| BOX\_BDR | \&h00000002 | Draw border around the box |
| BOX\_SVA | \&h00000004 | Save area used by box (to be restored later) |
| BOX\_RSA | \&h00000008 | Restore area (previously saved) |
| BOX\_COF | \&h00000010 | Leave cursor off on exit |
| BOX\_REV | \&h00000020 | (Not supported under A-Shell) |
| BOX\_FAO | \&h00000040 | Field attributes on/off (at edge of box) |
| BOX\_CHK | \&h00000080 | Return BOXSTS=0 if save/restore supported |
| BOX\_PSA | \&h00000100 | Pop saved area without displaying it |
| BOX\_MAP | \&h00000400 | (Not supported under A-Shell) |
| BOX\_PRT | \&h00000800 | (Not supported under A-Shell) |
| BOX\_ATR | \&h00001000 | Save/restore screen context |
| BOX\_HLI | \&h00002000 | Draw horizontal line (set _strow_ = _endrow_) |
| BOX\_VLI | \&h00004000 | Draw vertical line (set _stcol_ = _endcol_) |
| BOX\_DBL | \&h00008000 | Draw double line border around box |
| BOX\_SBU | \&h00010000 | Scroll box up one line |
| BOX\_SBD | \&h00020000 | Scroll box down one line |
| BOX\_SRF | \&h00040000 | Draw line with serifs |
| BOX\_WIN | \&h00080000 | Display pop-up window; see _Comments_ below |
| BOX\_PAR | \&h00100000 | See note in _History_, below |
| **Definition File: **[ashinc:msboxx.def](https://bitbucket.org/microsabio/soslib/src/master/907016/msboxx.def) | | 

[Hex-Decimal Values](hex-decimalvalues.htm.md)



_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**

The A-Shell implementation of MSBOXX is nearly equivalent to the original version included with [TRACKER](terminology.htm.md#tracker-in-terminology). Note that it simplifies box drawing operations, you can perform all of the same operations directly in ASB code using Print [Tab Functions](tabfunctions.htm.md).

**See Also**

•	[ABOX](aboxsbr.htm.md)[XS](keyword-types.htm.md): An alternate box-drawing routine

•	[MSGBOX](msgboxsbr.htm.md): Windows-style message box

•	[INMEMO](inmemo_sbr.htm.md): Free-form and menu text inside a box

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