E_STATE

Modify the state of the current environment

xcall E_STATE([state, ...])

Arguments

state

(optional) One or more (up to 10) of the following codes. The meaning of each is dependent on the preceding arguments. (n)

D_ON

Turn on (set) options. (default)

D_OFF

Turn off (reset) options.

D_CBADVANCE

Advance context for combo boxes.

D_CURSOR

Display a screen cursor.

D_ECHO

Echo terminal input.

D_EURO

Allow European formatting conventions.

D_INPPRCRND

Apply the Input Field Processing or Read-Only Input Field Processing renditions to the field that has focus during input processing.

D_INPRNDOVER

Override field-level rendition settings (color and attribute settings) with Input Field Processing or Read-Only Input Field Processing renditions. (D_INPPRCRND must also be set to D_ON for this to work.)

D_INTR

Allow interrupt characters.

D_LOCKWAIT

Wait for locked records.

D_LOWER

Allow lowercase terminal input.

D_MSGWAIT

Wait for messages.

D_RETURNBTN

Enter key simulates a key press of the default button. (Windows only; ignored on UNIX and OpenVMS)

D_VALSTCHG

Validate immediately on a state change of certain field types.

Discussion

E_STATE sets or modifies the following states or behavior for the current environment:

Synergy DBL FLAGS subroutine states
Synergy DBL DFLAG subroutine states
Synergy low-level window system states
UI Toolkit behavior

The D_ON and D_OFF codes indicate whether the codes that follow in the argument list are to be turned on or off. D_ON is the default for any code that is passed as a state argument. (For example, if you pass D_INPRNDOVER without passing D_ON or D_OFF, D_INPRNDOVER is set to on, even though it is turned off by default.)

U_START sets all environment states to their defaults. Use E_STATE after calling U_START to modify these states. You must use E_STATE exclusively to manipulate the specified states. If you directly manipulate them in any other way, the states as they are “known” by the UI Toolkit environment may be incorrect.

A special case occurs when you don’t pass any arguments to E_STATE. In this case, all environment states are assumed to be unknown, and they are set or reset according to the current environment level.

Codes D_EURO, D_LOWER, D_ECHO, and D_INTR refer to controls 1, 2, 5, and 8 of the FLAGS subroutine, respectively. The codes D_MSGWAIT and D_LOCKWAIT refer to controls 2 and 3 of the DFLAG subroutine, respectively. The D_CURSOR code refers to the WP_CURSOR function state of the W_PROC subroutine.

When D_INPPRCRND is set to D_ON, Toolkit applies the Input Field Processing or Read-Only Input Field Processing renditions to the currently active input field during I_INPUT or I_INPFLD processing. When D_INPPRCRND is set to D_OFF, Toolkit does not change renditions for the active field. (By default, D_INPPRCRND is set to D_OFF on Windows and D_ON on UNIX and OpenVMS.) For information on renditions see Renditions and rendition schemes.

Note the following:

To instruct Toolkit to override field-level rendition settings (.FIELD, I_FLDMOD, and IB_FIELD settings) with Input Field Processing renditions, set D_INPRNDOVER and D_INPPRCRND to D_ON. By default, D_INPRNDOVER is set to off, so field-level rendition settings override the Input Field Processing renditions.
On Windows, D_INPPRCRND does not affect screen updates caused by calls to W_DISP. (So neither Input Field Processing nor Read-Only Input Field Processing renditions are used in this case.)

The D_VALSTCHG code allows immediate validation of check boxes, radio buttons, and combo boxes. Immediate validation occurs when a check box is toggled, the selected entry of a group of radio buttons is changed or the selected item in a combo box is changed. Validation means that the entry will pass through any Toolkit tests as well as any change method specified, and, if it passes, the associated data area will be updated with the new contents and any break processing would then occur. Focus will remain on this field unless the change method or break processing forces a change of focus (for instance, by calling I_NEXT) or D_CBADVANCE is specified. Likewise, leave and arrive methods will not be invoked unless such a change of focus occurs.

To enable or disable this option per field, toggle the option in the field’s arrive method.

The E_STATE subroutine does not affect displays during input processing. (.FIELD controls the displays in this situation.) For example, during input processing, the echo state won’t be altered.

Any E_STATE option can be set within private environments, and E_EXIT will revert the option to the value defined in the previous environment level.

E_STATE on Windows

When D_CBADVANCE is turned on, which it is by default, context will advance when the user selects an entry in a combo box by using its drop-down list. If the list is not dropped down, or if D_CBADVANCE is turned off, the context will remain on that field. If a user presses Enter or the tab key while in a combo box (the field or the drop-down list), context is advanced to the next field regardless of the D_CBADVANCE setting. If you always want the context to advance, regardless of how the user selects the item, you will need to handle this by using I_NEXT.

If you disable interrupt characters using the following combination: D_OFF, D_INTR, the close box and the “Close” entry (in the Windows system menu), your Windows application will also be disabled. To provide true Windows look-and-feel in your application, you should not disable interrupt characters, and you should support an application close method that performs a clean shutdown of your application.

D_RETURNBTN determines the behavior of the Enter key on Windows systems. It is ignored on UNIX and OpenVMS. If D_RETURNBTN is set, pressing the Enter key will simulate pressing the default button. The default button is visually indicated by a thicker border around the button. If the default button is not specified, it will be the first button in the tabbing order. In this case, when a window has no buttons but its tab set container does, the first button on the tab set is the default button. A tab set cannot have a default button when a list is on the current tab.

If a tab set container and its contained window both have buttons, the following rules are used to determine which button is the default:

If only one, either the contained window or the tab set container, defines a default button, the specified button is the default button.
If neither the contained window nor the tab set container defines a default button, the first button on the contained window is the default button.
If both the contained object and the tab set container define a default button, the default button of the contained window is the default button.