S_SELECT

Process a selection window

WTSupported in traditional Synergy on Windows
WNSupported in Synergy .NET on Windows
USupported on UNIX
VSupported on OpenVMS
 
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.

n

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 flag, which is defined in the distributed tkctl.def file. See g_plc_col_args for information.

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.

Note

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")