test

Common Desktop Environment: Desktop KornShell User's Guide

Using Desktop KornShell to Create Motif Applications

This section describes how to use dtksh to create Motif applications. To successfully use dtksh, you should have experience with Xlib, the Xt Intrinsics, the Motif widgets, and KornShell programming. It is also helpful to know the C programming language. If you are not familiar with any of these, you should refer to the appropriate documentation. Even if you are familiar with these systems, you should have access to the applicable man pages for reference.

In addition, your system should have these libraries:

Resources

Resources are widget variables that you use to define attributes such as size, location, or color. Each widget usually has a combination of its own resources, plus resources it inherits from higher level widgets. Xt Intrinsics and Motif resource names consist of a prefix (XtN or XmN) followed by the base name. The first letter of the base name is always lowercase, and the first letter of subsequent words within the base name is always uppercase. The convention for resource names in dtksh scripts is to delete the prefix and use the base name. Thus, the resource XmNtopShadowColor becomes topShadowColor.

Some Xt and Motif commands allow the shell script to pass in a variable number of parameters, representing resource-value pairs. This is similar to the argument list passed to the corresponding Xt or Motif C function. Examples include any of the commands used to create a widget, plus the XtSetValues command. In dtksh, resources are specified by a string with the following syntax: 

resource:value

where resource is the name of the resource and value is the value assigned to the resource. dtksh automatically converts the value string to an appropriate internal representation. For example:

XtSetValues $WIDGET height:100 width:200 resizePolicy:RESIZE_ANY
XmCreateLabel LABEL $PARENT myLabel labelString:"Close Dialog"

When you retrieve widget resource values using XtGetValues, the return value is placed in an environment variable. Thus, unlike the Xt Intrinsics, the dtksh version of XtGetValues uses a name:(environment) variable pair, rather than a name:value pair. For example: 

XtGetValues $WIDGET height:HEIGHT resizePolicy:POLICY             
		sensitive:SENSITIVE  echo $HEIGHT  echo $POLICY  echo

$SENSITIVE

The preceding dtksh segment might produce this output:

100  RESIZE ANY 
TRUE

Certain types of resource values, including string tables and bit masks, have special representation. For example, the List widget allows a string table to be specified for both the items and selectedItems resources. In dtksh, a string table is represented as a comma-separated list of strings, which is similar to how Motif treats them. When a resource that returns a string table is queried using XtGetValues, the resulting value is a comma-separated set of strings.

A resource that expects a bit mask value to be passed to it expects the mask to be specified as a string composed of the various mask values separated by the |(bar) character. When a resource that returns a bit mask is queried, the return value is a string representing the enabled bits, separated by the | character. For example, you could use the following command to set the mwmFunctions resource for the VendorShell widget class: 

XtSetValues mwmFunctions: MWM_FUNC_ALL|MWM_FUNC_RESIZE

Unsupported Resources

dtksh supports most of the Motif resources. The following lists unsupported resources. Resources with an * (asterisk) can be specified at widget creation time by using XtSetValues, but can't be retrieved using XtGetValues.

dtksh app-defaults File

The dtksh app-defaults file, named Dtksh, is found in a location based on the following path description: 

/usr/dt/app-defaults/<LANG>

The only information contained in this app-defaults file is the inclusion of the standard Dt base app-defaults file. The following is a listing of the dtksh app-defaults file:

#include
"Dt"

The file Dt is also located in /usr/dt/app-defaults/<LANG> and is shown in the following listing.

*foregroundThreshold: 
70   
!###  
!#  
!#   Help system specific resources  
!#  
!###   
!#  
!#  Display Area Colors  
!#  
!#     These resources set the colors for the display area(where  
!#     actual help text is displayed).  The resources are complex  
!# 	 because they have to override the standard color resources  
!#     in all cases.  
!#  
*XmDialogShell.DtHelpDialog*DisplayArea.background: White 
*XmDialogShell*XmDialogShell.DtHelpDialog*DisplayArea.background: White 
*XmDialogShell.DtHelpDialog*DisplayArea.foreground: Black 
*XmDialogShell*XmDialogShell.DtHelpDialog*DisplayArea.foreground: Black   
!# 

