A-Shell Reference

xcall PCKLST, row, col, answer, array, maxcnt, prompt, exitcode {,strow, endrow, flags, file, mmoclr}

PCKLST displays a list of items in a box (aka a "pick list"), optionally waiting for the user to select one. Besides simplifying this common user interface element, it can operate in either text or GUI modes, making the decision at runtime based on external factors, and with a good deal of compatibility between them.

In GUI mode, PCKLST acts as an alias for a simple selection XTREE, while in text mode it acts as a wrapper for the vertical menu mode of INMEMO.

Developers committed to the GUI environment should consider PCKLST deprecated and just use XTREE directly, while those interested in both text and GUI (or text only) should use PCKLST. For information on the differences between PCKLST and XTREE, and how PCKLST/XTREE handles text versus GUI issues, see the note on those subjects in XTREE.

Parameters

row, col  (Num)

If XTF_XYXY is not specified in flags, these are the locations where the ordinary field input would have taken place. The pick list box is drawn around the position where the field was or would have been (to give it the flavor of a drop-down box). If XTF_XYXY flag is specified, these are interpreted as the top left character position of the box (i.e. starting row, starting col).  

answer  (Num)

On exit, answer is set to the Row number of the selection (first row is numbered 1). On input, answer specifies the default position of the selection bar. Range is limited to 0-65535.

array  (String array or BLOB)

is an array of strings containing the choices for the pick list. The end of the array is marked by the first null entry or maxcnt. Note that the array element size must be large enough to accommodate at least one trailing null on each element. Any text in an array element following a backslash will be treated as "hidden text", meaning that it will not be displayed (nor used in determining the box display width). See note in History, below.

maxcnt  (Num)

is the maximum number of elements in the array.

prompt (String)

If XTF_COLDFX is not specified in flags, contains the string to display in the top border of the box as a title or prompt. If the string contains an embedded CHR$(13), the remainder of the string will go on the bottom border of the box. See the documentation on XTF_COLDFX for details on the interpretation of this parameter when XTF_COLDFX is specified.

exitcode  (Signed Num)

will return a code indicating how the pick list was exited, with 0 indicating the normal exit via the Enter key, and 1 indicating Escape. See the flags parameter below for enabling other exit keys.

strow, endrow  (Num)

if specified, determine the top and bottom display position of the box. Otherwise the box is likely to extend both above and below the row specified by the row parameter, according to some kind of primitive internal heuristics. (Set to 0 as a placeholder if needed for subsequent parameters.)

If the XTF_XYXY bit is set in the flags parameter, strow and endrow are reinterpreted as the ending row and ending column (bottom right corner) of the box, whose top left corner will be set by row and col. This is the more traditional method for specifying the coordinates of a box, as used by XTREE.

flags (Num, two-element array of B,4)

may be used to specify zero or more options from the tables below. See XTREE XTREE Flags for details on mapping this parameter. Note that while this parameter is generally compatible between PCKLST and XTREE, many of the XTREE flags are ignored by PCKLST. To simplify, the tables below list only the flags that are recognized by PCKLST, or for which the interpretation differs between PCKLST and XTREE. The XTF_xxx symbols are def!ined in ashinc:xtree.def.

 

Hex-Decimal Values

 

file  (String)

specifies a sequential file to be used instead of the Array parameter. When non-null, the interpretation of Array, Maxcnt, and Answer parameters changes as follows. Array becomes an ordinary string which is used to pass in the default selection (text) and to get back the item chosen by the user. Answer and Maxcnt are then ignored (with the actual contents of the file being examined to determine Maxcnt and the maximum width).

mmoclr

may be used to specify a set of colors for the various parts of the pick list display. It is equivalent to the INMEMO parameter of the same name, which is not surprising, since PCKLST is actually just a front-end to the vertical menu mode of INMEMO. The format of MMOCLR is:

