Defining lists

This topic includes the following sections:

 

To set up a list, you must first define what kind of list it will be (Toolkit list or ActiveX Toolkit list), define how the list will look, and specify any methods you will write for the list. To do this, you must define a list class (or accept default list characteristics), and you must create a special input window for the list.

In addition to the data that’s displayed in a list (display data), you can add buttons to a list (using L_BUTTON and L_BUTTONSET), and you can associate a data buffer with each item in a list. The data in such a buffer is called non-window data. Non-window data doesn’t appear in the list, but it’s stored and retrieved with the display data.

Specifying and determining the list type

By default, lists are created as Toolkit lists. If you want an ActiveX Toolkit list, do one of the following:

To find out if a list is actually instantiated as an ActiveX Toolkit list, call L_STATUS with D_LACTIVEX or D_LAXCTRL. Both options return a value of 0 unless the list is currently instantiated as an ActiveX list. Based on this information, you can then alter column headings, avoid invoking methods and properties when they don’t apply to the list type, and so forth.

The list class: specifying general list characteristics

By defining a list class, you can specify the following characteristics of your list:

You can also associate methods with a list. You can specify

Creating a list class

There are two ways you can define a list class: in a script file or at runtime. To define a list in a script file, use the .LISTCLASS command. To define a list class at runtime, use the L_CLASS subroutine.

When you create the list, you’ll pass the name of the list class to L_CREATE. (If you don’t pass the list class name, which is optional, the list will have the default characteristics documented in .LISTCLASS and L_CLASS.) Once you’ve defined a list class, you can use it as the basis for one or more lists in your application. List classes can help standardize your user interface and simplify global changes to your lists.

Note the following:

The input window: specifying the list title and the appearance of individual list items

To specify the appearance and layout of individual list items, you must create an input window that defines the layout of one list item. For example, the following input window definition specifies three fields, which will result in a list with three columns:

.input detlstimp, 1, 49
.repository_structure ORDER_DETAIL
.field OD_PRODUCT, noprompt, fpos(1, 5), nodrill_method
.field OD_ORD_QTY, noprompt, fpos(1, 20)
.field OD_PRICE, noprompt, fpos(1, 35)
.end

This example would result in a list in which each list item takes up only one row, which is the most common scenario. List items can, however, take up more than one row. (On Windows, multi-row list items are supported only for ActiveX lists.) To create a list with multi-row items, define an input window with one line for each list item row. For example, if you want each list item to take up three rows (to hold an entire record, for example), define three lines in the input window.

Note that there’s no need to specify borders, and column headings usually replace individual field prompts. The input window title is also optional; if you specify it, it will become the list title.

Note

Never explicitly remove the input window associated with a list. Doing so will corrupt the placement order. If you want to use the same input window for other input, you will need to load a separate copy of the window.

Creating the input window

You can create the input window in a script file or at runtime. To create it in a script file, use the .INPUT command. To create the input window at runtime, use the input build (IB_) subroutines. Then, once you’ve created the list, pass the input window ID to L_CREATE. An input window can be associated with only one list.

The input window’s other role: processing input

You’ll use the input window to pass display data between the list processor and your application. When the list processor asks your application for data for a list item, you simply place the data in the input window. The list processor uses that data to display the current item in the list. When list processing is complete, the input window is returned to your application with the data for the new current item along with any non-window data that has been associated with this item. Your application can also use this input window to edit list items.

Using non-window data

In addition to the data that’s displayed in a list (display data), you can associate a data buffer with a list. The data in this buffer is called non-window data. Non-window data doesn’t appear in the list, but it’s stored and retrieved with the display data and may duplicate the display data.

To use non-window data, pass the initial non-window data item as the data argument to L_CREATE when you create the list. When you call a list processing routine, place non-window data for the current item by passing it as the data argument. When processing is complete, the list processing routine will return the non-window data for the new current item as the data argument.

Unlike display data, which is stored and retrieved as displayed, non-window data is stored and retrieved in the form passed to L_CREATE and the list processing routines. For more information on non-window data, see the L_CREATE Discussion.

Defining behavior for lists

List processing methods enable you to define the behavior of a list. Methods are routines you write; they are a modularized way to determine how lists are loaded and any additional processing that you want to happen when an item is accessed, de-accessed, or double-clicked.

The .LISTCLASS script command and L_CLASS subroutine have arguments that enable you to specify the method names when you define the list class. You can use the L_METHOD subroutine to overload methods that you’ve previously specified with the list class or to register methods not specified in the list class.

On Windows, applications must use method subroutines (as opposed to inline code).

See Appendix D: Methods for information on issues that are common to different types of methods.

List arrive and leave methods

Arrive and leave methods enable your program to perform additional processing when arriving at or leaving a list item. Arrive and leave methods are supported on all platforms, but are especially useful on Windows, where users can change the current list item during a call to a Toolkit subroutine, such as L_PROCESS. In this situation your program may not be in control (the user may use the mouse, for instance), so you must create an arrive or leave method if you want additional processing.

In addition to writing an arrive or leave method, you must also associate the arrive or leave method with the list. To do this, do one of the following:

See LARRIVE_METHOD / LLEAVE_METHOD for more information.

List double-click method

By default, Toolkit simulates an Enter when the user double-clicks on a list item. If you want something different to occur for a double-click, you can write an LDBLCLICK_METHOD subroutine and either pass the dblclick_method argument to L_CLASS or specify DOUBLE_CLICK_METHOD in your .LISTCLASS script.

In addition to writing a double-click method, you must also associate the double-click method with the list. To do this, do one of the following:

See LDBLCLICK_METHOD for more information.

List load method

The list load method is an external subroutine you write. This subroutine is called by the list processing routines (L_PROCESS, L_SELECT, or L_INPUT) when an item needs to be loaded into the list (when the user scrolls down the list, for example). The load method must be written to load a single list item at a time. In other words, it should retrieve a single item from your data file (using READS, for example), and then, using I_DISPLAY, display that item in the input window associated with the list.

If you are developing an application for Windows, you must use a load method. Be aware that a load method on Windows may be called at different times than on Unix or OpenVMS (for example, during L_INPUT), so code your load method routine with this in mind.

If you are writing code for Unix or OpenVMS only, a load method is not required, but it’s recommended. If you don’t use a load method for Unix or OpenVMS systems, the list processing routines will use their default processing, which is to return to the calling routine when new items are needed. Load methods free your application from having to satisfy load requests whenever a list processing routine is called, and they encapsulate your item-loading code.

In addition to writing the load method subroutine, you must also associate the load method with the list. To do this, do one of the following:

See LLOAD_METHOD for more information on creating a load method.