L_CLASS

Create a list class at runtime

xcall L_CLASS(class_id, class_name, [placemt_row], [placemt_col], [num_items], 
&     [num_headers], [header_static], [num_footers], [footer_static], [no_null], [snapshot],
&     [load_method], [options], [error], [arrive_method], [leave_method] 
&     [, dblclick_method])

Arguments

class_id

The returned class ID. (n)

class_name

The name of the class to create (a maximum of 15 characters). (a)

placemt_row

(optional) The placement row for the list. (n)

placemt_col

(optional) The placement column for the list. (n)

num_items

(optional) The number of items to be visible at one time. (n)

num_headers

(optional) The number of header lines to reserve. (n)

header_static

(optional) The true/false flag that indicates whether the header is to remain static. (n)

num_footers

(optional) The number of footer lines to reserve. (n)

footer_static

(optional) The true/false flag that indicates whether the footer is to remain static. (n)

no_null

(optional) The true/false flag that indicates whether null lists are prohibited. (n)

snapshot

(optional) The true/false flag that indicates whether to take input set information snapshots. (n)

load_method

(optional) The name of an LLOAD_METHOD subroutine you have written. (a)

options

(optional) One or more of the option_string options for .LISTCLASS. (a)

error

(optional) The returned Toolkit error number, or 0 if the list class is successfully created. (n)

arrive_method

(optional) The name of an LARRIVE_METHOD subroutine you have written. (a)

leave_method

(optional) The name of an LLEAVE_METHOD subroutine you have written. (a)

dblclick_method

(optional) The name of an LDBLCLICK_METHOD subroutine you have written. (a)

Discussion

L_CLASS defines a list class at runtime, as opposed to defining one through the .LISTCLASS script command. The class name is then used when creating a list with L_CREATE.

The returned class_id is not needed for subsequent list creation or processing (since L_CREATE identifies the class by name), but you can pass the ID to the U_SAVE subroutine to store the list class in a window library.

Class_name must be unique within the set of windows.

If placemt_row and placemt_col are passed, but the list is not placed when created, these coordinates will be retained and used when the list is placed.

For more information about the snapshot argument, see the .LISTCLASS Discussion.

If passed, load_method is the name of an LLOAD_METHOD subroutine that you have written. L_PROCESS or L_SELECT will call this subroutine to load new items into the list. Using a load method avoids the necessity of satisfying load requests (D_LLOADBOT, D_LLOADTOP) whenever L_PROCESS is called, and also encapsulates your item-loading code.

If any method subroutines are specified, they must be available. In other words, they must either be contained within the current program image, or in an executable library (ELB) that was either linked to or opened with OPENELB. The default behavior, if no load_method is specified for the list, is for L_PROCESS and L_SELECT to return to the caller when new items are needed.

If error is passed, it is returned as 0 if the list class is successfully created. If the list class cannot be created, error is returned with the Toolkit error number. If error is not passed, all errors are fatal.

The following are the errors that can be returned in error. You can use %U_GETWNDERR to get the text of error .

519, DTK_DUPCLASS, “List class class already defined”—A list class with the name passed in class_name already exists.
520, DTK_CLSCREAT. “Cannot create list class class”—The list class could not be created (e.g., because the system ran out of available resources).

Using L_INPUT on Windows

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. Use the INPUT_SNAPSHOT option to preserve input context and field states. If, however, you don’t want the context preserved for each item, 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.

On Windows, the current list item can be interactively changed within a call to a Toolkit subroutine (such as L_SELECT or L_INPUT). To enable you to support change “events,” you can pass the arrive_method and leave_method arguments so the specified subroutines can be called to perform any additional processing required. These method subroutines are also supported on Unix and OpenVMS.

Dblclick_method specifies the name of a double-click subroutine that you have written. If specified, the list processor will call the double-click method subroutine whenever the user double-clicks on an item within the list. You can overload this method at runtime using the L_METHOD subroutine. If dblclick_method is not specified and the user double-clicks on the current item, the list processor will assume that the item is being selected.