Processing and maintaining lists

This topic includes the following sections:

 

These are the basic steps you’ll follow to process a Toolkit or ActiveX Toolkit list:

1. In your program, use I_LDINP to load the input window you created for the list. But don’t place the window. (Be sure to pass D_NOPLC as the no_placement argument.)
2. Use L_CREATE to create the list. In this step, you’ll pass the name of the list class and input window, and you’ll determine how the list will be loaded (top to bottom, bottom to top, or from the middle).
3. (optional) Use L_SECT to add text to the header, footer, or title.
4. (optional) Place the list with L_PLACE, and enable the list with L_ENABLE if necessary.
5. Process the list with L_SELECT, L_PROCESS, or one of the list input routines. These routines should be called from a loop. See Performing list processing below.
6. Delete the list either explicitly, with L_DELETE, or implicitly by exiting the environment in which the list was created.
Note

There are other routines that enable you to maintain lists. There are routines that enable you to remove a list, enable a list, disable a list, queue requests for a list, promote a list to global status, and so forth. See The list subroutines and functions.

Performing list processing

The three primary list processing routines are L_INPUT, L_PROCESS, and L_SELECT. Both L_PROCESS and L_SELECT support the processing functions that are generic to all Toolkit and ActiveX Toolkit lists:

Neither L_PROCESS nor L_SELECT performs any input. (Use one of the list input routines, such as L_INPUT, to do this.) L_PROCESS performs any requests to the list (such as to insert an item, delete an item, and so forth) and returns to the calling program. L_SELECT also performs requests, but it returns only when the user has selected an item from the list or has selected an unknown menu entry. See L_PROCESS, L_SELECT, and L_INPUT for more information.

Call L_INPUT or L_SELECT from a loop in your application, as you would I_INPUT or M_PROCESS. Use an L_INPUT loop when you want to perform input into the list. Use an L_SELECT loop for making a selection from a list of existing items. One of the arguments to L_PROCESS and L_SELECT is a request flag, which is used by the calling routine to request action from L_PROCESS or L_SELECT and by these routines to request action from the calling routine. Note that L_INPUT does not have a request flag argument. Use calls to L_PROCESS within your L_INPUT loop to handle requests.

How list items are loaded

Toolkit lists and ActiveX Toolkit lists are empty when they are first created, but the first call to a list processing routine loads the list with the list items needed for the initial display. List items are loaded only as they are needed for display. The first time an item is needed, the list processing routine requests the item from the list load method (or the calling routine if you don’t have a load method) and loads the item into the list. Once an item is loaded, UI Toolkit continues to use it when necessary. It doesn’t need to be loaded again. Because the list processor maintains loaded items in a linked list on the file stack, the calling routine does not need to supply loaded items a second time, which improves processing speed. (Refer to Appendix E: File‑Stack Processing and Appendix F: Linked‑List Processing for more information about the file‑stack and linked‑list subroutines.)

Note

We strongly recommend that you use a load method to load items into a list. For Windows applications, you must write and use a list load method to enable scrolling.

For information on list load methods, see List load method.

List processing examples

A selection list

The following example creates and processes a simple look‑up list. The attributes of the list are defined by the list class lst_lookup. The items for the list are provided by the load method listload_method, which is automatically called by L_SELECT. (See Retrieve the text in an individual cell of a header.) The list enables a selected item to be deleted. Choosing delete sets the request flag to D_LDELITEM, which instructs the next call to L_SELECT in the loop to process the request. Note that an item is deleted only from the visible list, not from the file from which the list was loaded.

xcall i_ldinp(inpid, g_utlib, "inp_lookup")
xcall l_create(listid, inpid, data, g_utlib, "lst_lookup")
xcall l_button(listid, "O_EXIT", DSB_TEXT, "Exit")
xcall l_button(listid, "O_DELETE", DSB_TEXT, "Delete")
xcall l_method(listid, D_LLOAD, "listload_method")
request = D_LNOP
repeat
    begin
    xcall l_select(listid, request, data)
    if (g_select) then                      ;Unknown menu entry
        begin
        using g_entnam select
            ('O_EXIT'), exitloop
            ('DELETE'), request = D_LDELITEM
        endusing
        end
    else
        xcall u_msgbox (data)               ;Display chosen entry
    end

An input list

The following example creates and processes a simple input list. The attributes of the list are defined by the list class lst_process. The items for the list are provided by the list load method listload_method, which is automatically called by L_INPUT. (See Retrieve the text in an individual cell of a header.) The list enables existing items to be deleted and new ones to be inserted. Choosing insert or delete calls L_PROCESS with the request flag set to the appropriate value. Note that an item is deleted only from the visible list, not from the file from which the list was loaded.

Note

Direct input into an ActiveX Toolkit list may cause repainting problems. See Notes and tips for ActiveX Toolkit lists for information.

xcall i_ldinp(inpid, g_utlib, "inp_process")
xcall l_create(listid, inpid, data, g_utlib, "lst_process")
xcall l_button(listid, "O_EXIT", DSB_TEXT, "Exit")
xcall l_button(listid, "O_DELETE", DSB_TEXT, "Delete")
xcall l_button(listid, "O_INSERT", DSB_TEXT, "Insert")
xcall l_method(listid, D_LLOAD, "listload_method")
request = D_LNOP
repeat
    begin
        xcall i_next(inpid,, "*FRST*")
        xcall i_input(listid,, data, data)
        if (g_select) then                  ;Unknown menu entry
            begin
            using g_entnam select
                ('O_EXIT'), exitloop
                ('O_DELETE'), xcall l_process(listid, request=D_LDELITEM, data)
                ('O_INSERT'), xcall l_process(listid, request=D_LINSERT, data)
            endusing
            end
        else
            ;process new entry
        end

Load method for the examples

The load method for the above list examples would look like this:

subroutine listload_method
;
; Description: Load method for lookup and input lists
; Arguments:
    a_listid         ,n       ;ID of the list
    a_req            ,n       ;Request
    a_data           ,a       ;Data
    a_inpid          ,n       ;Input window ID
    a_disabled       ,n       ;(Optional) disabled item flag
    a_itemindex      ,n       ;Request item number
static record
    chn              ,i4      ;Channel for loading
proc
    if (a_itemindex .eq. 1)                           ;First item?
        xcall u_open(chn, "I:I", "customer")          ;Open file
    reads(chn, a_data) [eof=nomore]                   ;Read next record
    xcall i_display(a_inpid, "customer_set", a_data)  ;Display the data
    xreturn
nomore,
    a_req = D_LEOF            ;Signal no more
    xreturn
endsubroutine

Enabling users to search a list

Depending on the subroutine you use to process your list (L_INPUT or L_SELECT), there are two ways to provide a search for your list.

You can search the display data or the non‑window data. See L_FINDSPEC for more information on how to specify which type of data will be searched.

IDs for list windows

There are two types of window ID for a list: the ID for the input window used to define the list and the ID for the list window, which is the window that contains the list when the list is placed. When you create a list with L_CREATE, you supply the first type of window ID. If, however, you want to use other Toolkit routines that require a window ID (for example, %U_WINMETRICS), you must supply the ID for the list window. To get the list window ID, use the D_LCTRID subfunction for L_STATUS.