Common Properties

The set of list box common properties includes:

TITLE

List boxes do not have titles.

VALUE

A list box has an alphanumeric value.

When VALUE is set, the list is searched for an exact, case-sensitive match with the specified value. If the value is found, it is selected. If an exact match is not found, the list is searched for an exact match regardless of case. If a match is still not found, the list is searched again, this time for the first string that contains the passed VALUE as a leading substring, regardless of case. For example, if your list contains:

  • Capital Building
  • Capital-inc, unit 2
  • Capital-Inc

and VALUE is set to Capital-Inc, the third item is selected. If VALUE is set to CAP, the first item is selected.

On termination of a list box entry, the value is the currently selected list item, or spaces if no item is selected

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

Note: The scroll bar is hidden if the list of items is small enough to be shown on the screen. If this happens, the list box may appear wider than specified, because some systems add the space devoted to the scroll bar into the text area. When enough items are added to the list to require a scroll bar, the text space is reduced and the scroll bar displayed. If you are using the WIN32_NATIVECTLS runtime variable, drop-down list behavior changes. A Windows XP style list automatically expands downward to show up to 30 items at a time, regardless of whether or not it temporarily overlaps a control beneath it. A scroll bar will not appear unless there are more than 30 items.

COLOR

List boxes will use any specified foreground or background color. If either color is omitted, 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 system's color-handling configuration options.

EVENT-LIST, EXCLUDE-EVENT-LIST

EVENT-LIST is an exclusive list of events that are either sent to or withheld (blocked) from the program depending on the value of EXCLUDE-EVENT-LIST. See Common Screen Options for more information.

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.
LOWER Converts all the text in the box to lower-case.
UPPER Converts all the text in the box to upper-case.
PAGED 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 Paged List Boxes in Graphical Controls for a complete description of paged list boxes and an introduction to how they are programmed.
NO-BOX 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 of ACUCOBOL-GT, the default depends on the configuration variable LISTS_UNBOXED.
3-D Causes the list box to appear inscribed into the surface of the screen. This looks similar to the LOWERED frame style. The runtime system uses the background color of the floating window to determine how to draw the frame. The background color is set when the window is created and each time the window is erased. This color must be one of the low-intensity standard colors, except for black (color numbers 2–7). Any other background color will prevent the 3-D effect from displaying. Only boxed list boxes will display 3-D effects. See Frame in Control Types Reference for more information.
NOTIFY-DBLCLICK This 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 special properties 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.
Parent topic: List Box