A LIST-BOX presents a vertical list of items that the user can scroll through and select.
List boxes that do not have the PAGED style are limited to 64K bytes of text. Memory is allocated as needed.
The set of LIST-BOX properties includes:
Common Properties
TITLE
List boxes do not have titles.
VALUE
A list box has an alphanumeric value. On activation, the value is the currently selected list item, or spaces if no item is selected. On output, the value is the first list item that matches the value of the substring input by the user. For example, if your list consisted of the strings "One", "Two", and "Three", an input value of "T", "Tw", or "Two" would cause "Two" to be selected. An input value of "Th" would cause "Three" to be selected. An input value that does not match any item, or a value of spaces, causes all items to be unselected.
SIZE
The LINES setting specifies the number of lines of text that are visible in the list box. The SIZE setting determines the maximum width of the text area as a multiple of the width of the "0" (zero) character of the list box's font. Any overhead needed for the box itself, or any scroll bars, is added to the height and width. The list box handler does not allow partial lines of text to be displayed, so the height of the list box may be reduced accordingly.
When the program executes on a non-graphical system, the values specified in the CLINES and CSIZE phrases, if present, replace the values specified by the LINES and SIZE phrases.
The default LINES value is "5". The default SIZE value is "12".
COLOR
List boxes will use any specified foreground or background color. If either color is omitted, then that color uses a system-dependent default value. On most systems, the default foreground is black and the default background is white. Under Microsoft Windows, the default values are determined by the user's choices in the Control Panel (usually black on bright-white). These system-dependent default colors are not transformed or mapped by the runtime's color-handling configuration options.
STYLES
UNSORTED Normally the items in the list are automatically sorted alphanumerically. Alternatively, the UNSORTED style causes the list to be shown in the order in which the items are added.
PAGED This style specifies that the list box is to be a paged list box. Paged list boxes are typically used when the number of items in the list is too large for a standard list box. See Chapter 3, section 3.9 for a complete description of paged list boxes and an introduction to how they're programmed.
NO-BOX This style removes the box that normally displays around the listed items.
BOXED This style indicates that a box should be placed around a list box. It is the default for graphical versions of ACUCOBOL-GT. For character-based versions, the default depends on the configuration variable LISTS-UNBOXED.
3-D This style behaves identically to the 3-D ENTRY-FIELD style of the same name.
NOTIFY-DBLCLICK This style causes the list box to generate CMD-DBLCLICK events. Normally, double-clicking on an item in the list box has no special effect. If you specify this style, double clicking on an item will generate a CMD-DBLCLICK event. This will usually terminate the current ACCEPT statement and allow your program to act on the selection immediately. You can also use an associated EXCEPTION PROCEDURE in the Screen Section to perform immediate processing. See also the TERMINATION-VALUE and EXCEPTION-VALUE properties below for related information.
NOTIFY-SELCHANGE This style causes the list box to generate NTF-SELCHANGE events. Normally, selecting an item in the list box has no special effect. If you specify this style, a selection change will generate an NTF-SELCHANGE event. This allows your program to act immediately on the new selection.
NO-SEARCH This style affects only paged list boxes. It inhibits the box's built-in search facility. If this style is in effect, the user can move around in the paged list box with the arrow buttons and keyboard keys, but cannot bring up the search box. To use this style within the AcuBench Screen Painter, add it in the "Additional Properties" box. (create)
Special Properties
ITEM-TO-ADD (alphanumeric) This property provides a way of adding items to the list box. Any time you create or modify a list box, the ITEM-TO-ADD property is examined. If it is not spaces, then its value is added to the items in the list box. The examples below demonstrate how to use this property to initially populate a list box.
RESET-LIST (numeric) This property allows you to empty a list. If this property is "0", it is ignored. If it is non-zero, then all the items in the list are deleted.
MASS-UPDATE (numeric) This property improves the efficiency of making large content changes to the list box.
Normally, the runtime immediately repaints a list box when the program adds or removes an item from the box. If you are making several changes in a row, this process can be slow. To improve performance, set the MASS-UPDATE property to "1". While set to "1", MASS-UPDATE inhibits repainting of the box due to changes in the box contents. To repaint after you have finished your changes, set MASS-UPDATE to zero ("0").
For example, this code could be used to initially populate the contents of a list box:
MODIFY LIST-BOX-1, MASS-UPDATE = 1
PERFORM VARYING IDX FROM 1 BY 1
UNTIL IDX > LIST-BOX-SIZE
MODIFY LIST-BOX-1,
ITEM-TO-ADD = LIST-BOX-ITEM( IDX )
END-PERFORM
MODIFY LIST-BOX-1, MASS-UPDATE = 0
In this example, the list box will not be repainted until the last MODIFY statement executes.
ITEM-TO-DELETE (numeric) Setting this property to a non-zero value deletes the corresponding item in the list box. The first item in the list is item number "1" and each item is numbered sequentially thereafter. Deleting a non-existent item has no effect.
INSERTION-INDEX (numeric) Setting this property to a positive value affects the location of the next item added to the list box. When it is set to zero (the default), items are added in sort-order, or to the end of the box if the list box has the UNSORTED style. When INSERTION-INDEX is positive, the next item added is placed immediately before the corresponding item instead. For example, setting this to "1" causes the next item to be inserted at the top of the list. You can place an item at the end of the list by specifying an index one greater than the number of items in the list. When you finish adding the next item, INSERTION-INDEX automatically resets itself to a value of zero.
MODIFY LIST-BOX-1,
INSERTION-INDEX = 1,
ITEM-TO-ADD = "New top item"
SEARCH-TEXT (alphanumeric) This property is used only in conjunction with paged list boxes. SEARCH-TEXT returns the current value of the user-supplied search text. Normally, this property is used in an INQUIRE statement when you implement a response to the NTF-PL-SEARCH event (which indicates that the user wants to search for a particular text string in the list box). See Chapter 3, section 3.9 for a complete description and code example.
DATA-COLUMNS (numeric) This property describes where each column begins in the data added to the list. Columns are defined by character positions in the raw data, with the first character being position "1". For example, the following data item:
01 LIST-DATA.
03 NAME PIC X(20).
03 PHONE-NUMBER PIC X(15).
03 STATE PIC X(2).
would normally be displayed in three columns, one at position "1" (NAME), one at position "21" (PHONE-NUMBER), and one at position "36" (STATE). Each time you set DATA-COLUMNS to a positive value, a new column is created at that position. Setting DATA-COLUMNS to zero clears all the existing column definitions.
Typically, you specify DATA-COLUMNS by enclosing a list of columns in parentheses. This causes the compiler to generate code to set each column in turn. For example, a setting that would match the preceding example would be:
DATA-COLUMNS = ( 21, 36 )
DISPLAY-COLUMNS (numeric) This property describes where each DATA-COLUMN will display in the list box. The first column always displays in column "1". Additional columns display at the locations set by DISPLAY-COLUMNS. Columns are measured with the standard font measure (i.e., the width of the character "0" in the list box's font). Each time you set DISPLAY-COLUMNS to a positive value, a new display column is defined. Setting DISPLAY-COLUMNS to "0" clears all of the columns (except column 1).
If you are using a proportionally spaced font, you should provide enough space in each column to allow for wider-than-average data. You will also want to provide some white space between columns. To continue the example given under DATA-COLUMNS above, you might code the following:
DATA-COLUMNS = ( 21, 36 )
DISPLAY-COLUMNS = ( 31, 51 )
In this example, the first column, which is 30 characters wide in the display, accommodates a 20-character data source, and the second column, which is 20 characters wide, accommodates a 15-character data source.
Data contained in a column cannot overflow the allocated space. If the data is too large to be fully displayed, the data is truncated. Therefore, you should always set your columns wide enough to hold the largest data item.
ALIGNMENT (alphanumeric) This property specifies the alignment of data in each column. Like DATA-COLUMNS and DISPLAY-COLUMNS, each time you assign this property, you affect a new column. Allowed values are "L" for left alignment, "R" for right alignment, "C" for centered alignment, and "U" for unaligned. Equivalent lower-case values are also allowed, as are any words that start with the appropriate letters (thus, you can spell out "left", "right", and "center" if you want). For example, to establish a left-aligned column followed by two right-aligned columns, you would use:
ALIGNMENT = ( 'L', 'R', 'R' )
To empty the alignment list (to establish new alignments, for example) assign an alignment value of space (" "). Left alignment differs from unaligned in that leading spaces are removed from left-aligned data, but not from unaligned data. Any column that does not have an alignment specified for it is unaligned.
SEPARATION (numeric) This property establishes a blank region at the end of each column. This has the effect of creating a uniform separation space between each column and prevents data from visually running together. When data is too large to fit in the allocated space, the data is truncated to the column width minus the separation space.
Like DATA-COLUMNS, each time you assign a value to this property, you set the separation amount for a new column. The separation is expressed in 10ths of characters. For example, to establish a 1/2 character separation, use a value of "5". On character-based systems, the separation is rounded down to the nearest whole character. The blank region specified appears at the end of the column. Data is never displayed in the separation region, it is truncated if need be. Also, the separation region defines the edge from which right and center justification are computed. To reset the separation list for a box, assign the value "-1". Unspecified columns use a default separation value. This value is set by the configuration variable COLUMN-SEPARATION.
DIVIDERS (numeric) When set, this property causes divider bars to be displayed between columns. Like DATA-COLUMNS, each time you assign a value to this property, you establish the divider for a new column. The value assigned is the width of the divider, in pixels. A width of zero means that there will be no divider. The divider appears after the column, immediately before the beginning of the next column (there is a small space between the divider and the next column's text). To reset the list of dividers, assign a value of "-1". The divider's color is the shadow color of the list box (usually dark gray or black).
SELECTION-INDEX (numeric) This property, when set, causes the list box selection to change to the indicated item. Items are numbered sequentially from the top of the list box, starting at "1". Setting this value to "-1" clears any selection. Values beyond the number of list box items are undefined.
When queried, this property returns the item number of the current selection, or "-1" if no item is selected.
Using SELECTION-INDEX to change the list box focus causes a faint dotted-line box to appear around the selected item on graphical systems. On character-based systems, the text cursor is diplayed at the end of the selected item. The end user presses the space bar to choose the item.
THUMB-POSITION (numeric) This property, when set, causes the list box to display the line number of the item on top of the list box, scrolling the latter if necessary. Items are numbered sequentially from the top of the list, starting at "1". Setting THUMB-POSITION to a value greater than the actual number of lines in the list box or to a value less than "1" has no effect.
When queried, this property returns the line number of the item currently displayed on top of the list box.
QUERY-INDEX (numeric) This property is used only in conjunction with the ITEM-VALUE property described below. This property determines which list box item to return information about. Items are numbered sequentially from the top of the list box, starting at "1".
ITEM-VALUE (alphanumeric) This property, when queried, returns the value of a list box item. The item returned is determined by the current value of QUERY-INDEX (see above). If QUERY-INDEX does not correspond to a valid item, then nothing is returned.
For example, to determine the value of the first item in a list box, perform the following statements:
MODIFY LIST-BOX-1, QUERY-INDEX = 1
INQUIRE LIST-BOX-1, ITEM-VALUE IN MY-ITEM
TERMINATION-VALUE (numeric) This property produces the same behavior as the TERMINATION-VALUE push button property, except that it acts on the CMD-DBLCLICK event instead of the CMD-CLICKED event. This property is used only when the NOTIFY-DBLCLICK style is also used. The compiler applies the NOTIFY-DBLCLICK style automatically if this property is explicitly named when the control is initially created.
EXCEPTION-VALUE (numeric) This property produces the same behavior as the push button property of the same name, except that it acts on the CMD-DBLCLICK event instead of the CMD-CLICKED event. This property is used only when the NOTIFY-DBLCLICK style is also used. The compiler applies the NOTIFY-DBLCLICK style automatically if this property is named when the control is initially created.
SORT-ORDER (numeric) This property applies to paged list boxes only. It determines whether the case of the data items will be considered as the user searches for a data item. It can take one of four values:
PL-SORT-DEFAULT (0) Use the default sort order. Currently this is the same as PL-SORT-NATIVE-IGNORE-CASE
PL-SORT-NONE (1) Every character the user types results in a notification to the COBOL program.
PL-SORT-NATIVE (2) The paged list is searched as well as it can, and case is considered. If the item that the user has entered is on the current page, it is selected.
PL-SORT-NATIVE-IGNORE-CASE (3) The paged list is searched as well as it can, independent of case. If the item that the user has entered is on the current page, it is selected.
Any other value results in undefined behavior.
Events
CMD-DBLCLICK
CMD-GOTO
CMD-HELP
MSG-VALIDATE
NTF-SELCHANGE
For paged list box:
NTF-PL-FIRST
NTF-PL-LAST
NTF-PL-NEXT
NTF-PL-PREV
NTF-PL-NEXTPAGE
NTF-PL-PREVPAGE
NTF-PL-SEARCH
Using Special Keys
When list box has the input focus, the Page-Up and Page-Down keys can be used to scroll the list box. Setting KEYSTROKE configuration entries does not affect these actions.
Examples
This example creates a list box and fills it with the contents of a table:
PERFORM VARYING IDX FROM 1 BY 1 UNTIL IDX > TABLE-SIZE
DISPLAY LIST-BOX, LINES 5, SIZE 30, HANDLE IN BOX-1.
MODIFY BOX-1, ITEM-TO-ADD = TABLE-ITEM( IDX )
END-PERFORM.
The following Screen Section entry and accompanying code perform the same actions:
PERFORM VARYING IDX FROM 1 BY 1 UNTIL IDX > TABLE-SIZE
03 LIST-1, LIST-BOX, LINES 5, SIZE 30,
VALUE SELECTED-ITEM, ITEM-TO-ADD = ADD-ITEM.
MOVE TABLE-ITEM( IDX ) TO ADD-ITEM
DISPLAY LIST-1
END-PERFORM.
MOVE SPACES TO ADD-ITEM.
The first time through this loop, the list box is created (if it has not already been created). Subsequent iterations of the loop modify the existing list box.