MAP1 MMOCLR

  MAP2 BFCLR,B,1,-1          ! Border Foreground

  MAP2 BBCLR,B,1,-1          ! Border Background

  MAP2 TFCLR,B,1,-1          ! Text Foreground

  MAP2 TBCLR,B,1,-1          ! Text Background

  MAP2 AFCLR,B,1,-1          ! Arrow Foreground

  MAP2 ABCLR,B,1,-1          ! Arrow Background

  MAP2 PFCLR,B,1,-1          ! Prompt Foreground

  MAP2 PBCLR,B,1,-1          ! Prompt Background

  MAP2 WFCLR,B,1,-1          ! Warnings & messages Foreground

  MAP2 WBCLR,B,1,-1          ! Warnings & messages Background

  MAP2 SFCLR,B,1,-1          ! Orig. Status line Foreground

  MAP2 SBCLR,B,1,-1          ! Orig. Status line Background

  MAP2 RFCLR,B,1,-1          ! Inactive selection bar - see Comments

  MAP2 RBCLR,B,1,-1          ! Inactive selection bar - see Comments

 

The individual fields within MMOCLR are shown above initialized to -1, which is what you must do to get default colors, since color 0 is black. (Specifying MMOCLR with all the fields un-initialized will result in a not-very-interesting black on black display.)

 

Comments

If XTF_XYXY not specified, the width of the box will be determined by considering the maximum length of the top and bottom prompts and the data items (not counting any hidden text). If XTF_XYXY is specified, then the coordinates of the box are explicitly determined by the row,col (upper left) and strow,endrow (interpreted as lower right row/col) parameters.

Rather than setting colors in individual calls to PCKLST, it would be easier to set them globally in the LIB:INI:CLR file. See Configuration for more details.

When the XTF_COLDFX flag is specified, the prompt parameter is assumed to be in the format of an XTREE advanced Coldef syntax definition with a single column. From this string, the ctitle field is extracted and used for the top title. (cpos is ignored and assumed to be 1; cwidth must be greater than or equal to the actual width of the elements of array; cformat is ignored.) The main advantage of using this alternate form is to make it easier for a program that operates in both text and GUI modes to take advantage of the features of XTREE without breaking PCKLST compatibility. PCKLST will ignore all of the Advanced Coldef Options that it doesn't understand, but there is one that it does: SelChgExit=###. For example:

prompt = "1~20~Selections~S~SelChgExit=155~~"

The above example would set the title to "Selections", and tell PCKLST to exit with exitcode -155 whenever the selection changes.

Inactive selection bar colors: Normally, when you exit from PCKLST, the bar indicating the selected item remains displayed, exactly as when the menu was active. This is typically desirable, or doesn't matter, but there are some situations where it is useful to provide some visual indication that the list (and selection process) are no longer active. XTREE handles this by changing the standard selection bar (dark blue) to light gray. PCKLST provides you an option to redisplay the selection bar in a different color scheme, by setting the RFCLR and RBCLR fields of the mmoclr structure to the desired colors. If left at the default values of -1, the selection bar is left as is.

See the sample program PCKMNU in EXLIB:[908,21] for an example of a two-level menu program using PCKLST which operates in either text or GUI mode.

PCKLST supports a maximum of 32K rows.

 

Example

The following screens are from a single menu implementation, using two side-by-side PCKLST controls, as it appears in text and GUI modes. See PCKMNU in EXLIB:[908,21] for the actual program.

 

 

Background and Additional Notes

Originally, PCKLST was created to provide a simplified way of accessing INMEMO's menu mode with the idea of upgrading a functionally equivalent INFLD operation to be more user friendly. In other words, rather than call INFLD to have the user type one of the allowed options, the program could call PCKLST to perform the same function—input a field—but in a way that allows the user to easily see the choices and select one without actually typing it. For example:

Screen save/restore was built in to PCKLST, so there was no need to worry about the parts of the screen that would be temporarily covered by the pick list (making it easier to upgrade a screen designed to allow only a single line for the input field).

With the advent of GUI capabilities in A-Shell, a more powerful Windows list/selection control (XTREE) was implemented, but with the same parameter interface. This allows A-Shell to redirect calls to PCKLST to the XTREE if the environment supports GUI and the feature is enabled in miame.ini (via SBR=PCKLST_GUI). Over time, XTREE grew to support so many extended capabilities unrelated to PCKLST that it is now difficult to recognize the parts of XTREE that are compatible with, or even related to PCKLST. So we've tried to keep it simple for PCKLST developers by keeping separate documentation, while trying to note the areas of particular similarity or difference between the two routines.

 

History

2011 June, A-Shell 5.1.1221 and 1220: