|
WSupported on Windows
|
USupported on Unix
|
VSupported on OpenVMS
|
NSupported in Synergy .NET
|
xcall L_NEXT(list_id, itemno)
Return value
status
Always returns true. (i)
Arguments
list_id
The ID of the list. (n)
itemno
The row number of the list item you want selected. (n)
Discussion
L_NEXT enables you to specify which list item will be selected when a list is next processed. It queues a request to set the selected item for a list to the nth item where n is the value passed as itemno. As with L_QUEUE, the selection is queued so that actions queued before the call to L_NEXT occur before the selection, and actions queued after the call to L_NEXT occur after the selection. Note the following:
- Call L_NEXT before calling L_PROCESS or a routine that calls L_PROCESS (such as L_SELECT or L_INPUT). L_NEXT queues a request, but an L_PROCESS call is required to actually set the specified item.
- If the selection is successful, the found status of the list (the L_STATUS flag D_LFOUND) is set to 1.
- If the requested item cannot be accessed (in other words, if itemno is less than 1 or greater than the number of items in the list), the list selection remains unchanged, and the found status of the list is set to zero.
- If item numbering within the list is changed (by loading more or fewer items at the top than expected), the item is selected according to the most recent numbering scheme. This means that item 1 always selects the top item in the list. However, this also means that using the L_STATUS subfunction D_LCURITM to retrieve the current item number and then using L_NEXT in an attempt to return to that item after loading items may cause L_NEXT to access a different item.
Examples
In the following example, the D_LCURITM subfunction of L_STATUS is used to save the current item number. The example then navigates to the end of the list to ensure that all items have been loaded, enabling D_LLASTITM to get the total number of items. Finally, L_NEXT returns the list to the previously selected item.
xcall l_status(listid, D_LCURITM, itmno) ;Fetch current item. xcall l_process(listid, request=D_LBOTTOM, data) ;Go to the end to load all items. xcall l_status(listid, D_LLASTITM, numitems) ;Get number of items. xcall l_next(listid, itmno) ;Specify where to go. xcall l_process(listid, request=D_LNOP, data) ;This actually does it.
