.LISTCLASS

Begin a list class definition

.LISTCLASS name[, ARRIVE_METHOD(arrive_method)] –
           [, DOUBLE_CLICK_METHOD(double_click_method)] – 
           [, FOOTERS([fline_count[, STATIC]]) –
           [, HEADERS([hline_count[, STATIC]])] [, INPUT_SNAPSHOT]–
           [, ITEMS(item_count)] [, LEAVE_METHOD(leave_method) –
           [, LOAD_METHOD(load_method)] [, NONULL][, OPTIONS(option_string)]

Arguments

name

The name of the list class (maximum 15 characters). This name must be unique within the window library.

ARRIVE_METHOD (arrive_method)

(optional) Specifies that you want the list processor to call the specified arrive_method subroutine whenever an item is accessed (“arrived at”). You can overload this method at runtime with the L_METHOD subroutine. You may want to use ARRIVE_METHOD when you want additional setup performed when the item is accessed. If ARRIVE_METHOD is not specified, no special action is taken when a new item is accessed. See LARRIVE_METHOD / LLEAVE_METHOD for more information.

DOUBLE_CLICK_METHOD (double_click_method)

(optional) Specifies that you want the list processor to call the specified double_click_method subroutine whenever the user double-clicks within the list. You can overload this method at runtime with the L_METHOD subroutine. If DOUBLE_CLICK_METHOD is not specified and the user double-clicks on the current item, the list processor will assume that the item is being selected.

FOOTERS ([fline_count[, STATIC]])

(optional) Specifies the number of footer lines for the list. If not specified, defaults to 0. If the FOOTERS qualifier is present but fline_count is not specified, the line count defaults to 1.

Specify STATIC to indicate that the horizontal display area of the footer will not be adjusted by the L_VIEW subroutine, or by a D_LRIGHT or D_LLEFT request to L_PROCESS, or when the input window display is adjusted to encompass the current input field. The default is not static. For ActiveX Toolkit lists, text is centered in each column by default. If you specify STATIC, however, text will be left-justified in each column.

HEADERS ([hline_count[, STATIC]])

(optional) Specifies the number of header lines for the list. If HEADERS isn’t specified, the default is 0. If the HEADERS qualifier is present but hline_count is not specified, the default line count is 1.

Specify STATIC to indicate that the horizontal display area of the header will not be adjusted by the L_VIEW subroutine, or by a D_LRIGHT or D_LLEFT request to L_PROCESS, or when the input window display is adjusted to encompass the current input field. The default is not static. For ActiveX Toolkit lists, text is centered in each column by default. If you specify STATIC, however, text will be left-justified in each column.

INPUT_SNAPSHOT

(optional) Specifies that the list will maintain input window control information for each item in the list, by using the I_SNAPSHOT subroutine. This option is useful when using input sets in a list but creates unnecessary overhead in other cases (such as selection processing).

If INPUT_SNAPSHOT is not specified, the default action is not to maintain item-specific input window control information.

ITEMS (item_count)

(optional) Specifies that the number of list items to be displayed at one time. If ITEMS is not defined, the default number depends on the available screen-body space between the placement row (inclusive) and the information bar (exclusive). Display items such as borders, headers, and footers are made to fit within this area. If item_count is too large for the screen, the default number is used.

LEAVE_METHOD (leave_method)

(optional) Specifies that you want the list processor to call the specified leave_method subroutine whenever the user leaves a list item. You can overload this method at runtime with the L_METHOD subroutine. You can use LEAVE_METHOD when you want the item to perform additional processing (such as validating the input) when the user leaves it. If LEAVE_METHOD is not specified, no special action is taken when the user leaves the item. See LARRIVE_METHOD / LLEAVE_METHOD for more information.

LOAD_METHOD (load_method)

(optional) Specifies that you want the list processor to call the specified load_method subroutine whenever it loads existing items (on demand) into the list. You can overload this method at runtime with the L_METHOD subroutine. If LOAD_METHOD is not specified, load requests are returned to the calling routine. See also L_PROCESS and LLOAD_METHOD for more information.

On Windows, you must write and use a load_method subroutine to enable scrolling of the list.

NONULL

(optional) Specifies that the list is not allowed to remain empty. A list is null if no items are loaded into it, or if the last list item is deleted. If NONULL is specified, an empty list will cause the L_PROCESS subroutine to return a D_LABORT request, which asks the calling routine to immediately delete the list. The default is to enable a null list.

OPTIONS (option_string)

(optional) Defines an option_string to be used by L_CREATE when instances of this class are created. Specify one or more of the following, separated by commas:

ACTIVEX

Specify that the ActiveX implementation of a Toolkit list will be used. See Specifying the ACTIVEX option (Windows).

GRIDCOLOR ([odd_color][, even_color])

Specify background colors for alternating ActiveX Toolkit list items. See Specifying the ACTIVEX option (Windows).

NOACTIVEX

Specify that a Toolkit list (non-ActiveX) will be used.

NOAUTOSIZE

Suppress automatic sizing of the list when the container is resized. On Windows, the size of the list is not affected by the size of its container and can only be resized using L_RESIZE. This option is ignored on UNIX and OpenVMS systems. See the DTS_LIST Discussion for an explanation of how this feature can be used.

NOBAR

Suppress the list’s vertical and horizontal scroll bars.

On Windows, mouse wheel scrolling works even if you suppress scroll bars with NOBAR, HOHBAR, or NOVBAR.

NOCELLHBAR

Suppress the list’s horizontal scroll bar only when running on UNIX or OpenVMS.

NOCELLVBAR

Suppress the list’s vertical scroll bar only when running on UNIX or OpenVMS.

NOHBAR

Suppress the list’s horizontal scroll bar.

NOVBAR

Suppress the list’s vertical scroll bar.

Discussion

The .LISTCLASS command enables you to define a list class. A list class defines a set of list characteristics. When a list is created in a Toolkit application, its characteristics can be drawn from a given list class.

A list class defines features of lists that are likely to be common across multiple lists. When you define these features in classes, global changes in presentation style are simple. Because you define classes in scripts, global customization of distributed list classes is possible.

The placement of a list can be specified as a list class characteristic using the .PLACEMENT command. The placement coordinates can be overridden when a list is created with the L_CREATE subroutine; or the list can be created without being placed. If so, these coordinates will be retained and used when the list is placed.

If placement is not specified, the default placement is inherited from the associated input window specified in the L_CREATE subroutine.

When using the L_INPUT subroutine on Windows, be aware that the user can change the current list item without control returning to your program first. This means that the state of the input fields and the input set context can be propagated across list items. For example, if your program uses I_INIT to initialize fields in the input set, and the user moves to a different item in the list, the fields are still considered empty. This results in a different redisplay of the data, and validation occurs unexpectedly. There are two ways to solve this problem. You can use the INPUT_SNAPSHOT option to preserve input context and field states for each item, or you can use a list item arrive method to either initialize or display the data in the associated input window (depending on the content of the list item), and then use I_NEXT to establish the correct context.

Specifying the ACTIVEX option (Windows)

Specifying the ACTIVEX option for the OPTIONS qualifier creates an ActiveX implementation of a Toolkit list when displaying and processing the list in a Windows environment. (On UNIX and OpenVMS, this option has no effect; you get a standard Toolkit list. For information on the differences between Toolkit lists and ActiveX Toolkit lists, see Using lists in Toolkit applications.)

For ActiveX Toolkit lists, the GRIDCOLOR odd_color and even_color options are numbers between 0 and 511 that correspond to Synergy color definitions. Odd_color is used for the background color for odd numbered items in the list, and even_color for even numbered items. Both default to white. If an item spans multiple rows, all rows for that item use the same background color.

Additionally, note the following:

Odd_color and even_color must be different colors. (If you want to set the entire background to one color, use the BackColor property. For information, see Published properties for ActiveX Toolkit lists.)
Field attribute settings have precedence over GRIDCOLOR settings and the DarkItemColor and LightItemColor published properties for ActiveX lists.
GRIDCOLOR settings are used only when a list is created. So changes to the Synergy colors used for odd_color and even_color won’t affect lists that exist when the changes are made.

For information on Synergy colors, see Colors and the color palette.

Examples

This example defines a list class named my_list which enables 14 items to be displayed at once. A load method subroutine called my_load_method has been written, which will be called by the Toolkit list processor to load entries into the list.

.listclass my_list, items(14), load_method("my_load_method")
.placement 3, 1
.end

This example defines a list class with one header named my_activex_list which enables 14 items to be displayed at once. A double click method subroutine called my_dclick_method has been written, which will be called by the list processor whenever the user double clicks within the list. This list will use an ActiveX Toolkit list when run on Windows.

.listclass my_activex_list, items(14), -
 double_click_method("my_dclick_method"), - 
 options(activex), headers
.placement 3, 1
.end