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.

Note that in statements that allow for multiple properties, the properties are set in the order specified. Therefore, you can set both INSERTION-INDEX and ITEM-TO-ADD in the same statement, providing you specify INSERTION-INDEX first. For example, the following statement will add a new item to the top of a list box:

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. Note that there is always a column at position "1", so setting position "1" has no useful effect.

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 )

This can also be specified with the RECORD-POSITION construct. The data item is reference by a numeric literal whose value corresponds to the location of the data item within the record. (This construct is covered in detail in Chapter 5.2.5 of the Reference Manual.) For example, the above example would be:

    DATA-COLUMNS = (
        record-position of PHONE-NUMBER,
        record-position of STATE )

Note that you must also specify DISPLAY-COLUMNS to get the columns to display correctly. If you don't, the results are undefined.

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.

Note that you can also use columns to hide data. A column set beyond the right side of the list box is not visible on the screen. You can use this behavior to store information in the list box that your program needs to associate with list items, but that you do not want to be seen by the user. One potential use for this feature is to store a file record's primary key value in the hidden column so that you can retrieve the full record easily when the user selects an item in the list.

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 ½ 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 displayed 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. Note that this does not occur if you use the PROPERTY phrase to supply the property value (by giving its identifying number).

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. Note that this does not occur if you use the PROPERTY phrase to supply the property value (by giving its identifying number).

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.