S_SELBLD

Create a selection window

WTSupported in traditional Synergy on Windows
WNSupported in Synergy .NET on Windows
USupported on UNIX
VSupported on OpenVMS
xcall S_SELBLD(window_id, window_name, fields, rows, array_data, [type], [quick_select], 
&     [width], [default_entry][, nopad])

Arguments

window_id

Returned with the window ID. (n)

window_name

The name of the window to be created (a maximum of 15 characters). (a)

fields

The total number of items in the window, including text and lines. (n)

rows

The number of rows per column, including text and lines. (n)

array_data

The first element of the array containing the data to load. (a)

type

(optional) The array of flags indicating one of the following types of entries: (n)

D_SEL_ENTRY = A field entry. (default)

D_SEL_TEXT = Non‑entry text.

D_SEL_LINE = A horizontal line.

quick_select

(optional) The array of quick_select characters. (a)

width

(optional) The column width. The default width is %len(array_data). (n)

default_entry

(optional) The default entry. (n)

nopad

(optional) The true/false flag that specifies whether to suppress the blank columns that occur to the left and right of each entry in the selection window. (n)

Discussion

S_SELBLD creates a selection window and loads it with data.

You can specify a maximum of 32767 fields. The number of rows per column (rows) must be greater than zero. (Note, however, that because Synergy cannot place windows that do not fit on the screen, the practical maximum number of entries will be much lower. For instance, if the size of the Toolkit's virtual screen is 25 rows by 80 columns, a selection window cannot be placed if it has more than 2000 entries—and 2000 would only be possible if there is no padding between the columns and each entry is a single character.)

S_SELBLD loads the data from top to bottom and then left to right. The selection window will have a one‑character margin on each side (unless you have passed nopad), except for horizontal line entries. Line entries in array_data will be overwritten by a horizontal line; use a blank element in array_data.

If you are processing with S_SELECT, on Windows systems, the window is automatically placed. On UNIX and OpenVMS, you must place the window with U_WINDOW(D_PLACE).

Use I_FLDSEL to associate the new selection window with a particular field.

Don’t forget to log the window you create with the U_LOGWND subroutine.

If you pass a null string (“ ”) for window_name, Toolkit assigns a unique window name in the form _W_nnn, where nnn is the window ID.

If quick_select is not passed or is blank, the first non‑blank character in each entry is used.

The elements in array_data, type, and quick_select correspond with each other.

On Windows, the type options D_SEL_TEXT and D_SEL_LINE, and the quick_select argument are ignored and serve only as placeholders. D_SEL_TEXT and D_SEL_LINE are not recognized because Windows environments do not categorize text and line items with selection items the user can select.

If default_entry is not specified, the first selectable entry in the selection window becomes the default entry. You can change or override the default entry with S_SELDFLT or when calling S_SELECT. Default_entry refers to the ordinal, selectable entry number (not counting text and line entries).

Note that horizontal lines do not connect with the selection window border.

If you have a selection window with more than one column, and that window does not have corresponding text or line entries in the same row of each column, left and right movement within the window won’t be consistent. Therefore, we recommend that you either don’t use text or line entries in a multi‑column selection window, or make sure that each column in the selection window contains text or line entries in the same row.

Examples

The following example creates a window called choices with a maximum of 25 entries, 5 per column. It loads the data from data.

xcall s_selbld(selid, "choices", 25, 5, data)   

The next example, a selection window named names, can be created with the data records listed below.

Example selection window

data    ,15a6   ,"Team 1", " ", "Jim", "Kim", "Tim" 
&               ,"Team 2", " ", "Bill", "Jill", "Phil" 
&               ,"Team 3", " ", "Jan", "Dan", "Fran" 
type    ,15d1   ,D_SEL_TEXT, D_SEL_LINE, D_SEL_ENTRY 
&               ,D_SEL_ENTRY, D_SEL_ENTRY 
&               ,D_SEL_TEXT, D_SEL_LINE, D_SEL_ENTRY 
&               ,D_SEL_ENTRY, D_SEL_ENTRY 
&               ,D_SEL_TEXT, D_SEL_LINE, D_SEL_ENTRY 
&               ,D_SEL_ENTRY, D_SEL_ENTRY 
xcall s_selbld(selid, "names", 15, 5, data, type)