!#  Menu Accelerators  
!#  
!#     The following resources establish keyboard accelerators  
!#     for the most frequently accessed menu commands.  
!#  

*DtHelpDialogWidget*searchMenu.keyword.acceleratorText: Ctrl+I 
*DtHelpDialogWidget*searchMenu.keyword.accelerator:  Ctrl<Key>i 
*DtHelpDialogWidget*navigateMenu.backTrack.acceleratorText: Ctrl+B 
*DtHelpDialogWidget*navigateMenu.backTrack.accelerator:  Ctrl<Key>b 
*DtHelpDialogWidget*navigateMenu.homeTopic.acceleratorText: Ctrl+H 
*DtHelpDialogWidget*navigateMenu.homeTopic.accelerator:  Ctrl<Key>h 
*DtHelpDialogWidget*fileMenu.close.acceleratorText:      Alt+F4 
*DtHelpDialogWidget*fileMenu.close.accelerator: Alt<Key>f4

Variable Values

This section describes the types of values for some of the variables in a dtksh app-defaults file.

Defined Values

The C bindings of the interfaces to X, Xt and Motif include many nonstring values that are defined in header files. The general format of such values consists of an Xt or Xm prefix followed by a descriptive name. For example, one of the constraint values for a child of a form widget is XmATTACH_FORM. Equivalent values are specified in dtksh by dropping the prefix, just as in a Motif defaults file:

Boolean Values

You can specify a Boolean value as a parameter to a dtksh command using the words True or False; case is not significant. A Boolean result is returned as either True or False, using all lowercase letters.

Return Values

Graphical commands in dtksh fall into one of four categories, based on the definition of the corresponding C function:

  1. The function is void and returns no values. Example: XtMapWidget()

  2. The function is void, but returns one or more values through reference parameters. Example: XmGetColors()

  3. The function returns a non-Boolean value. Example: XtCreateManagedWidget()

  4. The function returns a Boolean value. Example: XtIsSensitive()

Category 1

A dtksh category 1 command follows the calling sequence of its corresponding C function. The number and order of parameters can be determined by looking at the standard documentation for the function. Example: 

XtMapWidget $FORM

Category 2

A dtksh category 2 command also generally follows the calling sequence of its corresponding C function. It returns a value in an environment variable, instead of passing a pointer to a return variable. Example: 

XmGetColors $FORM $BG FOREGROUND TOPSHADOW BOTTOMSHADOW SELECT  
echo "Foreground color = " $FOREGROUND

Category 3

A dtksh category 3 command differs slightly from its corresponding C function. Where the C function returns its value as the value of the procedure call, a dtksh command requires an additional parameter. This parameter is the name of an environment variable into which the return value is to be placed. It is always the first parameter. Example: 

XmTextGetString TEXT_VALUE $TEXT_WIDGET  
echo "The value of the text field is "$TEXT_VALUE

Category 4

A dtksh category 4 command returns a value that can be used in a conditional expression just as in C. If the C function also returns values through reference variables (as in category 2), the dtksh command also uses variable names for the corresponding parameters. Example: 

if XmIsTraversable $PUSH_BUTTON; then  
echo "The pushbutton is traversable"  
else 
echo "The pushbutton is not traversable"  fi

Generally, the order and type of parameters passed to a command matches those passed to the corresponding C function, except as noted for category 3 commands.

Immediate Return Value

Many of the category 3 commands return a single value using an environment variable specified as the first parameter to the command (for these special commands, the first parameter has the name variable). If this return value is immediately used in an expression, the special environment variable "-" may be used in place of a variable name. When dtksh encounters "-" as the name of the environment variable in which the return value is to be returned, it instead returns the result as the value of the command. This allows the shell script to embed the command call in another command call. This feature only works for commands that return a single value, and the value is returned in the first parameter. For example: 

XtDisplay DISPLAY $FORM 
XSync $DISPLAY true

can be replaced by the equivalent statement:

XSync $(XtDisplay "-" $FORM) true

The reference to $DISPLAY is replaced with the value returned by the call to XtDisplay.

This capability is available for all category 3 commands except those that create a widget, those that return more than a single value, and those whose first parameter is not a named variable. Commands that do not accept "-" as the environment variable name include the following: