L_PROCESS

Process a list

xcall L_PROCESS(list_id, request, [data], [disabled]
&     [, a_methoddata1, ..., a_methoddata20])

Arguments

list_id

The ID of the list to process. (n)

request

One of the following requests (which must be passed as a variable). (n)

D_LNOP = No request, but update the current item.

D_LLOADBOT = Request to load at the bottom has been satisfied.

D_LLOADTOP = Request to load at the top has been satisfied.

D_LEOF = No more items to load at this end.

D_LUP = Position up one item.

D_LDOWN = Position down one item.

D_LLEFT = Scroll left.

D_LRIGHT = Scroll right.

D_LTOP = Position to the first item.

D_LBOTTOM = Position to the last item.

D_LPGUP = Position up one page.

D_LPGDN = Position down one page.

D_LPGTOP = Position to the top of the page.

D_LPGBOT = Position to the bottom of the page.

D_LINSERT = Insert a new item before the current item.

D_LAPPEND = Insert a new item after the current item.

D_LDELITEM = Delete the current item.

D_LMOVEUP = Move the current item up one place.

D_LMOVEDN = Move the current item down one place.

D_LFIND = Find an item between 1 and 256 characters.

D_LCANCEL = Don’t update the current item; instead, restore the previous contents of the window and data area. (Same as D_LRESTORE.)

D_LRESTORE = Don’t update the current item; instead, restore the previous contents of the window and data area. (Same as D_LCANCEL.)

D_LEXTENDBOT = Reopen the bottom of the list.

D_LEXTENDTOP = Reopen the top of the list.

Returned requests that L_PROCESS can generate are

D_LNOP = No request.

D_LLOADBOT = Load a new item at the bottom.

D_LLOADTOP = Load a new item at the top.

D_LABORT = Fatal list error.

data

(optional) The associated non-window data. (a)

disabled

(optional) The disabled item status. (n)

a_methoddata1 through a_methoddata20

(optional) Up to 20 additional data arguments. (any)

Discussion

L_PROCESS processes a list.

Request must be passed as a variable. See Requests for more information on the values that can be passed and values that are returned.

Whether or not the data argument is passed must correspond to whether it was passed in the L_CREATE call when the list was created. Data is required here if it was also passed to L_CREATE. If data is passed here but was not passed to L_CREATE, a fatal error occurs. (Non-window data is additional information that you don’t want displayed, but that you want to be maintained with the list.)

Disabled is a true/false flag that indicates whether the current item is disabled. Whether or not the disabled argument is passed must correspond to whether it was passed to other list routines such as L_CHR, L_DATA, L_INPFLD, L_INPUT and L_SELECT.

If disabled is present and non-zero, the current item will be disabled. Otherwise, the current item will be disabled only if the entire list is disabled.

The disabled argument will be returned with the enabled/disabled status of the item. On return, disabled will be false (0) if the item inherited the entire list’s enabled/disabled status, regardless of whether the list is actually enabled or disabled.

A disabled list item is designated by the “Disabled list” rendition. (See the tools.def file.) While a list item’s appearance may be affected by the disabled flag, Toolkit processing is not affected by the fact that an item is disabled. Your calling routine is solely responsible for assigning significance to the disabled state of an item: you can leave the item as is, make it uneditable, or process it some other way. For example, the L_SELECT subroutine (which calls L_PROCESS) does not allow the user to select a disabled item, and you can make it skip over disabled items completely by passing a non-zero value in the skip_disabled argument.

On Windows, disabled list entries have no meaning.

A_methoddata1 through a_methoddata20 are up to 20 additional optional arguments that can be passed to L_PROCESS. L_PROCESS, in turn, passes them directly to each field’s methods. This allows you to communicate additional information to your input field methods.

Toolkit passes the method data arguments to the current list processing routine (L_PROCESS, L_INPUT, or L_SELECT) and to the list methods. Thus, if you pass data arguments to one list processing routine, to ensure these arguments are always available, you must pass them to all the list processing routines.

The first time this subroutine is called after the list is created, it initiates the loading of the first window full of items.

Unlike many of the processing routines in UI Toolkit, L_PROCESS doesn’t perform input. The calling routine must perform any input and interpret any menu entry selections.

A list does not have to be placed to be processed.

If you are currently processing more than one list, you must call L_PROCESS or L_SELECT with request set to D_LRESTORE before calling any list processing routine when changing context from one list to the other.

Requests

D_LNOP, D_LLOADBOT, and D_LLOADTOP are the only requests that can be both passed to and returned from the L_PROCESS subroutine. The D_LABORT flag should not be passed to L_PROCESS.

If an LLOAD_METHOD subroutine has been specified, L_PROCESS will call it every time a new list item is needed. LLOAD_METHOD can be specified with the .LISTCLASS script command, or with the L_CLASS or L_METHOD subroutines.

On Windows, you must use a load method to support scrolling.

