A-Shell Reference

xcall SCRSTS, opcode {params}

The parameter syntax varies with the opcode: .

xcall SCRSTS, SCROP_INIT, srow, scol, erow, ecol{, parentid, sflags, title, closecmd, coldef, xt'kbdstr, xt'flags, ctlid}

xcall SCRSTS, SCROP_ADD, msgfmt, arg1, ... argN

xcall SCRSTS, SCROP_TMADD, msgfmt, arg1, ... argN

xcall SCRSTS,SCROP_SCROLL {,msg, exitcode}

xcall SCRSTS,SCROP_CLR

xcall SCRSTS,SCROP_DEL

SCRSTS.SBX outputs a status message to a window, scrolling previous messages up. Three variations are supported, depending on flags and environment:

Some examples using SCRSTS are provided below. Source, additional samples and related functions can be found in SOSLIB:[907,20].

Parameters

opcode (Num)  [in]

specifies the operation using one of the options from the following table:

 

srow,scol,erow,ecol (Num)  [in]

specify coordinates of the rectangle in normal or milli-units

sflags

takes MBF_xxxxx flags (from ashell.bsi); the only ones of interest so far are MBF_DIALOG and MBF_MODELESS, which, together cause the scrolling status control to be placed inside its own modeless dialog window (ignored in text mode). Also, MBF_LISTBOX causes GUI version to use XTREE instead of INFLD, eliminating the scrolling limit

title

title string to display in the dialog; ignored unless sflags contains the MBF_DIALOG option.

closecmd

if MBF_KBD and MBF_SYSMENU flags included in sflags, then closecmd determines what happens when X clicked (if "", then dialog is closed internally; else string is sent in place of the normal ESC) (Virtual click codes supported)

coldef

can be a legal XTREE advanced column definition, if MBF_LISTBOX (The default is "1~512~ ~S~~") Warning: if you define any columns, it is up to you to pass subsequent MSG strings formatted to be compatible with the definition). Also note that if the header fields are all blank, the header row will be removed entirely.

xt'kbdstr

if MBF_KBD and MBF_LISTBOX defined, clicking on the control will send this string (which applications would typically responsd to by calling SCROP_SCROLL).

xt'flags

optional XTREE flags (if MBF_LISTBOX)

xt'ctlno

B,2 optionally returns XTREE control ID (XTR.CTLNO) or INFLD AUI ID

When the XTREE option is requested (see Using XTREE with SCRSTS), three additional optional parameters can be passed to the SCROP_INIT call:

xt'kbdstr (String,10)

sets the XTR.KBDSTR member of the xtrctl structure, so that clicking on the status control sends the specified string. This can be useful if you want to allow the user to manipulate the status window, such as to sort, select, etc. This probably only makes sense in conjunction with a coldef that defines relevant features such as columns, popup menus, etc. The application would normally call the SCROP_SCROLL opcode to in response to receiving the XT'KBDSTR.

xt'flags

may be used to specify additional XTREE flags, such as perhaps XTF_MSEL, etc.

ctlid

will return the XTREE control number (XTR.CTLNO), or in the case of INFLD, the AUI control id. This would only be of interest in sophisticated situations where you wanted to bypass SCRSTS.SBX and operate on the control directly using XTREE or INFLD.

 

These parameters apply only to the SCROP_ADD and SCROP_TMADD:

msgfmt  (String)  [in]

The message to output. May contain zero or more of the following special field markers, some of which are supplied by the next parameter in sequence (see arg1,...argN and Examples below):

 

arg1,...argN  (various types)  [in]

These arguments are plugged into the %d, %s, and %x field markers from msgfmt

These parameters apply only to the SCROP_ADD and SCROP_TMADD:

msg  (String)  [in]

A string message to add to the bottom of the list. For text mode, the list is scrolled up one line to first to make room. For GUI mode, the scroll operation is automatic and thus this opcode is typically not used, although when it is used, it has the effect of suspending the application and putting the focus on the list control (allowing the operator to perform any operations supported internally by the control itself). To exit back to the application the user must issue some kind of exitcode (such as ESC); see exitcode.

exitcode  (Signed Num)  [out]

When specified in GUI mode, the standard XTREE exitcode value will be returned here, indicating how the user exited from the state of having the focus on the message list.

 

