Chapter 3 Advanced Topics
Now that you have the basic information about dtksh, this chapter introduces you to more advanced topics.
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.
Accessing Event Subfields
The XEvent structure has many different configurations, based on the event's type. dtksh provides access only to the most frequently used XEvents. Any of the other standard XEvents can be accessed using the event type XANY, followed by any of the subfields defined by the XANY event structure, which includes the following subfields:
-
${TRANSLATION_EVENT.XANY.TYPE}
-
${TRANSLATION_EVENT.XANY.SERIAL}
-
${TRANSLATION_EVENT.XANY.SEND_EVENT}
-
${TRANSLATION_EVENT.XANY.DISPLAY}
-
${TRANSLATION_EVENT.XANY.WINDOW}
dtksh supports full access to all of the event fields for the following event types:
-
XANY
-
XBUTTON
-
XEXPOSE
-
XNOEXPOSE
-
XGRAPHICSEXPOSE
-
XKEY
-
XMOTION
The following examples show how the subfields for the preceding event types can be accessed:
${TRANSLATION_EVENT.XBUTTON.X}
$(CB_CALL_DATA.EVENT.XKEY.STATE)
${EH_EVENT.XGRAPHICSEXPOSE.WIDTH}
Responding to a Window Manager Close Notice
When the user selects Close from the Window Manager menu for an application, the application is terminated unless it has arranged to "catch" the Close notification. If the application does not catch the notification, then multiple windows managed by the application all disappear and application data may be left in an undesirable state. To avoid this, dtksh provides for catching and handling the Close notification. The application must:
-
Define a procedure to handle the Close notification
-
Request notification when Close is selected
-
Override the response, so the application is not shut down
The following code illustrates this processing.
# This is the `callback' invoked when the user selects
# the `Close' menu item
WMCallback()
{
echo "User has selected the Close menu item"
}
# Create the toplevel application shell
XtInitialize TOPLEVEL test Dtksh $0 "$@"
XtDisplay DISPLAY $TOPLEVEL
# Request notification when the user selects the `Close'
# menu item
XmInternAtom DELETE_ATOM $DISPLAY "WM_DELETE_WINDOW" false
XmAddWMProtocolCallback $TOPLEVEL $DELETE_ATOM "WMCallback"
# Ask Motif to not automatically close down your
# application window
XtSetValues $TOPLEVEL deleteResponse:DO_NOTHING
Responding to a Session Manager Save State Notice
Session Manager allows applications to save their current state when the user terminates the current session, so that when the user later restarts the session, an application can return to the state it was in. In dtksh, this is accomplished by setting up a handler in a similar way of handling a Close notification. If a handler is not set up, the application has to be restarted manually in the new session, and the application does not retain any state.
To set up a handler to save the current state, the application must:
-
Define functions to save the state at the end of the session and to restore it on startup
-
Register interest in the Session Manager notification
-
Register the function to save the state
-
At startup, determine whether the saved state should be restored
The following code illustrates this process.
#! /usr/dt/bin/dtksh
# Function invoked when the session is being ended by the user
SessionCallback()
{
# Get the name of the file into which we should save our
# session information
if DtSessionSavePath $TOPLEVEL PATH SAVEFILE; then
exec 9>$PATH
# Save off whether we are currently in an iconified state
if DtShellIsIconified $TOPLEVEL ; then
print -u9 `Iconified'
else
print -u9 `Deiconified'
fi
# Save off the list of workspaces we currently reside in
if DtWsmGetWorkspacesOccupied $(XtDisplay "-" $TOPLEVEL) \
$(XtWindow "-" $TOPLEVEL) \
CURRENT_WS_LIST ;
then
# Map the comma-separated list of atoms into
# their string representation
oldIFS=$IFS
IFS=","
for item in $CURRENT_WS_LIST;
do
XmGetAtomName NAME $(XtDisplay "-" $TOPLEVEL) \
$item
print -u9 $NAME
done
IFS=$oldIFS
fi
exec 9<&-
# Let the session manager know how to invoke us when
# the session is restored
DtSetStartupCommand $TOPLEVEL \
"/usr/dt/contrib/dtksh/SessionTest $SAVEFILE"
else
echo "DtSessionSavePath FAILED!!"
exit -3
fi
}
# Function invoked during a restore session; restores the
# application to its previous state
RestoreSession()
{
# Retrieve the path where our session file resides
if DtSessionRestorePath $TOPLEVEL PATH $1; then
exec 9<$PATH
read -u9 ICONIFY
# Extract and restore our iconified state
case $ICONIFY in Iconified) DtSetIconifyHint $TOPLEVEL True;;
*) DtSetIconifyHint $TOPLEVEL False;
esac
# Extract the list of workspaces we belong in, convert
# them to atoms, and ask the Workspace Manager to relocate
# us to those workspaces
WS_LIST=""
while read -u9 NAME
do
XmInternAtom ATOM $(XtDisplay "-" $TOPLEVEL) \
$NAME False if [ ${#WS_LIST} -gt 0 ]; then
WS_LIST=$WS_LIST,$ATOM
else
WS_LIST=$ATOM
fi
done
DtWsmSetWorkspacesOccupied $(XtDisplay "-" $TOPLEVEL) \
$(XtWindow "-" $TOPLEVEL) $WS_LIST
exec 9<&-
else
echo "DtSessionRestorePath FAILED!!"
exit -3
fi
}
################## Create the Main UI #######################
XtInitialize TOPLEVEL wmProtTest Dtksh $0 "$@"
XtCreateManagedWidget DA da XmDrawingArea $TOPLEVEL \
height:200 width:200
XmInternAtom SAVE_SESSION_ATOM $(XtDisplay "-" $TOPLEVEL) \
"WM_SAVE_YOURSELF" False
# If a command-line argument was supplied, then treat it as the
# name of the session file
if (( $# > 0))
then
# Restore to the state specified in the passed-in session file
XtSetValues $TOPLEVEL mappedWhenManaged:False
XtRealizeWidget $TOPLEVEL
XSync $(XtDisplay "-" $TOPLEVEL) False
RestoreSession $1
XtSetValues $TOPLEVEL mappedWhenManaged:True
XtPopup $TOPLEVEL GrabNone
else
# This is not a session restore, so come up in the default state
XtRealizeWidget $TOPLEVEL
XSync $(XtDisplay "-" $TOPLEVEL) False
fi
# Register the fact that we are interested in participating in
# session management
XmAddWMProtocols $TOPLEVEL $SAVE_SESSION_ATOM
XmAddWMProtocolCallback $TOPLEVEL $SAVE_SESSION_ATOM \
SessionCallback
XtMainLoop
Cooperating with Workspace Manager
dtksh provides access to all of the major Workspace Manager functions of the Dt libraries, including functions for querying and setting the set of workspaces with which an application is associated; for querying the list of all workspaces; for querying and setting the current workspace; and for requesting that an application be notified any time the user changes to a different workspace.
From a user's perspective, workspaces are identified by a set of names, but from the Workspace Manager's standpoint, workspaces are identified by X atoms. Whenever the shell script asks for a list of workspace identifiers, a string of X atoms is returned. If more than one X atom is present, then the list is comma-separated. The Workspace Manager expects that the shell script uses the same format when passing workspace identifiers back to it. During a given session, it is safe for the shell script to work with the X atoms, since they remain constant over the lifetime of the session. However, as was shown in the Session Manager shell script example in the previous section, if the shell script is going to save and restore workspace identifiers, the identifiers must be converted from their X atom representation to a string before they are saved. Then, when the session is restored, the shell script needs to remap the names into X atoms before passing the information on to the Workspace Manager. Mapping between X atoms and strings, and between strings and X atoms, is accomplished using the following two commands:
-
XmInternAtom ATOM $DISPLAY $WORKSPACE_NAME false
-
XmGetAtomName NAME $DISPLAY $ATOM
Specific dtksh commands for dealing with workspace management are documented in "Built-in libDt Session Management Commands" in Appendix A.
Creating Localized Shell Scripts
dtksh scripts are internationalized and then localized in a process similar to C applications. All strings that may be presented to the user are identified in the script. A post-processor extracts the strings from the script and, from them, builds a catalogue, which can then be translated to any desired locale. When the script executes, the current locale determines which message catalog is searched for strings to display. When a string is to be presented, it is identified by a message-set ID (corresponding to the catalog) and a message number within the set. These values determine what text the user sees. The following code illustrates the process:
# Attempt to open our message catalog catopen MSG_CAT_ID "myCatalog.cat" # The localized button label is in set 1, and is message # 2 XtCreatePushButton OK $PARENT ok \ labelString:$(catgets $MSG_CAT_ID 1 2 "OK") # The localized button label is in set 1, and is message #3 XtCreatePushButton CANCEL $PARENT cancel \ labelString:$(catgets $MSG_CAT_ID 1 3 "Cancel") # Close the message catalog, when no longer needed catclose $MSG_CAT_ID
It is important to note that the file descriptor returned by catopen must be closed using catclose and not by using the kshell exec command.
Using dtksh to Access X Drawing Functions
dtksh commands include standard Xlib drawing functions to draw lines, points, segments, rectangles, arcs, and polygons. In the standard C programming environment, these functions take a graphics context (GC) as an argument, in addition to the drawing data. In dtksh drawing functions, a collection of GC options are specified in the parameter list to the command.
By default, the drawing commands create a GC that is used for that specific command and then discarded. If the script specifies the -gc option, the name of a graphics context object can be passed to the command. This GC is used in interpreting the command, and the variable is updated with any modifications to the GC performed by the command.
- -gc <GC>
-
<GC> is the name of an environment variable which has not yet been initialized or which has been left holding a graphic context by a previous drawing command. If this option is specified, then it must be the first GC option specified.
- -foreground <color>
-
The foreground color, which may be either the name of a color or a pixel number.
- -background <color>
-
The background color, which may be either the name of a color or a pixel number.
- -font <font name>
-
The name of the font to be used.
- -line_width <number>
-
The line width to be used during drawing.
- -function <drawing function>
-
The drawing function, which can be xor, or, clear, and, copy, noop, nor, nand, set, invert, equiv, andReverse, orReverse, or copyInverted.
- -line_style <style>
-
The line style, which can be any of the following: LineSolid, LineDoubleDash, or LineOnOffDash.
Setting Widget Translations
dtksh provides mechanisms for augmenting, overriding, and removing widget translations, much as in the C programming environment. In C, an application installs a set of translation action procedures, which can then be attached to specific sequences of events (translations are composed of an event sequence and the associated action procedure). Translations within dtksh are handled in a similar fashion, except only a single action procedure is available. This action procedure, named ksh_eval, interprets any parameters passed to it as dtksh commands and evaluates them when the translation is triggered. The following shell script segment gives an example of how translations can be used:
BtnDownProcedure()
{
echo "Button Down event occurred in button "$1
}
XtCreateManagedWidget BUTTON1 button1 XmPushButton $PARENT \
labelString:"Button 1" \
translations:'#augment
<EnterNotify>:ksh_eval("echo Button1 entered")
<Btn1Down>:ksh_eval("BtnDownProcedure 1")'
XtCreateManagedWidget BUTTON2 button2 XmPushButton $PARENT \
labelString:"Button 2"
XtOverrideTranslations $BUTTON2 \
'#override
<Btn1Down>:ksh_eval("BtnDownProcedure 2")'
- © 2010, Oracle Corporation and/or its affiliates