If no load method is specified for the list, L_PROCESS returns to the calling routine with request set to D_LLOADBOT or D_LLOADTOP, depending on which kind of loading is to be done initially. (See L_CREATE.)

Always set request to D_LEOF for a load request that you don’t support. For example, if you support D_LLOADBOT but not D_LLOADTOP, you’d set request to D_LEOF if D_LLOADTOP was returned.

Before requesting a load, L_PROCESS sets both the data in the input window and the optional data argument to whatever they contained when the list was created. This state of the data is called the “initial” state for an item, and it can be useful when you’re loading prompts or other static or default data.

The load method (or calling routine, if no load method exists) should honor requests from L_PROCESS immediately. When loading is requested, you must do the following:

Obtain the necessary data.
Display any appropriate information in the associated input window.
Load the optional data argument with the associated non-window data.
Set the optional disabled flag to indicate the disabled state of the item.
Return to L_PROCESS again with request still set to the load request (which acknowledges the request).

Between the time you get a load bottom or load top request and the time you return to L_PROCESS again, do not do any screen I/O (for example, M_PROCESS or U_UPDATE).

If no more items are available for the requested load, the load method (or calling routine) must return to L_PROCESS with request set to D_LEOF, to signal this state to the list processor. If no items have been loaded into the list, the processor will leave only one null item in the list, unless the NONULL option was specified for this list’s class. In the latter case, the D_LABORT flag will be returned to indicate a fatal error.

This loop continues until you either send a D_LEOF flag or load the first window full of items. When one of these events occurs, the list processor repositions the list to the first item loaded.

If D_LABORT is returned, a fatal list error has occurred and you will need to delete the list. You can call L_STATUS to get the reason for the error.

The D_LEOF request tells the processor that no more items are available for loading at the requested end of the list.

D_LUP and D_LDOWN tell the processor to move the list’s positional indicator to the previous or next item in the list and to make that item the current one. You cannot move to a previously deleted item. If the indicator is already positioned at the end of the list, the keyboard will beep. If the indicator is already positioned at the end of a page, the list will be scrolled one item in the desired direction.

The horizontal display can change in one of three ways:

You call L_VIEW.
UI Toolkit adjusts the input window display automatically if the user moves to a field that was previously off the screen.
You send a D_LLEFT or D_LRIGHT request to the L_PROCESS subroutine.

The D_LLEFT and D_LRIGHT requests only have an effect if the display area is narrower than the full window. They tell the processor to move the display area of the list to the left or to the right. The display area of the associated input window moves as well. The number of characters that move at one time is half the width of the display area.

Movement can only occur within the display area boundaries. If the current position is on the left or right boundary, no movement occurs in that direction.

The D_LTOP and D_LBOTTOM requests tell the processor to position to the first or last item in the list, respectively. If the indicator is already positioned at the specified end of the list, nothing will happen.

The D_LPGUP and D_LPGDN requests tell the processor to position up or down one page, respectively. A page is defined as the number of visible items. If the top or bottom of the list is encountered before the appropriate number of items has been reached, the first or last item in the list will become the current item.

The D_LPGTOP and D_LPGBOT requests tell the processor to position to the first or last item that is currently visible. If the indicator is already on that item, nothing will happen.

The D_LINSERT and D_LAPPEND requests tell the processor to open a new item before or after the current item, respectively, and make the new item the current item. If you want to insert or append an item somewhere other than adjacent to the current item, you must first move to that location and then use D_LAPPEND or D_LINSERT.

The D_LDELITEM flag tells the processor to delete the current item from the list. The next item, if one exists, becomes the current item. If no next item exists, the previous item becomes the current item. If the only remaining item in a list is deleted, the processor will leave only one null item in the list, unless the NONULL option was specified for this list’s class. In the latter case, the D_LABORT flag will be returned to request that the list be deleted.

The D_LMOVEUP and D_LMOVEDN requests switch the position of the current item with the previous or next item in the list, respectively. If either the beginning or end of a page is encountered, the current item remains at the page boundary, and the new, previously concealed item with which it is being swapped appears below or above that item, with all other visible items scrolled appropriately.

The D_LFIND flag tells the processor to find the next item that matches the criteria set up by any previous calls to the L_FINDSPEC subroutine. If a matching item is not found, the current item remains the same. You can find out whether D_LFIND was successful by calling the L_STATUS subroutine.

The D_LCANCEL (or D_LRESTORE) flag tells the processor not to update the list from the input window and the data argument. Instead, the input window and data are loaded with the previous contents of the current item. (The list will display the same current item that was there before, instead of the data that was just passed.) Any optional disabled flag and input window controls will be updated if you specified the INPUT_SNAPSHOT option when you created the list class. (See .LISTCLASS for information about INPUT_SNAPSHOT.)

D_LEXTENDBOT and D_LEXTENDTOP tell the processor to reopen the previously closed bottom or top of the list, respectively. Even if D_LEOF was passed back to L_PROCESS on a previous load request for the bottom or top of the list, the processor can now request that more items be loaded at that end of the list.