Inputting data into textboxes or change button states¶
input |
Input data into textboxes or change button states |
Contents
SYNTAX
Moves input focus to each control in the list in turn, and allows the user to input data into a textbox, or change the state of a button.
The input command may be used on controls whose window is hidden, provided that the window is not disabled.
A hidden control may receive input. Input into a hidden textbox is not very useful, but the technique of inputting into hidden buttons may be used to determine if the user has clicked on a particular part of the screen.
A disabled control cannot receive input focus and is skipped by the input command.
If a control has a help caption assigned, and caption display is turned on, the caption is displayed while the control has input focus.
The input command differs from the related dialog command in that it forces the user to move to each control in turn, in the order specified, whereas in the dialog command all enabled controls in the window are available for activation and input with the mouse or the keyboard. Additionally, input can only be used with textboxes and buttons. It is recommended that the input command be treated as obsolescent and dialog used in its place.
control_id [, control_id] |
Each control_id may be any of the following:
A single input command may contain different control types. The command functions differently according to whether a textbox or button is being input, so these two input types are documented separately below. |
||||||
[Bs = label] |
Traps the condition where the user presses the BACKSPACE key while the input command is active. If the input command has a single control, program control passes to the line indicated by label. If the input command has a control list (two or more controls), and the user presses the BACKSPACE key while the first control has focus, program control passes to the line indicated by label. Pressing BACKSPACE from a control other than the first in the list causes focus to move to the previous control. The return value CANCEL_DIALOG from a textbox validation function has the same effect as pressing BACKSPACE from the first control in the list. |
||||||
[eoi = label] |
The eoi condition is generated if the user prematurely terminates data entry during the input command by pressing the EOI key (defined in the terminal parameter file Section 7, Entry 1[44].) The ESC key is most commonly used. The EOI key behaves in the same way as the RETURN key if there is no eoi = clause. |
||||||
[ni = label] |
The ni clause specifies a line to which control is to be transferred if no fields are changed by the input command. Control passes to the line indicated by label. |
||||||
[traps = label] |
General purpose trap clause that traps any condition not explicitly trapped, passing control to the line indicated by label. It has the lowest priority, and is only invoked if a trappable condition has not been more explicitly trapped. |
Input into textboxes¶
input box_id[[subscript]]
Moves input focus to the textbox specified in order to input data into the field linked to it. Note that it is the textbox and not the field whose identifier must be supplied. The current value of the linked field is displayed in the textbox. The cursor is positioned in the textbox, and the program awaits input from the user.
If the textbox has an event function defined, any program code assigned to the event EV_GAIN_FOCUS is executed as soon as the textbox receives focus, and before the user has a chance to input data.
If the textbox is multi-row, input is into the row specified by subscript. If subscript is greater than the number of rows specified, it wraps around - so if subscript were equal to 10, but there were only 6 boxes, the fourth box would be selected. If the textbox has rows and no subscript is specified, the value of the Sculptor system variable sys.Row is used to determine the row to be used. This variable, which is initially set to 1 when a program loads, may be altered by direct assignment or by use of the setrow command.
A textbox group may be included in a list of input controls. The effect of this is to input into each textbox in the group, in the order in which the boxes are defined in the program code.
A field may be linked to more than one textbox. When a field is updated by an input command, no change is made to other textboxes containing this field. Only a display or input into such a textbox causes the amended value of the field to be displayed.
It is possible to call another input statement from a function attached to a textbox. There is no specific limit to the number of input commands that may be nested at any one time.
It is possible to close a window during input into a textbox in that window, or during execution of a function attached to the textbox, or during execution of a function or subroutine called by pressing a function key during input. When this occurs the window is automatically reopened when control returns to the input statement.
RELATED TOPICS |
Input into buttons¶
input button_id
The input command, when applied to a button, enables the user to change the button’s state. The button receives input focus and awaits input from the user.
If the button has an event function defined, any program code assigned to the event EV_GAIN_FOCUS is executed as soon as the button receives focus, and before the user has a chance to input data
It is frequently appropriate to input into a button group. In the case of radio and checkbox type button groups, inputting into the group, rather than individual buttons, is really the only method that makes any sense.
Push button groups |
The effect of inputting into an push button group is to input into each button individually, in the order in which the buttons appear in the program code. |
Radio groups |
The input command, when executed for a radio group, first moves focus to the currently selected button. The RIGHT ARROW or DOWN ARROW keys move to the next button in the group, checking that button and unchecking the previously checked button. LEFT ARROW and UP ARROW move to the previous button in the group with the same effect. The TAB and BACKTAB keys move out of the group altogether, passing focus to the next control in the input list (TAB) or the previous control (BACKTAB). |
Checkbox groups |
The input command, when executed for a checkbox group, moves focus to the first button in the group. The user may then move through the buttons in the group, using the RIGHT ARROW or DOWN ARROW key to move to the next button, and the LEFT ARROW or UP ARROW key to move to the previous button. Checkbox buttons are not automatically checked or unchecked. Pressing SPACE toggles the state of the currently focused button. |
For any group type, when the operation is complete, press the EOI key (normally ESC) to terminate the input.
The CANCEL key for the input command is defined in the terminal parameter file. It is most commonly CTRL-X. If this key is pressed during an input command the buttons revert to their original states.
When the user presses the RETURN key on a push button during an input operation, the button is momentarily selected before reverting to its normal state. If the button has an event function defined, any program code assigned to the event EV_BUTTON_DOWN, and then to the event EV_BUTTON_UP (or EV_BUTTON_CLICKED) is executed. The HOME key may be used to press a button down, and the END key to release it. This allows a toggle effect on a push button.
A button may also have, defined in the event function, actions which should be executed if the button loses focus. This event is defined as EV_LOSE_FOCUS. This occurs when the currently focused button loses focus, because the user has moved to a different button, or terminated the input operation by closing or cancelling the dialog.
RELATED TOPICS |
Validation¶
When data has been entered into a textbox, it is validated. The program then continues as follows:
Data valid |
The data is assigned to the field, and the input command proceeds to the next control_id in the list. If there are no more controls specified, program control continues with the next statement. If the field is linked to other textboxes, their display is not updated. The new value of the field can only be displayed by executing an input or display into the other textboxes containing it. |
Data invalid |
The textbox is locked in focus and the cursor remains in the textbox for the data to be re-entered. |
Interrupting input with a function key¶
During an input command, a function key may be pressed which causes the execution of a function or subroutine. However, at the point when control passes to the function or subroutine any changes to the current input field have not yet been stored.
The current values of the Sculptor default subscript variables sys.Col, sys.Row, sys.Plane and sys.Dim4 are automatically saved when the function or subroutine is called, and restored after it returns. Note that this is not the case with validation, help and event functions.
RELATED TOPICS |