Using Context Variables

dtksh has a number of variables that provide context to certain aspects of an application.

Event Handler Context Variables

An application registers event handlers with a widget to specify an action to occur when one of the specified events occurs. The action can be any arbitrary dtksh command line. For example:

XtAddEventHandler $W "Button2MotionMask" false "ActivateProc" 
XtAddEventHandler $W "ButtonPressMask|ButtonReleaseMask" \
       false "echo action"

Two environment variables are defined to provide context to the event handler:

EH_WIDGET

Set to the ID of the widget for which the event handler is registered.

EH_EVENT

Set to the address of the XEvent which triggered the event handler.

Access to the fields within the XEvent structure is shown in the following example:

if [ ${EH_EVENT.TYPE} = "ButtonPress" ]; then
        echo "X = "${EH_EVENT.XBUTTON.X}
        echo "Y= "${EH_EVENT.XBUTTON.Y}
     elif [ ${EH_EVENT.TYPE} = "KeyPress" ]; then     
			  echo "X = "${EH_EVENT.XKEY.X}
        echo "Y = "${EH_EVENT.XKEY.Y}    
fi

Translation Context Variables

The Xt Intrinsics provides for event translations to be registered for a widget. Context for event translation is provided in the same way it is provided for event handlers. The two variables defined for translation commands are:

TRANSLATION_WIDGET

Set to the widget handle for the widget for which the translation is registered.

TRANSLATION_EVENT

Set to the address of the XEvent that triggered the translation.

Dot-notation provides access to the fields of the event:

echo "Event type = "${TRANSLATION_EVENT.TYPE} 
echo "Display ="${TRANSLATION_EVENT.XANY.DISPLAY}

Workspace Callback Context Variables

An application has the ability to register a callback function that is invoked whenever the user changes to a new workspace. When the callback is invoked, two special environment variables are set, and can be accessed by the shell callback code:

CB_WIDGET

Set to the ID for the widget that is invoking the callback.

CB_CALL_DATA

Set to the X atom that uniquely identifies the new workspace. This can be converted to its string representation, using the XmGetAtomName command.

Input Context Variables

The Xt Intrinsics provides the XtAddInput facility, which allows an application to register interest in any data available from a particular file descriptor. When programming in C, the application provides a handler function, which is invoked when input is available. It is up to the handler to read the data from the input source and to handle character escaping and line continuations.

dtksh also supports the XtAddInput facility, but takes it a step further and makes it easier for shell programmers to use. By default, when a shell script registers interest in a file descriptor, dtksh invokes the shell script's input handler only when a complete line of text has been received. A complete line of text is defined as a line terminated either by an unescaped newline character or by the end of the file. The input handler is also called if no data is available and the end of the file has been reached. The handler can then use XtRemoveInput to remove the input source and to close the file descriptor. The advantage of this default behavior is that input handlers need not be concerned with escape processing or with handling line continuations. The disadvantage is that it assumes that all of the input is line-oriented and contains no binary information.

dtksh also supports a "raw" input mode if the input source contains binary information or if the input handler wants to read the data from the input source directly. In raw mode, dtksh does not read any of the data from the input source. Whenever dtksh is notified that input is available on the input source, it invokes the shell script's input handler. It is then the handler's responsibility to read the incoming data, perform any required buffering and escape processing, and detect when the end of the file has been reached (so that the input source can be removed and the file descriptor closed). This mode seldom needs to be used by a dtksh script.

Whether the input handler has been configured to operate in the default mode or in raw mode, dtksh sets up several environment variables before calling the shell script's input handler. These environment variables provide the input handler with everything needed to handle the incoming data. The environment variables are:

INPUT_LINE

If operating in the default mode, this variable contains the next complete line of input available from the input source. If INPUT_EOF is true, then there is no data in this buffer. If operating in raw mode, then this variable always contains an empty string.

INPUT_EOF

If operating in the default mode, this variable is set to false anytime INPUT_LINE contains data, and it is set to true when the end of file is reached. When the end of file is reached, the shell script's input handler should unregister the input source and close the file descriptor. If operating in raw mode, this variable is always set to false.

INPUT_SOURCE

This indicates the file descriptor for which input is available. If operating in raw mode, this file descriptor is used to obtain the pending input. The file descriptor is also used to close the input source, when no longer needed.

INPUT_ID

This indicates the ID returned by XtAddInput, when the input source was originally registered. This information is needed to remove the input source with XtRemoveInput.