.ITEM

Define a selection window entry

WSupported on Windows

USupported on Unix

VSupported on OpenVMS

NSupported in Synergy .NET

.ITEM text [, justification][, DEFAULT][, SELECT(character)]

Arguments

text

An alphanumeric or quoted string that contains the text of the selectable entry.

justification

(optional) Designates how the entry text is aligned within the selection window column: LEFT (default), RIGHT, CENTERED.

DEFAULT

(optional) Specifies that this entry will be the default entry for the selection window.

SELECT (character)

(optional) A single, printable quick-select character. If not passed, Toolkit defaults to the first non-blank character in the entry. (Unix and OpenVMS; see Discussion for Windows.)

Discussion

The .ITEM command creates an entry in a selection window.

Entries are loaded into a selection window in the order specified, along with any intervening .TEXT, .BLANK, and .LINE entries.

The specified text is returned if the entry is selected either during input processing or through S_SELECT. UI Toolkit also adds leading and trailing blanks to the display but doesn’t consider those blanks part of the entry.

You can use the S_SELECTCB and S_UPDATECB subroutines to process “check box” type selection windows. See Creating a check box selection window for information on designing check box selection windows. If you want your selection window to show a check mark to the left of the item selected, make sure the first character of text is a blank space. This space will be used for the check mark.

The default justification for entries is LEFT. When you select an entry that is right-justified or centered, any leading blanks are included in the returned entry.

On Windows, you should always use LEFT justification for selection items. RIGHT and CENTERED will not operate as expected because Windows uses a proportional font, rather than a fixed font, for selection window text.

You can specify the DEFAULT option for only one entry. The default entry can be changed or overridden by

• the .FIELD DEFAULT qualifier (which takes precedence over all other specifications for a default entry).
• subsequent calls to S_SELDFLT.
• the optional parameters to S_SELECT.

If you don’t specify DEFAULT, UI Toolkit uses the first entry in the selection window as the default.

On Windows, quick-select characters specified by .ITEM are ignored. The first non-blank character of the item’s text is always used as the quick-select character. Also, quick-select characters are never highlighted and if a user presses an invalid quick-select character, no beep is generated.

Examples

This script defines the following selection window on Unix or OpenVMS:

.select teams, 5, 8
.text "Team 1"
.line
.item Jim
.item Kim
.item Tim
.text "Team 2"
.line
.item Bill
.item Jill
.item Phil
.text "Team 3"
.line
.item Jan
.item Dan
.item Fran
.end