S_SELECT

Process a selection window

xcall S_SELECT(window_id, [initial_field], [field_data], [select_column], [selected_field], 
&     [help_id][, wait_time])

Arguments

window_id

The ID of the selection window to process. (n)

initial_field

(optional) The number of the initial field. (n)

field_data

(optional) Returned with the data of the selected field. (a)

select_column

(optional) The selection column ID. (n)

selected_field

(optional) Returned with the ordinal number of the selected field. (n)

help_id

(optional) The help identifier. (a)

wait_time

(optional) The time-out limit for I/O processing to be completed before returning to the calling routine. (n)

D_FOREVER or -1

Never time out.

D_GLOBAL or -2

Use the global value (see g_wait_time). (default)

D_IMMEDIATE or 0

Time out immediately.

Wait up to n seconds (where n is a positive value) for I/O processing to be complete.

Discussion

S_SELECT processes selection windows.

On Windows, the window is automatically placed, but on Unix and OpenVMS, you must place the window with U_WINDOW(D_PLACE) before processing with S_SELECT.

If initial_field is passed, the specified field will be initially highlighted before selection processing begins. If not passed, any previous call to S_SELDFLT or a default specified by S_SELBLD (or in a .SELECT window script using the .ITEM DEFAULT qualifier) will be used. In either case, if the resulting value is less than 1, 1 will be used. If initial_field is greater than the number of fields in the window, the last field will be highlighted.

If field_data is passed, it will be returned with the data of the highlighted field at the time that Enter was pressed, or an unrecognized menu entry was selected.

On Windows, the select_column is ignored by default. This column usually contains reserved menu entries that are automatically supported by the Windows environment. Additionally, the excessive placing and removing of columns causes a Windows menu bar to flicker.

On Unix and OpenVMS, if select_column is passed and non-zero, the specified column will be placed on the menu and removed on exit. The alternative to specifying this column is to place the column before calling S_SELECT.

The default behavior for each environment’s handling of columns is controlled by the g_plc_col_args variable, which is defined in the distributed tkctl.def file.

On Windows, the arrow keys, HOME key, and END key are captured by the selection window and are not returned to the calling application. For this reason, and to reduce menu-bar flicker, the optional select menu passed to S_SELECT is placed only when g_plc_col_args is true.

The following internal menu entry names are recognized by S_SELECT. Menu entries that start with E_ are recognized only on Windows and perform the associated Windows functionality, if applicable. See Appendix B: Reserved Menu Entries for information on reserved menu entries.

E_CLEAR	S_UP
E_COPY	S_DOWN
E_CUT	S_LEFT
E_MARK	S_RIGHT
E_PASTE

If the name of the selected menu entry begins with “U_”, the EUTILS_METHOD subroutine is called and the input is redone. If the internal name of the selected menu entry is “O_HELP,” the EHELP_METHOD subroutine is called with help_id as its argument.

If some other menu entry is selected, control is returned to the calling routine. G_select will be true and g_entnam will hold the name of the entry.

You will need to clear g_select after you satisfy the event.

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.

On Windows, the mouse can be used to highlight and select entries.

The S_SELECT subroutine turns echo and the cursor off. Your calling routine should put an E_ENTER and E_EXIT around the call to this subroutine because S_SELECT does not do an E_ENTER, and it does not reset these parameters when done.

On Windows, for selection windows that are part of a composite window, Tab and Shift+Tab move focus to the next or previous child (unless Tab or Shift+Tab is a shortcut on a placed menu column). Tab instructs S_SELECT to signal “C_NEXT”, and Shift+Tab instructs S_SELECT to signal “C_PREV”.

Examples

This example loads a selection window and a menu column, then processes the selection window, starting on the third item. The S_SELECT subroutine returns the chosen selection’s text in selection and its ordinal field number in selnum. If the user selects the menu entry “O_HELP,” the EHELP_METHOD subroutine is called, passing the help ID argument of “sel_help.”

xcall u_ldwnd(id, g_utlib, "select")
xcall m_ldcol(colid, g_utlib, "selcol", D_NOPLC)
xcall s_select(id, 3, selection, colid, selnum,"sel_help")