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. |
|
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:
- Load initial set of items into the list
- Insert in and delete items from the list
- Update the current item
- Cancel changes to the current item
- Move through the list one item or page at a time
- Move to the top or bottom of the list
- Move an item in the list one row at a time
- Move the display area of the list to the left or to the right
- Call list load method when new list items are needed for the display
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.
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.)
|
|
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.
|
|
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
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.
- If you use L_INPUT, use L_FINDSPEC to specify the parameters the search, and then use the D_LFIND request with L_PROCESS to execute the search.
- If you use L_SELECT, use the find options that are part of the L_SELECT subroutine. You can also use the L_FINDSPEC routine to provide more search functionality.
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.
