Selection windows enable you to present the user with a fixed list of textual items from which to choose. These items are listed in one or more columns in the window. All items are padded out to the same length, although the text of each may be left-justified, right-justified, or centered within that length. (On Windows, selection list items should always be left-justified. Any other option does not operate as expected.) A selection window can also have a border and a title.
The item currently being accessed in a selection window is always highlighted, regardless of whether the selection window is being processed.
A selection window can be attached to an input window field (using the I_FLDSEL subroutine) or processed directly. When a selection window is attached to an input field, the selected item becomes the input for that field. When a selection window is processed directly, either the text of the selected item or its ordinal position in the selection window can be returned to the calling routine.
You can generate selection windows from script files or at runtime (using the S_SELBLD routine).
Selection windows are like menu columns in the following ways:
- All the possible choices are visible.
- You navigate them with arrow keys and quick-select characters.
- To select an item, you press Enter.
However, they are unlike menu columns in these ways:
- They are not attached to a menu bar.
- They may contain more than one column of selections.
- Items can be reloaded at runtime.
- Entries do not have shortcuts, entry names, or user text.
Selection windows compare and contrast with lists in the following ways:
- Like lists, you can load selection windows at runtime with a set of items drawn from any source (such as a file) so that the user has them available to select.
- While lists allow only one column of items, selection windows can contain more than one column of items.
- Unlike lists, selection windows only contain a fixed number of items, all of which must be visible.
Note that you can also create check box selection windows, which display a special character (usually a check mark or an “X”) to the left of any entry whose value is true. See Creating a check box selection window.
Display renditions
Five rendition states are associated with selection windows:
- Border
- Title
- Background
- Selected item
- Entry quick-select character
When a selection window is processed, the above renditions are applied to the window. The item currently being accessed is displayed in the selected item rendition. All other items and any text, lines, or blank entries are displayed in the background rendition. (On Windows, text, lines, and blank items have no meaning.)
By default,
- the border and title renditions are unchanged from how they were defined when the window was created.
- the background rendition is unchanged, except that reverse is disabled.
- the selected item rendition is unchanged, except that reverse is forced.
- the entry quick-select character is set to underlined, color palette 10.
For information on editing these renditions, see Customizing the look of your application.
Making a selection
When a selection window is processed, the default item is highlighted. The user can then move the highlight to the desired item by pressing the arrow keys or a quick-select character. To select the item, the user presses Enter. On Windows, the mouse can be used to highlight and select entries.
Creating a check box selection window
Check box selection windows enable you to display a special character (usually a check mark or an “X”) to the left of any entry that has a true value. These values correspond to an array that is passed to and from the check box routines. The routines S_UPDATECB and S_SELECTCB are used with check box selection windows.
Typically, you would design a check box selection window in the following manner:
| 1. | Create your selection window, either in a script with the .SELECT command or in your code with the S_SELBLD subroutine. Leave the first character in each entry blank. This position will be used for the check mark. |
| 2. | In your program, load the selection window, and then call S_UPDATECB to mark any items that are already true. The check mark character is defined in tkctl.def by the global field g_chk_char. This field is initialized by U_START to an “X” on most environments. On Unix and OpenVMS, you can change the check mark character by modifying the value of g_chk_char. On Windows, setting g_chk_char has no effect. |
| 3. | Call S_SELECTCB to enable the user to process the window and toggle the truth value of each item. This subroutine returns when the user selects a menu entry unrecognized by S_SELECTCB. An array is returned from this subroutine with the final values. |
