UI Toolkit addresses an application’s need to process terminal input through an input window. An input window is a standard window that can contain text, input fields, and buttons. Input windows are defined with the .INPUT script command or at runtime with the IB_INPUT subroutine (see Building input windows at runtime).
|
You can also create windows that are made up of input windows, lists, ActiveX controls, and other types of windows. These are referred to as composite windows. They are processed by Toolkit and appear to the user as a single window. See Composite Window Routines. |
Each input field is associated with a position and length within the window, as well as a set of qualifiers that defines how the field should be processed.
Qualifiers
Input field qualifiers enable you to define input field characteristics, which include the following:
- Name for the field
- Type and length of the data
- Number of digits to the right of the decimal point (if numeric)
- Redisplay format (if applicable)
- Defaults that occur as a result of omitted data
- Help message to display
- Selection window to use
- Valid range or set of values (if applicable)
Organization of fields
You define and determine the order of the input fields and field qualifiers in an input window script using the .FIELD command. (See Window Scripts for more information on input window script commands.) Because the maintenance of your field qualifiers takes place in a script file (outside of your application), you can modify the characteristics of your input window or input fields without ever touching your actual code.
The following rules apply to field organization:
- Fields can be placed anywhere in an input window.
- Fields are organized into one or more data areas.
- A specific field can only be specified in one data area definition.
- Each data area can be associated with one or more input sets.
- An input set can consist of one or more fields from a specific data area.
Processing and editing field input
The input utilities support menu entries for moving between and editing input fields (I_xxx menu entries), for editing text (E_xxx menu entries), and for moving around selection windows (S_xxx). These menu entries are often referred to as reserved menu entries.
Applications on Unix and OpenVMS require that you place the corresponding reserved menu entry on a placed menu column to make the function available to the user. Refer to Appendix B: Reserved Menu Entries for a list of the specific menu entries available. On Windows, these reserved menu entries are ignored, as functions are already a part of the Windows environment.
When UI Toolkit processes input for an empty field, it clears the field to blanks and then displays the default value for the field, if one exists. The user can do one of the following:
- Accept the default by pressing Enter.
- Edit the default by selecting any editing function from the menu.
- Enter a new value in the field.
As soon as the user types any character in the field, the field is cleared and the typed character is the first character of the input. If the field doesn’t have a default, input proceeds normally.
Field editing is automatically performed during all input processing. Therefore, if the user moves to a field that already contains data, the user can edit it.
For example, on Unix or OpenVMS, if the entry “E_RIGHT” is present on the menu and the user selects it, Toolkit will move the cursor to the right one character and place the input position at that character. The user can go into edit mode by selecting any one of the “E_” reserved menu entries listed in the I_INPUT Discussion.
Let’s assume a user of an application on Unix or OpenVMS originally typed a telephone number as “3334545,” and the number was reformatted and displayed in the field as “333-4545.” If the user moved back to the field and selected “E_RIGHT,” “333-4545” would be cleared from the field and “3334545” would be redisplayed, left-justified. The user could then edit this data.
If the user presses the Backspace or rubout key at a field that contains data, the field is cleared and the input is redone. If the user presses any other character, the field is cleared and the typed character is used as the first data of the input.
When the user types data in an input field and presses Enter, that data goes into the data area associated with the input field in your program. If the user terminates the input field by selecting a menu entry (for example, a search function) instead of pressing Enter, the field reverts back to its original contents. You must use the I_FORCE subroutine to force the data from the internal input field buffer into the associated data area in your program if this is the action desired. (See IB_END for information on overriding this default behavior.)
By default, Toolkit sets no time limit for input; it waits until I/O processing is completed before returning to the calling subroutine. You can, however, change the default, and you can override the default for a field. Then, if the user does not complete input within the time you specify, input times out. For more information, see the .FIELD qualifier WAIT.
To facilitate redirection of input, UI Toolkit enables you to configure the number of successive end-of-file characters to allow on input. The field g_eof_max (in tkctl.def), which is set at 100 by default, specifies this maximum. After g_eof_max successive EOF characters (Ctrl+D on Unix, Ctrl+Z on OpenVMS) have been encountered, a message is displayed on the screen and the program stops. You can set this field to zero to disable this behavior.
Text fields
Your input windows can contain dimensioned alpha fields that offer full editing capabilities similar to text windows. (Note that only single-dimension alpha arrays are supported. See Text Routines for more information about text windows.) This feature is ideal for any field in which the user must enter a significant amount of text. For example, if a window in your application has a field for comments, the user would probably appreciate being able to edit the text that she types into that field.
The primary difference between edit processing in a text field and edit processing in a text window is that pressing Enter in a text field terminates the field’s input (rather than inserting a new line at the cursor position). We made text input fields work this way so that they would terminate in the same way as all other input fields. But this shouldn’t be a problem; words automatically wrap to a new line during data entry. Also, you can override this action by modifying the value of g_txt_rtrn (defined in the tools.def file).
On Windows, arrayed text fields are displayed as a multi-line edit control. Because the sizing of this field includes extra leading for each line, the edit control will contain extra space into which no text can be entered. You can minimize the amount of extra space by setting the environment variable MINIMIZE_LEADING to 1 and using fixed fonts. When using proportional fonts, if the text field uses a smaller font than the input window, the input window’s background color will extend beyond the bottom of the edit control.
On Unix and OpenVMS, when the user begins performing input to a text field, any specified text editing menu column is placed on the menu bar, and the user can access these editing commands as if the field were a text window. A menu column entry that inserts a new line is available, if you choose to put it in your text editing menu column. You may decide to make only a subset of the editing commands available on the menu for text field entry, since some of the entries are already available for normal field editing, and the user may not need such functions as paragraph movement or top and bottom buffer movement for small amounts of text. See Appendix B: Reserved Menu Entries for a complete list of reserved menu entries.
Understanding display, input, and view lengths
Input fields have the following length settings:
- display length—the maximum number of characters that can be displayed in the field
- input length—the maximum number of characters that the user can enter in the field
- view length—the amount of space (width) on the screen that the field will take
Toolkit automatically calculates the display length and the input length by looking at field settings like size, type, and the format string. Toolkit then uses the greater of the display length or input length to determine the width of the field, which is referred to as the view length.
Typically, Toolkit’s default calculations are sufficient, but you can override them if necessary.
- If you want a field to take up less room on the screen than the greater of the input or display length, set an explicit view length. On Windows this makes the contents of the field scrollable. On Unix and OpenVMS, the contents of a field will be truncated to the view length if you move the cursor in the field or modify the contents of the field.
- Because the input length determines how many characters are passed to a change method, you may want to override the input length to enable users to input more or fewer characters than the field can store. For example, if you store a temperature in Celsius, but allow users to enter a temperature followed by either “F” or “C” to indicate Fahrenheit or Celsius, you could set the input length to 4, while the storage size might allow for only 2 digits. The change method could then convert Fahrenheit temperatures to Celsius before storing the value. See INPUT_LENGTH, NOINPUT_LENGTH for more information on overriding the input length.
- If you have a display method that requires a different display length than the default, you can override the display length. You could set this override, for example, if your display method formats data based on runtime considerations (so you can’t use a format string) and you know you’ll need more or fewer characters than the input length. See DSP_LENGTH, NODSP_LENGTH for more information on overriding the display length.
View length, display length, and input length can be specified in Repository, in a window script (as .FIELD qualifiers), or at runtime (with I_FLDMOD or IB_FIELD).
For more information on these settings, including information on their default values, see DSP_LENGTH, NODSP_LENGTH , INPUT_LENGTH, NOINPUT_LENGTH , and VIEW_LENGTH, NOVIEW_LENGTH .
Building input windows at runtime
In addition to generating input window definitions from script files, you can generate them at runtime. The subroutines that begin with “IB_” (for “input build”) support runtime generation of input windows. These subroutines provide an alternative to defining your input windows in script files.
We recommend that you only use these subroutines when you cannot determine the contents of your input window until runtime. Loading windows from window libraries is faster and more modular than generating windows at runtime.
There is almost a one-to-one correspondence between the IB_xxx subroutines and the script commands that build an input window (along with I_LDINP). For example:
- IB_INPUT provides essentially the same functionality as the .INPUT script command.
- IB_FIELD gives you the same results as the .FIELD script command.
- IB_PAINT corresponds to the .PAINT script command.
These subroutines are also called in the same order as the input window script commands (IB_INPUT, IB_FIELD, …, IB_END).
Each subroutine must be passed a build_id variable, which is initially returned by IB_INPUT. This variable should be an aligned i4.
Multiple fields, sets, and structures are supported, but the fields used in a set or structure must be defined before you define a set or structure. Also, the structure used in a set must be defined before the set.
IB_RPS_STRUCTURE must be called prior to the IB_FIELD calls for fields to be drawn from a repository structure. IB_STRUCTURE can only be used for local fields (fields not drawn from the Repository). Before either IB_RPS_STRUCTURE or IB_LOCAL is called, the default state is local.
IB_INPUT must be called once at the beginning and IB_END once at the end to complete the input window. After IB_END returns successfully, the build_id may be discarded. At this point, the input window is ready to use. Note that build warnings for IB_xxx subroutines display only if g_dtkbounds is set to 1 or 2. And if IB_FIELD creates a text field that is too large for a window, a warning will display only if g_dtkbounds is set to 2 or greater. See g_dtkbounds.
