PCKLST

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 Raw)

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, wo 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 defined in ashinc:xtree.def.

Symbol	Value	Description
XTF_FKEY	&h00000001	Allow F1-F16 (returning Exitcodes -1 through –16)
XTF_LEFT	&h00000002	Enable Left arrow (Exitcode -40)
XTF_RIGHT	&h00000004	Enable Right arrow (Exitcode –41)
XTF_UP	&h00000008	Enable Ctrl+Up-Arrow on first row (Exitcode -42)
XTF_TAB	&h00000020	Enable Tab (Exitcode -44), and Shift+Tab (Exitcode -35)
XTF_HOME	&h00000040	Enable Home key (Exitcode –45)
XTF_END	&h00000080	Enable End key (Exitcode –46)
XTF_NOAS	&h00000100	Disable auto-shrink of box height to match amount of data. (This flag is ignored by XTREE since it does not support auto-shrink.)
XTF_MODELESS	&h00000200	Leave list box on the screen after exit from the subroutine.
XTF_TIMOUT	&h00000400	For the PCKLST (text mode) only, sets a 200 second timeout—i.e., acts as if user had hit Escape. For XTREE, ignored; use XTR.TIMEOUT instead.
XTF_FST	&h00000800	Fast selection mode. In PCKLST, this means menu items can be selected by entering the minimum number of characters to uniquely identify the item. (Without the XTF_FST flag, Enter would be required to complete the selection.) For XTREE, this means that a single click (completes the selection operation, rather than requiring a double-click or a click followed by Enter).
XTF_XYXY	&h00002000	Interpret the 1st and 2nd parameters (row, col) as starting row, starting col, and the 8th and 9th parameters (strow, endrow) as ending row, ending col. Mandatory for XTREE, optional for PCKLST.
XTF_COLDFX	&h00040000	Indicates that the prompt parameter is actually an XTREE advanced Coldef syntax specification, rather than simply a title string.
XTF_NOSEL	&h00100000	Exit immediately, rather than waiting for the user to make a selection. (This only makes sense in conjunction with XTF_MODELESS; also see xtrctl XTR.opcode)
XTF_DEL	&h00400000	Enable Del exit (Exitcode –47)
XTF_CTRLC	&h01000000	Causes Ctrl+C to set Exitcode 10 (as in INFLD) instead of 1.

 

Symbol	Value	Description
XTF2_PGUPDN	&h00000040	Enable Page-Up / Page-Down (exitcodes 4, 6).
XTF2_DOWN	&h00000080	Enable Ctrl+Down-Arrow on last row (exitcode -43).
XTF2_SAVRES	&h00008000	Causes PCKLST to save the screen area.

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.SBR is actually just a front-end to the vertical menu mode of INMEMO.SBR. 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:

•   XTF2_SAVRES causes PCKLST to save the screen area.

•   XTROP_DELETE operation to clear the screen area used by the list is now supported.

•   XTREE-style title justification codes ("| ","< ","> ") are now supported for the top title.

•   The XTF_NOSEL flag bit is now supported.

•   The SelChgExit=### advanced coldef option is now supported.

•   RFCLR, RBCLR now affect inactive selection bar.

•   The prompt parameter can now use the XTREE advanced Coldef syntax.