|
WSupported on Windows
|
USupported on Unix
|
VSupported on OpenVMS
|
NSupported in Synergy .NET
|
xcall L_SELECT(list_id, request, [data], [disabled], [skip_disabled], [find_prompt], & [find_length], [character], [select_column], [help_id], [pre_input_routine], & [find_window], [find_init], [find_column], [wait_time] & [, a_methoddata1, ..., a_methoddata20])
Arguments
list_id
The ID of the list. (n)
request
The request flag. Passed requests that L_SELECT can accept are the same requests honored by L_PROCESS. (See L_PROCESS for more information on these requests.) These are the returned requests that L_SELECT can generate: (n)
Item was selected, or unknown menu entry was selected.
Need an item at the bottom.
Need an item at the top.
Cannot proceed; delete the list.
data
(optional) The associated non-window data. (a)
disabled
(optional) The disabled item status. (n)
skip_disabled
(optional) The true/false flag that indicates whether disabled items will be skipped. (n)
find_prompt
(optional) The prompt to the user to enter a string for which to search. (a)
find_length
(optional) The maximum length (between 1 and 256 characters) allowed for a search string. (n)
character
(optional) The ASCII value of the character the user typed. (n)
select_column
(optional) The selection column ID. (n)
help_id
(optional) The help identifier. (a)
pre_input_routine
(optional) The name of a subroutine to call before character input is performed. (a)
find_window
(optional) The ID of the input window for find. (n)
find_init
(optional) The true/false flag that indicates whether L_SELECT will initialize the find window. (n)
find_column
(optional) The input column for find. (n)
wait_time
(optional) The time-out limit for I/O processing to be completed before returning to the calling routine. (n)
Never time out.
Use the global value (see g_wait_time). (default)
Time out immediately.
Wait up to n seconds (where n is a positive value) for I/O processing to be complete.
a_methoddata1 through a_methoddata20
(optional) Up to 20 additional data arguments that can be passed to L_SELECT. L_SELECT, in turn, passes them directly to each field’s methods. This allows you to communicate additional information to your input field methods. (any)
Discussion
L_SELECT provides selection processing similar to S_SELECT, except using a list. The list (or some part of it) is presented to the user, and the user can navigate the list, find specific values, and finally, select an item. The advantage to using a list is that it can be virtually any length, but only the necessary items are loaded.
If the list is an ActiveX list, when a user selects a cell in the list, by default only the cell is highlighted. You can, however, instruct Toolkit to highlight the entire row by setting the RowMode property to any non-zero value. For more information, see Published properties for ActiveX Toolkit lists.
List_id is the ID of a list that was previously created with the L_CREATE subroutine.
Request is the request flag for the L_PROCESS subroutine. The L_SELECT subroutine translates menu entries into request flag values, but the calling routine must either specify the name of the LLOAD_METHOD subroutine for loading list items or provide the items to load into the window itself. LLOAD_METHOD can be specified using the .LISTCLASS script command, or the L_CLASS or L_METHOD subroutines.
Request should be set to D_LNOP (0) the first time L_SELECT is called. L_SELECT will call the load method, or return with request set to either D_LLOADBOT or D_LLOADTOP (depending on the options set when the list was created) until no more items are currently needed. The load method or the calling routine must do either one of the following:
- Retrieve another item, display the data in the associated input window, fill in data appropriately, set the optional disabled flag, and call L_SELECT again with request still set to the load request value.
- If no more items are available at the requested end of the list, set request to D_LEOF and call L_SELECT again.
Between the time you get a load bottom or load top request and the time you return to L_SELECT, do not do any screen I/O (for example, M_PROCESS or U_UPDATE).
If a load method has been specified, L_SELECT calls it every time a new list item is needed, and does not return to the calling routine.
If L_SELECT returns request set to D_LABORT, an unsupportable situation has occurred, and the calling routine should delete the list.
L_SELECT honors the following menu entries and translates them into list requests:
|
L_SELECT Menu Translations |
|
|---|---|
|
Menu entry |
List request |
|
S_UP |
D_LUP |
|
S_DOWN |
D_LDOWN |
|
S_LEFTa |
D_LLEFT |
|
S_RIGHTa |
D_LRIGHT |
|
S_TOP |
D_LTOP |
|
S_BOTTOM |
D_LBOTTOM |
|
S_PGUP |
D_LPGUP |
|
S_PGDN |
D_LPGDN |
|
S_PGTOP |
D_LPGTOP |
|
S_PGBOT |
D_LPGBOT |
|
S_FIND |
D_LFIND (after prompting for a find string and calling L_FINDSPEC) |
|
S_FINDNEXT |
D_LFIND |
|
S_FINDDIR |
(Toggle find direction) |
You can also translate menu entries yourself. If the user selects a menu entry that L_SELECT does not recognize, the calling routine can map it to any request code recognized by L_PROCESS.
As shown in the above table, both the S_FIND and S_FINDNEXT menu entries use D_LFIND, but S_FIND’s operation does some additional processing. S_FIND first pops up an input window for the user to input specifications for the find operation, then it calls L_FINDSPEC to set the characteristics, and lastly it calls L_PROCESS. You can call L_FINDSPEC before calling L_SELECT to establish “find” defaults.
When either an S_FIND or an S_FINDNEXT is being performed, L_SELECT will display a message on the information line. This message is contained in the syntxt file under the facility DTK, mnemonic FIND_MSG.
If L_SELECT will be displaying a find window (honoring S_FIND), you have three options:
- Use L_SELECT’s default find window, which has the prompt “Find:”, accepts 80 characters or the number of characters passed as data (whichever is less), and on Windows has OK and Cancel buttons. This is The default find window will display centered within the current display area.
- Create your own find window in a script file (or with the IB_xxx routines) and pass that window’s ID in find_window.
- Create your own find window by using the %L_FINDWND function as the find_window argument.
If you would prefer either of the last two options (creating your own find window), see the information on find_window below.
Whether or not the data argument is passed must correspond to whether it was passed in the L_CREATE subroutine 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.
Data is the optional associated non-window data for the list. (Non-window data is additional information that you don’t want displayed, but that you want to be maintained with the list.) Whenever this subroutine returns, the data for the current item is loaded in data, and the list’s associated input window contains the display data for that item.
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_PROCESS. See L_PROCESS for more information about the disabled item status.
If disabled is passed and has a value of true, the current item is disabled and cannot be selected. If skip_disabled is passed and has a value of true, the positional indicator cannot move to a disabled item after it is loaded; the indicator will move past the item automatically. The disabled argument is returned with the disabled status for the current item.
If the user presses Enter, Tab, or Shift+Tab, or if an unknown menu entry is selected, L_SELECT returns, setting request to D_LNOP. The data argument will contain the associated data for the item, and the list’s input window will contain the display data for the item. Note the following:
- On Windows, if the selection list is part of a composite window, Tab signals “C_NEXT” and Shift+Tab signals “C_PREV”.
- If an unknown menu entry is selected, g_select is returned with a value of true and g_entnam will contain the menu entry name. You must clear g_select after you satisfy the event.
Character helps you determine whether the user typed a printable character while positioned on an enabled item. If character is not passed and the user enters any key other than Enter or a menu shortcut, the terminal bell will ring and processing will continue.
If character is passed, one of the following may occur:
- If the user types a printable character while positioned on an enabled item, the ASCII value of that character will be returned.
- If the user selects a menu entry or presses Enter while positioned on an enabled item, character will be returned with a value of 0.
- If the user is positioned on a disabled item (which means skip_disabled either is not passed or has a value of false) and types a printable character or presses Enter, the terminal bell will ring and processing will continue.
The user can select a menu entry while on a disabled item if skip_disabled is not passed or has a value of false, in which case the optional character argument will be returned with a value of zero.
On Windows, select_column and find_column are, by default, ignored if passed. These columns usually contain reserved menu entries that are automatically supported by the Windows environments.
On Unix and OpenVMS, if select_column is passed, the specified selection column will be placed before selection processing occurs, and it will be removed on exit. If find_column is passed, the menu column with that ID is placed before performing input to find_window, and removed afterwards.
The default behavior for each environment’s handling of columns is controlled by the g_plc_col_args flag, which is defined in the distributed tkctl.def file. See g_plc_col_args for information.
If the operation times out, g_select is set to true and g_entnam set to the entry name specified in g_time_entry, which is defined in tkctl.def. See g_time_entry.
If pre_input_routine is passed, L_SELECT will pass the specified pre-input routine the list ID. If a menu entry is selected while in the pre-input routine, L_SELECT will honor the menu name if L_SELECT recognizes it. If L_SELECT doesn’t recognize the name, L_SELECT will return the name to the calling routine.
If specified, the pre_input_routine must be available. In other words, it must either be contained within the current program image, or in an executable library (ELB) that was either linked to or opened with OPENELB. The default state, if no pre_input_routine is specified anywhere, is for L_SELECT to return to the caller when input is ready to be performed.
The L_SELECT subroutine turns both echo and cursor off. You may want to call E_ENTER and E_EXIT around the call to this subroutine, because L_SELECT doesn’t call E_ENTER, nor does it reset the echo and cursor parameters when it’s done.
You can pass find_window to replace L_SELECT’s default find window. Find_window must be either the ID of an input window you have created in a script file, with the IB_xxx subroutines, or with %L_FINDWND.
|
If D_RETURNBTN will be enabled and the list will be part of a composite window that on Windows has buttons, you will need to add a default button to the find window. This will enable users to close the find window normally. The default find window, for example, has OK and Cancel buttons, with OK as the default. |
L_SELECT places and displays the find window within the current display area when the user selects the menu entry “S_FIND”. If you create your own find window with a script, placement of the find window can be specified within your script. If you create the window with the IB_xxx subroutines, you can use U_WINDOW to specify placement. If you use the %L_FINDWND function, the find window will be centered within the current display area by default. To change the placement of the %L_FINDWND window, place and remove the window (without updating the screen) before calling L_SELECT. When L_SELECT calls the %L_FINDWND window, it will place it at the last placement position.
When find_window is specified, L_SELECT calls a UI Toolkit input routine to perform the input in the find_window. L_SELECT passes the input routine the D_NOTERM option (to suppress the input termination message) and passes the finddata data structure:
record finddata finddir ,i4 ;Find direction findcase ,i4 ;Find case findtype ,i4 ;Find type findcurr ,i4 ;Find current item findpos ,i4 ;Search area position findlen ,i4 ;Search area length findstrng ,a80 ;Find string
See the tools.def file for the values associated with finddata’s first four variables (finddir, findcase, findtype, and findcurr). Finddata is preloaded with the current values, as previously specified by a call to L_FINDSPEC (or the default values).
Note that even though findstrng is declared as a80, only positions 1 through findlen will be considered, and only the trimmed input within these bounds will be used for find matching.
Find_window does not have to provide input for or display all of finddata’s options. For example, if you only wanted to allow the user to input the find string, the .STRUCTURE script command for the input window would look something like:
.structure find, <24>, findstrng
If find_init is passed and true, the default set for the window is initialized with I_INIT. Otherwise, the previous find data is displayed into the default set using I_DISPLAY, and I_NEXT is used to position the context of that set to the first field.
See also
WAIT qualifier for the .FIELD command for more information on input time-outs
Examples
The following example processes the selection list identified by lstid. On entry, req contains the request to be processed by L_SELECT. In this example, no initial action has been requested. The paragraph satisfy_request will perform the request returned from L_SELECT. This could be either to load data into the list (assuming no load method is defined for the list) or to abort the list. Satisfy_request will set req to indicate the result of the performed action. The paragraph process_selection is called only when all requests from the list processor are satisfied, and in this case either a menu entry (unrecognized by L_SELECT) has been selected or the user has pressed Enter on an item in the list.
req = D_LNOP do begin xcall l_select(lstid, req, lst_data) if (req) then call satisfy_request ;Process list requests first else call process_selection ;Process a selection end until (g_select) ;Unrecognized menu entry satisfy_request, case req of begincase ;D_LLOADBOT call load ;Load requested item ;D_LLOADTOP req = D_LEOF ;Tell L_SELECT "none available" ;D_LABORT g_select = TRUE ;Force exit from L_SELECT loop endcase return process_selection, if (g_select) then case g_entnam of ;Process a menu entry begincase . . . endcase else ;An item was selected g_select = TRUE ;Force exit from L_SELECT loop return
The following call to L_SELECT passes the data associated with the selection list in lst_data and the current disabled status of the item in disabled. Disabled selections will be skipped and the new disabled status returned in disabled.
xcall l_select(lstid, req, lst_data, disabled, TRUE)
