Defining lists
This topic includes the following sections:
- Specifying and determining the list type
- The list class: specifying general list characteristics
- The input window: specifying the list title and the appearance of individual list items
- Using non-window data
- Defining behavior for lists
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.
- The list class defines the general appearance of the list, enables you to associate the list with any methods you’ll write for the list, and can define the list type. For information, see The list class: specifying general list characteristics below.
- The input window enables you to define the appearance of individual list items. For information, see The input window: specifying the list title and the appearance of individual list items.
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:
- Set the ACTIVEX_LIST environment variable.
- Specify the ACTIVEX option when you define the list class. (See .LISTCLASS.)
- Set g_ActiveX_list to true. (You will need to include tkctl.def from the synergyde/toolkit directory.)
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:
- Row and column position
- Number of visible lines
- Header and footer sections
- Scroll bars
- Whether a null list is allowed
- Whether the list will maintain input window control information for each item in the list
- Whether the list will be a Toolkit list or an ActiveX Toolkit list
You can also associate methods with a list. You can specify
- a load method. This is a subroutine that supplies the items for the list.
- an arrive method and a leave method. These are subroutines that perform additional processing when a list item is accessed or deaccessed.
- a double-click method. This is a subroutine that performs additional processing when the user double-clicks on a list item.
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:
- Although the list class defines the characteristics of the header and footer, you must use the L_SECT subroutine to place text in the header or footer, and you must use the L_SECTDRAW subroutine to draw lines in the header or footer.
- You can overload (replace) methods specified in the list class. To do this, use the L_METHOD subroutine.
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.
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:
- Pass the name of the arrive or leave method as the arrive_method or leave_method argument to the L_CLASS subroutine.
- Specify the name of the arrive or leave method after the ARRIVE_METHOD or LEAVE_METHOD option in a .LISTCLASS script command.
- Pass the name of the arrive or leave method after the D_LARRIVE or D_LLEAVE option in a call to the L_METHOD subroutine.
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:
- Pass the name of the double-click method as the dblclick_method argument to the L_CLASS subroutine.
- Specify the name of the double-click method after the DOUBLE_CLICK_METHOD option in a .LISTCLASS script command.
- Pass the name of the double-click method after the D_LDBLCLCK option in a call to the L_METHOD subroutine.
See LDBLCLICK_METHOD for more information.
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:
- Pass the name of the load method as the load_method argument to the L_CLASS subroutine.
- Specify the name of the load method after the LOAD_METHOD option in a .LISTCLASS script command.
- Pass the name of the load method after the D_LLOAD option in a call to the L_METHOD subroutine.
See LLOAD_METHOD for more information on creating a load method.