PCKLST

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

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

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; two element array of B,4)

may be used to specify zero or more options from the tables below. See 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 PgUp/PgDn (exitcodes 4, 6).
XTF2_DOWN	&h00000080	Enable Ctrl+Down 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

INIX

Documentation added May 2016

xcall INIX, inifile, opcode, section, item {, value, dftvalue}

INIX.SBX reads/writes from standard "INI" files, which are ordinary text files, typically with a .INI or .CFG extension, which are made up of one or more groups (sections) of item=value pairs as follows: xe "INIX.SBR"

[section]

item1=value

item2=value

etc.

Because these files can be edited in a standard text editor, and because comment lines beginning with a semicolon may be inserted anywhere, the format is both easy to use and self-documenting. There is no particular limit to the number of items or sections, but each item name within a section must be unique.

Source, samples and related functions can be found in SOSLIB:[907,26].

Parameters

inifile (String) [in]

File spec of the INI file.

opcode (Num) [in]

Operation to perform:

Value	Meaning
0	Read single item=value pair
1	Write single item=value pair
2	Delete single item=value pair
3	Delete complete section

In addition, you may add either or both of the following options in the ATE environment:

Value	Meaning
+16	redirect the operation to the ATE client
+32	first sync INIX.SBX from the server to the ATE client

section (String) [in]

Name of section; without the brackets, case sensitive

item (String) [in]

Name of item to read or write; case sensitive

value (String) [in/out]

For the read operation, the value is returned here. Note that if the item is not found within the specified section, the default value will be returned here, assuming the dftvalue parameter was specified. For the write operation, this will be the value to write.

dftvalue (String) [in]

For the read operation, supplies the default value of the item if the item is not defined

Comments

When writing, if the file does not exist, it will be created, and if the specified section does not exist, the section and item will be added to the end of the file. For example:

xcall INIX, "foo.ini", 1, "Favorites", "Beatle", "Ringo"

If the foo.ini file didn't previously exist, then after the above call, it would exist and contain:

[Favorites]

Beatle=Ringo

If we then wrote another item using ...

xcall INIX, "foo.ini", 1, "Favorites", "Position", "On Top"

... the file would be updated to contain:

[Favorites]

Beatle=Ringo

Position=On Top

Note that neither the order of the sections nor the order of the items is significant.

If we then retrieve three values from the file with the following ...

xcall INIX, "foo.ini", 0, "Favorites", "Beatle", fabguy$, "Paul"

xcall INIX, "foo.ini", 0, "preferences", "Position", pos$, "upside down"

xcall INIX, "foo.ini", 0, "Favorites", "Musician", player$, "Leadbelly"

The results would be:

? fabguy$ ! "Ringo"; (default "Paul" ignored)

? pos$ ! "upside down" (no such section "preferences"; use default)

? player$ ! "Leadbelly" (no such item "Musician"; use default)

Attempting to read from a non-existent INI file is equivalent to attempting to retrieve non-existent items; you get back the default value specified in each read operation, or "" if no default specified.

Despite the lack of order or indexing, INIX is quite efficient, particularly at reading, since the file gets cached in memory on the first access. Updates to the file do require the entire file to be rewritten, but this is still reasonably efficient, particularly if the total file size is "reasonable" (say, under 32K or so), and if read operations outnumber writes, as they usually do with these kinds of configuration files.

INIX.SBX was initially created and contributed to the SOSLIB by Steve Evans. It has since been adopted as a standard A-Shell routine, and is used extensively by many A-Shell modules. The source is available in [907,26] of the SOSLIB repository.

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.BP in [908,21] of the EXLIB 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 PCKLST.BP[908,21] in the SOSLIB 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 the 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.