I_CTRCONTEXT

Establish input context for child input window

xcall I_CTRCONTEXT(inp_id, [set_name], reason)

Arguments

inp_id

The ID of the child input window. (n)

set_name

(optional) The name of the input set to receive input context or *CURR* to use the currently active input set. *CURR* must be in capital letters and enclosed in quotation marks. (a)

reason

The reason the input window was activated, which determines what I_CTRCONTEXT will move input context to. This argument can be passed as blank (indicating that it was already activated), a program-supplied reason passed because it was activated programmatically, or one of the following: (a)

C_FIRST

Focus moved in attempt to reach the first child in the composite window. This instructs I_CTRCONTEXT to move context to the first active field in the input set. If there is no active field, context moves to the first button for the window.

C_LAST

Focus moved in attempt to reach the last child in the composite window. This instructs I_CTRCONTEXT to move context to the last active button on the tab set (if the window is on a tab). If there is no such button, it moves context to the last active button for the window. If there’s no active button for the window, it moves context to the last input field in the input set.

C_NEXT

Focus moved from the previous child in the composite window—e.g., by pressing Tab. This instructs I_CTRCONTEXT to move context to the first active field in the input set. If there is no active field, context moves to the first button for the window.

C_PREV

Focus moved from the next child in the composite window—e.g., by pressing Shift+Tab. This instructs I_CTRCONTEXT to move focus to the last active button on the tab set (if the window is on a tab). If there is no such button, it moves focus to the last active button for the window. If there’s no active button for the window, it moves focus to the last input field in the input set.

C_SET

Child explicitly activated. For example, this could be the result of a mouse click, or it could be that the child was activated programmatically without a specified reason. With this reason, I_CTRCONTEXT does not change focus.

If reason is blank or any value other than the above, I_CTRCONTEXT does not change input context.

Discussion

Like I_NEXT, the I_CTRCONTEXT subroutine sets input context for an input window. Unlike I_NEXT, however, it uses a reason to determine where to set input context. This is because I_CTRCONTEXT is designed for use in child input window methods (C_METHINP by default), where you likely want input context to initially reflect the reason the input window received focus. For example, if you have a composite window with two input windows for children, and the user presses Shift+Tab to move from the second input window back to the first, you may want the last button or field in the first input window to receive input context.

To use in a child method, pass the reason passed to the child method (by C_PROCESS) as the reason argument for I_CTRCONTEXT. See the ctrmeths.dbl file included in your UI Toolkit distribution for an example. This file includes code for the C_METHINP method, which uses I_CTRCONTEXT.

The set_name argument determines which input set will be used to set input context.

If the name of an input set in the window is passed as set_name, I_CTRCONTEXT uses this input set to determine input context.
If set_name is passed as *CURR*, I_CTRCONTEXT uses the most recently accessed input set for the window. If no input set has been accessed, input context defaults to the first input set for the window to determine input set context.
If set_name is not passed, I_CTRCONTEXT uses the first input set to determine input context.

Note that in a utility subroutine where you do not know the name of the currently active set, you can use *CURR* to specify the set that was most recently accessed in the window.