MSBOXX

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	&h000001	Clear interior of the box
BOX'BDR	&h000002	Draw border around the box
BOX'SVA	&h000004	Save area used by box (to be restored later)
BOX'RSA	&h000008	Restore area (previously saved)
BOX'COF	&h000010	Leave cursor off on exit
BOX'REV	&h000020	(Not supported under A-Shell)
BOX'FAO	&h000040	Field attributes on/off (at edge of box)
BOX'CHK	&h000080	Return BOXSTS=0 if save/restore supported
BOX'PSA	&h000100	Pop saved area without displaying it
BOX'MAP	&h000400	(Not supported under A-Shell)
BOX'PRT	&h000800	(Not supported under A-Shell)
BOX'ATR	&h001000	Save/restore screen context
BOX'HLI	&h002000	Draw horizontal line (set strow = endrow)
BOX'VLI	&h004000	Draw vertical line (set stcol = endcol)
BOX'DBL	&h008000	Draw double line border around box
BOX'SBU	&h010000	Scroll box up one line
BOX'SBD	&h020000	Scroll box down one line
BOX'SRF	&h040000	Draw line with serifs
BOX'WIN	&h080000	Display pop-up window; see Comments below
BOX_PAR	&h100000	See note in History, below
Definition File: MSBOXX.DEF

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

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.

2004 April, A-Shell 4.9.884:  The operation of the MSBOXX opcode BOX'WIN (to create a GUI-style raised panel box) has been improved to no longer require that the border option be selected, and more importantly, to work over ATE. If selected in a non-GUI environment, the option is just ignored (so you should combine it with whatever other box options you would otherwise use, including BOX'SVA, BOX'RSA, BOX'ERA, etc.)

Note that one of the advantages of BOX'WIN for pop-up boxes is that being a true control, it can overlay other controls, and other controls can overlay it, without the complications that arise when trying to save and restore text boxes in a mixed GUI environment. However, if you do use BOX'WIN, you should only use GUI-style static text and other controls to write within the box.

2004 February, A-Shell 4.9.863:  (Windows) A new opcode option has been added to MSBOXX.SBR to display a GUI-style pop-up window: 524288. This has been added to MSBOXX.BSI as BOX'WIN. When specified, and using the GUI version of the driver, it causes the pop-up box to be created using a static text control with the MBF'FRAME option and the standard "button face" background color (generally gray). The "frame" is much thinner than the normal MSBOXX border, allowing the rows and columns which are normally taken by the border to be used for text if so desired. This style of box is the only kind that can overlap other controls (without causing the underlying controls to have to be hidden). However, if you use this style of box, you should only print within it using TPRINT, DPRINT, or AUI_CONTROL. Any other kind of output will "print through" to the underlying screen layer and not be removed when the box is removed.