Examples

Display/add a message to the window:

xcall SCRSTS, SCROP_ADD, msgfmt {,arg1,...argN}

Clear the message window:

xcall SCRSTS, SCROP_CLR

Delete the message window (restore area in text mode)

xcall SCRSTS, SCROP_DEL

(If message window created inside its own dialog, dialog will be automatically deleted)

Allow user to scroll/activate the window.

xcall SCRSTS, SCROP_SCROLL {,msg{,exitcode}

Extended Example

The following example, from the actual AshLPD utility, illustrates the variation of SCRSTS based on XTREE, and includes the relatively advanced feature of using XTREE foreground row colors to code the various types of messages.

The initialization code for this image is:

! Columns 1-8 are the hh:mm:ss; 10 is the color code

COLDEF = "0~0~ ~H~RGBfg=200,200,220,D~"     ! D = Debug

COLDEF = COLDEF + "RGBfg=250,100,0,E~"      ! E = Error (Red Orange)

COLDEF = COLDEF + "RGBfg=255,0,0,F~"        ! F = Fatal (Red)

COLDEF = COLDEF + "RGBfg=0,0,204,I~"        ! I = Info (Blue)

COLDEF = COLDEF + "RGBfg=100,100,180,L~"    ! L = Low level info (gray)

COLDEF = COLDEF + "RGBfg=0,0,0,P~"          ! P = Printing msg (black)

COLDEF = COLDEF + "RGBfg=210,0,210,W~~"     ! W = Warning (yellow)

COLDEF = COLDEF + "1~8~ ~S~~10~1~ ~Hc~~11~120~ ~S~~"  ! column layout of msgs

xcall SCRSTS,SCROP_INIT,3,5,20,75,0,SFLAGS,"","",COLDEF    

 

Messages are added with calls such as the following one. (Note that the color code letter, "I" in this case, indicating Info (Blue), is just sandwiched at the start of the message (matching the coldef layout set up above).

xcall SCRSTS,SCROP_TMADD,"IPerforming housekeeping..."

xcall SCRSTS, SCROP_TMADD, "I Archive for %d day(s), age cutoff = %d seconds", CFG'ARCHIVE, cutoff

 

Comments

The name (SCROLL) is slightly misleading because in GUI mode, you could scroll without this, but it is necessary in text mode, and in XTREE mode it activates the control allowing other features (such as sorting, selecting, etc. to take place). If exitcode is specified, returns exitcode, if any.

Stores data between calls using memory module SCRSTS.MEM (meaning that currently there can be only one of them active per A-Shell instance.)

Note that in text mode, if the height is >= 3, we use a border (which occupies 2 of the allowed rows). Otherwise no border. Also, on opcode 0, we save the area, and restore it on opcode 3.

The SCROP_SCROLL operation now supports the return of an exitcode:

xcall SCRSTS, SCROP_SCROLL, msg, exitcode

Since the SCROP_SCROLL opcode actually puts the focus on the status control, the exitcode will be that which you would have gotten from XTREE, INFLD, or INMEMO, depending on the environment. This would probably be most useful if you defined a PopupMenu, which returned interesting exitcodes.

The sample program REGPTR in EXLIB:[908,29] illustrates some of the capabilities of SCRSTS.

Using XTREE with SCRSTS

SCRSTS.SBX 1.3(108), A-Shell’s scrolling status window handler, supports an option to use XTREE rather than INFLD to display the scrolling status window. To specify XTREE, you must set the MBF_LISTBOX bit in the sflags parameter when creating the scrolling status window. An optional new parameter allows you to specify an XTREE column definition string:

xcall SCRSTS, SCROP_INIT, srow, scol, erow, ecol {,parentid, sflags, title, closecmd, coldef}

The rest of the SCRSTS opcode formats are unchanged.

Although the XTREE version actually has more overhead (XTREE is a vastly more complex control than the multi-line edit control used by INFLD), here are some of the reasons why you might prefer it:

Also note that if any of the column header fields in coldef are not blank, then the normal column header bar will be displayed. Otherwise it will not (making it more like a typical scrolling status window).

The sample program TSTSCR.BP in SOSLIB:[907,20] sample program has been updated to allow easy experimentation with the new version.