LARRIVE_METHOD / LLEAVE_METHOD

Perform list item arrive or leave processing

subroutine LARRIVE_METHOD | LLEAVE_METHOD
 a_status               ,n
 a_listid               ,n
 a_win_event            ,n
 a_itemdata             ,a
 a_inpid                ,n
 a_disabled             ,n
 a_index                ,n
 a_row                  ,n
 a_methoddata1          ,any
       .
       .
       .
 a_methoddata20         ,any

Arguments

a_status

The returned status of the item. This argument is ignored and reserved for future use. (n)

a_listid

The ID of the list. (n)

a_win_event

The windows-event flag: TRUE if called in response to a Windows list box control event or FALSE if called in response to a program request to L_PROCESS. (n)

a_itemdata

(optional) The item data for the list. (a)

a_inpid

The ID of the list’s associated input window. (n)

a_disabled

(optional) The true/false flag that indicates whether to disable the list item. (n)

a_index

The index of the list item (1-based). (n)

a_row

The item’s row number within the currently visible set of rows. (n)

a_methoddata1 through a_methoddata20

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

Discussion

LARRIVE_METHOD and LLEAVE_METHOD are subroutines that you write and name when you want your program to perform extra actions before a specific list item is highlighted or before the user leaves a specific list item, respectively.

You register the LARRIVE_METHOD and/or LLEAVE_METHOD subroutines using the .LISTCLASS script command, or the L_CLASS or L_METHOD subroutines.

If registered, LARRIVE_METHOD and/or LLEAVE_METHOD must either be contained within the current program image or reside in an executable library (ELB) that was either linked to or opened with OPENELB.

When you specify LARRIVE_METHOD or LLEAVE_METHOD qualifiers, the above arguments will be passed to the LARRIVE_METHOD and/or LLEAVE_METHOD subroutines.

For the arrive method, a_itemdata, a_disabled, a_index, a_row, and the display in the input window correspond to the item being accessed. For the leave method, they correspond to the item being left.

The a_index argument starts at one (1), rather than zero (0).

A_methoddata1 through a_methoddata20 are up to 20 additional optional arguments that can be passed to I_INPUT or L_INPUT. They are passed, in turn, directly to LARRIVE_METHOD and/or LLEAVE_METHOD. This enables you to communicate additional information to LARRIVE_METHOD and LLEAVE_METHOD.

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 arrive and leave methods for a list are called only once, when the selected item changes. If no change is effected, neither method is called. Special cases include D_LINSERT (which leaves and arrives, even though the new item is at the same logical index), and D_LDELITEM (which does not leave the item being deleted, but arrives at the new item that took its place). D_LMOVEUP and D_LMOVEDN do not call the arrive or leave methods, because the item is the same although its index has changed.

An attempt to move to a nonexistent item will generate a leave and arrive at the same time. Requests that are queued with L_QUEUE and processed together in a single call to L_PROCESS or L_SELECT are treated as one movement. For instance, if you queue a D_LFIND and process a D_LDOWN, there will only be one leave (from the original item) and one arrive (to the item resulting from the D_LDOWN). If you need to arrive at the intervening points, call L_PROCESS for each operation.

The arrive and leave method subroutines are required for applications that will run on Windows. Windows applications can interactively change the current item in the list within a call to a UI Toolkit subroutine. Therefore, you must write these subroutines to support event procedures for arriving at and leaving from a list item. These method subroutines (also called “event procedures”) enable your program to perform any additional processing required.

If no arrive or leave methods are specified, the default behavior is to do nothing.

LARRIVE_METHOD / LLEAVE_METHOD

LARRIVE_METHOD / LLEAVE_METHOD