The first two sections, "Getting Started" and "Widget Basics", present basic Motif concepts and are intended for Motif beginners.

The remaining sections, starting with "Resources", constitute a full reference manual for Tcl Motif, with tables of supported resources with their default values, lists of callbacks, and example programs.

This chapter was derived from a document on Tcl Motif written by Jan Newmarch (the author of Tm) and Jean-Dominique Gascuel.

The following example is in the /usr/share/src/sgitcl directory as progEG.tcl. Typically, a Motif program has a top-level object called a mainWindow. This holds a menu bar and a container such as a Form or rowColumn, which in turn holds the rest of the objects. Here is code to create a mainWindow with a list and some buttons in a form:

#! /usr/sgitcl/bin/moat 
xtAppInitialize -class Program
xmMainWindow .main managed
xmForm .main.form managed
xmList .main.form.list managed
xmPushButton .main.form.btn1 managed
xmPushButton .main.form.btn2 managed

The xmForm acts as what is called the "workWindow" of the mainWindow. This resource would be set as follows:

.main setValues -workWindow .main.form

Values would also be set into the list and buttons:

.main.form.list setValues \
        -itemCount 3 -items "one, two, three" \
        -selectionPolicy single_select
.main.form.btn1 setValues -labelString Quit
.main.form.btn2 setValues -labelString "Do nothing"

Callbacks are set up for the Quit button and the selection list:

.main.form.btn1 activateCallback {exit 0}
.main.form.list singleSelectionCallback {puts stdout "Selected %item"}

Geometry would be set for the form, placing all objects in correct relation to each other. This produces a list on the left, with the two buttons above and below on the right:

.main.form.list setValues \
        -topAttachment attach_form \
        -leftAttachment attach_form \
        -bottomAttachment attach_form
.main.form.btn1 setValues \
        -topAttachment attach_form \
        -leftAttachment attach_widget \
        -leftWidget .main.form.list
.main.form.btn2 setValues \
        -topAttachment attach_widget \
        -topWidget .main.form.btn1 \
        -leftAttachment attach_widget \
        -leftWidget .main.form.list

Since we initially created all the widgets as managed, it is not necessary to explicitly manage them before entering the main loop.

Finally, windows are created and the main event loop is entered:

. realizeWidget
. mainLoop

Once entered in the main event loop, the application is really running: widgets are created, displayed, and manipulated as user events that trigger associated callbacks.

Tcl is a text-based language—the only data type is string— so it works well to describe widgets organized in a hierarchical structure. The naming of objects within the widget hierarchy is similar to absolute pathnames of system files, with a dot (.) replacing the slash (/) for pathnames. The application itself is known as "." or dot. An xmForm widget within the application might be known as .form1, while an xmLabel widget within this form might be known as .form1.okLabel, and so on.

Note that Xt requires that "." can have only one child (except for dialog boxes, which are not mapped inside their parents). Tcl Motif follows this naming convention.

Widgets belong to classes, such as Label, xmPushButton or List. For each class there is a creation command that takes the pathname of the object as its first argument:

createWidget widgetName ?managed? ?resourceList?

(This follows Tcl conventions where question mark pairs indicate an option.) Here is a summary of the command and its arguments:

Here are some examples of widget creation commands:

xmForm  .form1 managed 
xmLabel .form1.okLabel managed 
xmPushButton .form1.cancelButton managed -labelString "Get rid of me." 

This creates an xmForm called form1 as a child of "." (dot), then an xmLabel called okLabel and an xmPushButton called cancelButton, both as children of form1. The push button widget has additional arguments to set its label string to say "Get rid of me."

Creating a widget actually creates a Tcl command known by the widget's pathname in the hierarchy. This command should be executed with at least one parameter to change the behavior of the object or the value of its components, or to get information about the object. The first parameter acts as a "method" for the object, specifying an action that it should perform. The general syntax is

targetWidgetName widgetCommand ?options?

Some specific examples appear below:

.root.label manageChild 
.root setValues -title "Hello world"

Motif uses the concept of inheritance for both resources and translations (see the section "Actions and Translations"). Tm extends this to methods, which call Motif functions on the target widget.

In Motif jargon, resources are variables shared between widgets and the application. Their default values permit a common look and feel across applications. They are also used to communicate information between the application and the interface.

Tm resource names follow the usual Motif naming with a leading dash replacing the XmN prefix. For example, -font replaces XmNfont. Tm constants are specified by their Motif name, without the Xm_ prefix, either in upper or lower case.

The section "Resources" describes resource concepts, and default value types. The section "Base Classes" describes resources common to many widgets.

A user interface must react to user input such as clicks or keystrokes. Because a particular input can affect both the interface and the application, reactions may be of two kinds. Actions occur inside Motif to control the interface. Callbacks occur in an application to register user input. Each widget class may define a set of actions and callbacks.

The section "Actions and Translations" deals with actions and translations. The section "Callbacks" discusses callbacks. The section "Base Classes" presents the set of actions and callbacks common to many moat widgets.

In Motif, reactions to user input are defined from a high-level viewpoint: basic actions include choosing a menu item or setting input focus to some widget. On the other hand, basic events include mouse clicks, keystrokes, and key states, modified by the location of the mouse pointer. Motif uses a translation table for binding basic events to basic actions.

The set of classes generally mirrors the Motif set. Some classes (Core, Shell and Primitive) are not accessible from Tm because they are intended for inheritance use only. The section "Basic Widgets" discusses the widgets listed in Table 4-1:

Manager widgets are used to lay out several widgets together. Placing widgets inside widgets enables the creation of hierarchies suitable for complex user interface design. The section "Manager Widgets" discusses the widgets listed in Table 4-2:

Motif provides composite widgets, several object appearing together as one widget. The section "More Widgets" discusses the widgets listed in Table 4-3.

The section "Menus" presents widgets for building menus. Menus may contain button or separators, and of course any menu widget listed in Table 4-4:

Motif also has convenience functions for creating dialog boxes, which appear in their own transient window, with push buttons on the bottom line (Accept/Cancel/Help). The section "Dialogs" discusses the widgets listed in Table 4-5:

When you have to destroy such widgets, you must destroy the real dialog widget; that is, the parent of the usually manipulated widget:

xmQuestionDialog .askMe managed
[.askMe parent] destroyWidget

Motif is built upon Xt. The Xt world must be brought into existence explicitly. This allows setting of class and fallback resources, and leaves hooks for things like setting the icon later in the binding. The Xt startup function is XtAppInitialize.

Several root widget methods exist to deal with Motif features related only to the main application window:

For example, the following code adds an interpreter that reads and executes moat commands that are typed in while the interface is running:

# Define the interpret function, that handles errors.  
proc interpret {line} {     
   set code [catch $line result]   
      if {$code == 1} then {
      puts stderr "$result in :\n\t$line"      
   } else {
      if { $result != "" } { puts stderr $result }
   } 
      puts stderr " " nonewline   
}
# Bind it as an input handler.   
.addInput stdin r  {  
   interpret [gets stdin]   
}
# And display the first prompt   
puts stderr "%" nonewline

The list below describes additional root widget methods for Motif features related to the main application window:

Each widget belongs to a class, whose name is the widget creation command name. Each widget inherits resources from its superclass. For example, xmLabel is a subclass of Primitive, which in turn is a subclass of superclass Core. From Core, xmLabel inherits resources such as -background, -height, and -width. From Primitive, it inherits resources such as -foreground. It is necessary to consult superclasses to get a full resource list for a particular xmLabel. Furthermore, each class adds resources. For example, xmLabel has the additional resources -labelType, -labelPixmap, and -labelString, among others.

Some special resource values are inherited through multiple levels of the widget hierarchy at creation time. For instance, the -buttonFontList of a bulletin board might be inherited from the -defaultFontList of an ancestor subclassing the abstract classes vendorShell or menuShell. In this case, the resource value is copied and is not modified if the original resource is modified.

For instance, in the following example, the button inherits its -fontList default value from bulletin board -buttonFontList. On the other hand, the button's background color is taken from the class defaults, not from the BulletinBoard. Pushing the button will change the BulletinBoard's -buttonFontList resource, which does not update the button's font list.

#! /usr/sgitcl/bin/moat 
xtAppInitialize
xmBulletinBoard .top managed \
   -background #A22 -buttonFontList "-*-courier-*-o-*--20-*"
xmPushButton .top.bold managed \
   -y 10 -labelString Bold
xmPushButton .top.quit managed \
   -y 40 -labelString Quit
.top.bold activateCallback {
   .top setValues -buttonFontList "-*-courier-bold-o-*--20-*"
}
.top.quit activateCallback {exit 0}
. realizeWidget
. mainLoop

The usual X defaults mechanism is used to provide defaults to resources. Default values are located in files designated by the XAPPDEFAULTS environment variable, including an optional locale directory (designated by the LANG environment). XAPPDEFAULTS defaults to /usr/lib/X11/app-defaults, and LANG is usually not defined. In this simplest case, the located file would be /usr/lib/X11/app-defaults/ApplicationName, where ApplicationName is the class name of your application.

These defaults could be reset by the xrdb command; see the xrdb(1) reference page for details. Usually, login scripts read a user-customized resource file, often named .Xdefaults or .Xresources, using the xrdb -merge command. This is the usual way for users to configure their environment.

Finally, some applications employ special configuration files, which might also reset additional resources. The Motif window manager mwm is a good example of this complex area, as it looks in not fewer than eight different resource files; see mwm(1) for more information.

Resource files contain lines specifying values for widget or widget class resources. The syntax is shown below:

resourcePath  :  value

Here, resourcePath is a dot-separated path naming a particular resource in the hierarchy, while value is a string representation for the resource setting.

Resource paths start with an optional application name. Without this, the settings apply to all X applications. After that, names in the path may refer to a widget class (when starting with a capital), to widget names (as defined by moat creation command), or to application-specific scoping. The star character (*) may be used to match any portion of the resource path. Table 4-6 shows some examples of resource paths.

Some resources are just string values (such as -labelString), but others have more complicated types. Since moat is a string language, all values should be manipulated in string representations; moat uses either Motif internal routines or specific converters to make the necessary conversions.

This section briefly describes the main types used by Tm and moat.

$window setValues \
   -units 100th_font_units \
   -width 8000 -height 2400 

-foundry-name-weight-slant-width-style-14-80-100-100-m-60-encoding

#! /usr/sgitcl/bin/moat 
xtAppInitialize
xmPushButton .face managed \
    -labelType pixmap -labelPixmap /usr/share/src/sgitcl/face \
    -armPixmap face_no
.face activateCallback {exit 0}
. realizeWidget
. mainLoop

When Motif executes a callback in reaction to some event, it provides some parameters (such as the current widget) or additional data relevant to a given class. Tm follows Tk in providing the powerful mechanism of callback substitution. Before execution, the Tcl command list is scanned to look for the % character. Each time this character is found, the word that follows is extracted, analyzed, and if recognized, replaced with the corresponding data.

For example, %item in an xmList callback is replaced by the item selected, whereas %item_position is replaced by its position in the list. This is an example of callback substitution in a list:

.list singleSelectionCallback
    { print_info %item %item_position }
proc print_info item position
    { puts stdout "item was $item, at position $position" }

The following list shows the recognized tags. Their meaning is detailed below in the context of the corresponding callbacks.

The following list contains the possible callback reasons, as defined in <Xm/Xm.h> (but with the leading XmCR_ removed):

Table 4-8 lists all callbacks supported by Tm, and the class in which they are first defined. The Motif method names to add callback code are obtained by appending Callback and prepending XmN; these are listed in <Xm/XmStrDefs.h>.

Actions may be added to a widget in a way similar to the C version of Motif. You define an action for the widget in a translation table. In this binding, the Tcl code is placed as the arguments to the action in the translation table. Registering the translation using the action call links a generic action handler, which in turn handles the Tcl code.

This code adds a translation to turn an arrow left or right when the l or r key is typed:

#! /usr/sgitcl/bin/moat 
xtAppInitialize
xmArrowButton .arrow managed
.arrow setValues -translations \
   {<Key>r: action(arrow_direction %w arrow_right)
    <Key>l: action(arrow_direction %w arrow_left)  }
proc arrow_direction {arrow direction}  {
   puts stdout "Changing direction to $direction"
   $arrow setValues -arrowDirection $direction
}
. realizeWidget
. mainLoop

As with callbacks, substitutions are possible. The only one currently supported is %w, to substitute the current widget path. Other substitutions return an error message.

The callActionProc method is available for every widget. Its purpose is to simulate user actions. This method takes an action as a further parameter, using the usual Xt syntax. For example, to simulate the return key press occurring within an arrow button, call the ArmAndActivate() action:

.arrow callActionProc ArmAndActivate()

This sends a ClientMessage event to the widget. Most other widgets would ignore this event, so this call is sufficient. Some actions require event detail, though. For example, when a mouse button release occurs, the widget checks to see if the release occurred inside or outside the widget. If the event occured inside, then callbacks attached to the Activate() action are invoked; otherwise they are not. To handle this, an event of type ButtonPress, ButtonRelease, KeyPress, or KeyRelease can be prepared with some fields set. For example, a ButtonRelease occurring within the arrow can be sent by this call:

.arrow callActionProc Activate() -type ButtonPress -x 0 -y 0

Some of the Text manipulation actions require a KeyPress event, such as self-insert(), which inserts the character pressed. The character is actually encoded as a keycode, which is a hardware-dependent code, too low-level for this binding. To prepare such an event, this toolkit uses keysyms, which are abstractions for each type of key symbol.

The alphanumerics have simple representations as themselves (a, A, 2, and so on). Others have symbolic names (space, Tab, BackSpace). These are derived from the include file <X11/keydefs.h> by removing the XK_ prefix.

This example inserts the three characters "A a" into a text widget:

.text callActionProc self-insert() -type KeyPress -keysym A 
.text callActionProc self-insert() -type KeyPress -key space 
.text callActionProc self-insert() -type KeyPress -key a 

The set of actions requiring this level of X event preparation is not documented explicitly.

The Core class is the ancestor of all Tm widget classes. Any methods and resources it defines apply equally to all Tm objects. The Core class does not implement any behavior (neither action, translation, nor callback), and does not assume display should occur.

The Core class defines the set of methods common to all derived classes, shown below for widget w:

proc flash {widget {fg black} bg red}} { 
   $widget getValues 
      -background old_bg  -foreground old_fg 
   $widget setValues \
      -background $bg -foreground $fg 
   wait 0.1 
   $widget setValues \
      -background $old_bg -foreground $old_fg 
}

.frm.text setValues \
    -background lightGray \
    -foreground #111

name Class type value 

current
home
up
down
left
right
next
next_tab_group
previous_tab_group

The Primitive class derives from the Core class. This abstract class is designed to define resources and behavior common to any widget that could have something drawn on it. As the user sees something, Primitive is able to define some very general behavior, which can appear as translations, actions, and callbacks.

Table 4-10 describes the resources relevant for all widgets that derive from Primitive.

The -navigationType resource controls how the keyboard affects widgets navigation. Keyboard shortcuts are often used to quickly change input fields, as with the <Tab> key.

Simple bicolor drawing is done using the Primitive's foreground color over the Core's background color. Other colors default to mixing these two at widget creation time. When they are entered (gain the input focus), primitive objects are often highlighted by drawing a color border around them. They can also be enclosed by a beveled shadow frame, making them appear to be standing out or recessed (a 3D effect).

The -unitType resource selects screen-dependent, font-related, or device-independent units. It affects subsequent dimension resources for that widget only.

Table 4-11 shows the only two callbacks defined for every drawable widget. These callbacks only support the substitution %w to expand the widget path.

When the Help() action occurs, either through the Help (usually <F1>) key or by a virtual binding, Motif looks for a callback to execute in the current widget. If it finds none, it looks in the parent, the parent's parent, and so on up to the main window. Hence, helpCallback may be used to implement a general or context-sensitive help facility.

The destroyCallback method can be used to call some automatic cleanup procedure when a widget is deleted.

As for any widget, there is an action to match each callback. Actions trigger callback execution and standard widget responses, if any. Primitive class actions are as follows:

This is the only translation defined for the Primitive class:

 <KHelp>: Help() 

This says that the symbolic <Help> key, on most keyboards mapped to the <F1> function key, triggers the Help() action.

Shell classes are used to define resources and behaviors that are common to all widgets having their own window, such as top-level windows, popup menus, and dialogs. Motif describes several different base classes for this purpose, some inherited from Xt, and some defined inside Motif. All the shell classes are introduced below, followed by tables showing the resources available for each.

Shell is the ancestor of all the other abstract shell classes. Having only one managed child, it encapsulates interaction with the window manager. Shell inherits behavior and resources from the Composite and Core classes.

WMShell handles protocols that communicate between an application and the window manager. WMShell inherits behavior and resources from Core, Composite, and Shell.

VendorShell controls resources set up in the X server, and contains meaningful defaults for a particular implementation.VendorShell inherits behavior and resources from the Core, Composite, Shell, and WMShell classes.

TopLevelShell is used for normal top-level windows such as additional window widgets that an application needs. This level is responsible for iconization. TopLevelShell inherits behavior and resources from Core, Composite, Shell, WMShell, and VendorShell.

ApplicationShell is used for an application's main top-level window. There should be more than one of these only if a program implements multiple logical applications. ApplicationShell inherits behavior and resources from Core, Composite, Shell, WMShell, VendorShell, and TopLevelShell.

TransientShell is for temporary windows that do not stay visible on screen and must be iconized along with the TopLevelShell they are affiliated with. TransientShell inherits behavior and resources from Core, Composite, Shell, WMShell, and VendorShell.

-minWidth 100 -baseWidth 50 -widthInc 100 -maxWidth 300

minAspectX    width    maxAspectX
–––––––––– <= ––––– <= ––––––––––
minAspectY    height   maxAspectY

-minAspectX 1 -minAspectY 3 -maxAspectX 1 -maxAspectY 2

A label widget simply contains some text. For example, this is the classic "Hello world" program in Tcl Motif:

#! /usr/sgitcl/bin/moat 
xtAppInitialize
xmLabel .lbl managed -labelString "Hello world!"
. realizeWidget
. mainLoop

Note that text is broken into separate lines only if you put newline symbols in it. Text may contains non-ASCII characters, using the encoding defined in the current font, usually ISO 8859-1.

This example shows more complex use of label widgets:

#! /usr/sgitcl/bin/moat 
xtAppInitialize
xmLabel .lbl managed
.lbl setValues -labelString {
    If your text contains newline symbols,\n
    it will be broken into separate lines.\n
    It may contain non-ASCII characters (àçéñôßü)
}
.lbl setValues \
    -stringDirection string_direction_r_to_l \
    -alignment alignment_end \
    -fontList -*courier-bold-r-*--18-* \
    -marginLeft 10 -marginWidth 10 \
    -x 200 -y 100
. realizeWidget
. mainLoop

Table 4-18 shows the resources for xmLabel.

Some resources are used only in derived classes. When displayed text material changes, the size of the label may or may not be recomputed, depending on -recomputeSize. The label may display the -labelString or -labelPixmap resource, depending on the -labelType value. Labels are always centered top and bottom (inside their margins), but may be centered or left or right justified, depending on -alignment.

When a label is inactive (insensitive), the displayed text is grayed using a 50% pattern. You can change this pattern by specifying a pixmap with -label-Insensitive-Pixmap.

Table 4-19 lists resources inherited from the Primitive and Core classes.

Labels do not define specific callbacks, but just inherit them from the Primitive class, namely helpCallback and destroyCallback.

Text widgets display a text string, but also allow the user to edit it. An xmTextField widget displays a single line of editable text, while an xmText widget usually spans multiple lines.

The xmScrolledText widget automatically displays scroll bars if it is larger than the allotted space on screen. These xmScrollBars enable the user to change the currently viewed portion of the text. Text selection is done with keyboard or mouse interactions, as described in the section "Actions and Translations".

A scrolled text widget is a composite widget that has the following children, where tw represents the text widget name:

tw.HorScrollBar    tw.VertScrollBar    tw.ClipWindow

An associated Tcl procedure can be used to directly access them, as in this example:

xmScrolledText .txt managed
set rsrc_list [.txt.ClipWindow resources] 

In addition to standard Core methods, text widgets (tw) offer these additional methods to deal with text selection and the clipboard:

Table 4-20 lists the resources for xmText, while Table 4-21 lists the resources for xmTextInput and xmTextOutput:

The xmText widget inherits resources from two abstract classes, xmTextInput and xmTextOutput. The xmTextField widget uses the resource subset that corresponds to single-line text (it does not have an -editMode resource). The text source resource might be used to open multiple windows for editing a single text, as in the example below.

#! /usr/sgitcl/bin/moat 
xtAppInitialize
xmPanedWindow .top managed
xmScrolledText .top.a managed -editMode multi_line_edit \
    -rows 3 -columns 49 -value {
When ten low words oft in one dull line creep,
The reader's threatened, not in vain, with sleep.
                      --Alexander Pope}
xmScrolledText .top.b managed -editMode multi_line_edit \
    -rows 3 -columns 49
.top.b setSource .top.a 0 0
. realizeWidget
. mainLoop

The xmTextInput and xmTextOutput abstract classes are only used to group resources dedicated to text editing or displaying. Extensive text should be displayed or edited with the xmScrolledText widget, which automatically provides scroll bars when needed. Text widgets inherit any resources defined in the Core, Primitive, and xmLabel classes.

These text widgets allow the application to do special processing of entered data. After text has been typed or pasted in, initial processing by the text widget determines what the user has entered. This text is then passed to special callback functions, which can make copies of the text, alter it, or choose not to display it. Simple uses for this are text formatting widgets, and password entry widgets that read data but neither display it nor echo "*" for each character typed.

The callback mechanism for this is basically the same as for other callbacks, and similar sorts of substitutions are allowed. For example, the term currInsert is replaced by the current insert position. Other substitutions do not produce a value, but rather give the name of a Tcl variable, allowing the application to alter its value. For example, this callback substitution turns off the echoing of characters:

.text modifyVerifyCallback { set %doit false }

An alternate style is to call a separate procedure to handle the work. The Tcl variable is in the context of the calling routine, so the Tcl upvar function is needed:

.text modifyVerifyCallback {no_echo %doit}
proc no_echo {doit} {
    upvar 1 $doit do_insert
    set do_insert false
}

Actually, the Tcl variable here is the global variable _Tm_Text_Doit. Variables beginning with _Tm_ are reserved for use by the Tm library.

The supported callbacks are listed in Table 4-23:

The following callbacks substitutions are defined for the text-specific callbacks:

proc allcaps {ptr length} {
    upvar 1 $ptr p
    upvar 1 $length l
    if {$l == 0} return
    set upper [string toupper $p]
    set p $upper
}
.text modifyVerifyCallback {allcaps %ptr %length}

In addition, text widgets inherit callbacks from the Primitive class, namely help and destroy callbacks.

Motif provides several different types of buttons, some of which are shown below.

xmPushButton

This moat script creates a standard push button:

#! /usr/sgitcl/bin/moat xtAppInitialize xmMainWindow .main managed xmPushButton .main.button managed -labelString "Push me" . realizeWidget . mainLoop

Figure 4-1. xmPushButton

This is a regular button, displaying a text or pixmap label, surrounded by a beveled shadow. Clicking the button changes shadows to give the impression that the button has been pushed. When the button is released, it reverts to its normal appearance. When focus is gained, for instance by tabbing, the button appears brighter (if it is sensitive). The default push buttons of a dialog can be specified by setting -showAsDefault to true, in which case an additional border is drawn using Motif margin resources:

#! /usr/sgitcl/bin/moat xtAppInitialize xmMainWindow .main managed xmPushButton .main.b managed -labelString "Push me" -showAsDefault true . realizeWidget . mainLoop

Figure 4-2. xmPushButton as Default

Table 4-24 lists the resources for xmPushButton.

Table 4-24. xmPushButton Resources

Resource Name	Default Value	Type or Legal Values
-armColor	computed	Color
-armPixmap3	none	Pixmap
-defaultButtonShadowThickness	0	Dimension
-fillOnArm	True	Boolean
-multiClick		multiclick_discard, multiclick_keep
-showAsDefault	0	Dimension

xmArrowButton

This button contains an arrow, whose direction is given by the -arrowDirection resource.

#! /usr/sgitcl/bin/moat xtAppInitialize xmBulletinBoard .top managed -width 110 -height 110 xmArrowButton .top.up managed -x 40 -y 10 -width 30 -height 30 xmArrowButton .top.left managed -x 10 -y 40 \ -width 30 -height 30 -arrowDirection arrow_left xmArrowButton .top.right managed -x 70 -y 40 \ -width 30 -height 30 -arrowDirection arrow_right xmArrowButton .top.down managed -x 40 -y 70 \ -width 30 -height 30 -arrowDirection arrow_down . realizeWidget . mainLoop

Figure 4-3. xmArrowButton

Table 4-25 lists the resources for xmArrowButton.

Table 4-25. xmArrowButton Resources

Resource Name	Default Value	Type or Legal Values
-arrowDirection	arrow_up	arrow_up arrow_down arrow_left arrow_right

xmToggleButton

This button displays a state in an on/off indicator. Usually, a toggle button consists of a square or diamond indicator with an associated label. The square or diamond is filled or empty to indicate whether the button is selected or unselected.

#! /usr/sgitcl/bin/moat xtAppInitialize xmMainWindow .main managed xmRowColumn .main.col managed -orientation vertical xmToggleButton .main.col.one managed xmToggleButton .main.col.two managed xmToggleButton .main.col.three managed . realizeWidget . mainLoop

Figure 4-4. xmToggleButton

A set of buttons can be grouped into a manager with the -radioBehavior resource set to true, ensuring that only one of them can be selected at a given time. Radio buttons are represented with diamonds instead of squares.

#! /usr/sgitcl/bin/moat xtAppInitialize xmMainWindow .main managed xmRowColumn .main.col managed -orientation vertical -radioBehavior true xmToggleButton .main.col.yes managed -set true xmToggleButton .main.col.no managed xmToggleButton .main.col.maybe managed . realizeWidget . mainLoop

Figure 4-5. xmToggleButton with radioBehavior

See the section "Manager Widgets" for more information about manager options. Table 4-26 lists the resources for xmToggleButton.

Table 4-26. xmToggleButton Resources

Resource Name	Default Value	Type or Legal Values
-fillOnSelect	True	Boolean
-indicatorOn	True	Boolean
-indicatorSize	none	Dimension
-indicatorType	n_of_many	n_of_many one_of_many
-selectColor	computed	Color
-selectInsensitivePixmap	none	Pixmap
-selectPixmap	none	Pixmap
-set	False	Boolean
-spacing	4	Dimension
-visibleWhenOff	computed	Boolean

Text widgets also inherit resources from the Core, Primitive, and Label classes, as shown in Table 4-27.

Table 4-27. Button Widget Inherited Resources

Resource Inherited	From		Resource Inherited	From
-accelerators	(Core)		-alignment	(Label)
-backgroundPixmap	(Core)		-background	(Core)
-borderColor	(Core)		-borderWidth	(Core)
-bottomShadowColor	(Primitive)		-bottomShadowPixmap	(Primitive)
-fontList	(Label)		-foreground	(Primitive)
-height	(Core)		-highlightColor	(Primitive)
-highlightOnEnter	(Primitive)		-highlightPixmap	(Primitive)
-highlightThickness	(Primitive)		-labelPixmap	(Label)
-labelString	(Label)		-labelType	(Label)
-mappedWhenManaged	(Core)		-marginBottom	(Label)
-marginHeight	(Label)		-marginLeft	(Label)
-marginRight	(Label)		-marginRight	(Label)
-marginTop	(Label)		-navigationType	(Primitive)
-recomputeSize	(Label)		-sensitive	(Core)
-shadowThickness	(Primitive)		-stringDirection	(Label)
-topShadowColor	(Primitive)		topShadowPixmap	(Primitive)
-translations	(Core)		-traversalOn	(Primitive)
-unitType	(Primitive)		-width	(Core)
-x	(Core)		-y	(Core)

In addition to the usual helpCallback and destroyCallback, button widgets define additional methods, as listed in Table 4-28.

Table 4-28. Button Widget Callbacks

Method name	Why
armCallback	Button pressed.
disarmCallback	Button released, with the pointer still on it.
activateCallback	Some event triggers the Activate function.

The toggle button also defines the %set callback substitution, which is replaced by the Boolean state of the button.

Simple decorative widgets include xmFrame and xmSeparator. The former is simply a container widget that displays a frame around its child, using in-and-out shadowing or etching. The later is a primitive widget that looks like a flat or beveled line, used to separate items in a display. These two widget classes do not accept user input, so they have no associated actions, callbacks, or translations.

The decoration resources for xmFrame are listed in Table 4-29.

The decoration resources for xmSeparator are listed in Table 4-30.

Decorative widgets inherit resources from the Core and Primitive classes, as shown in Table 4-31.

A list is used to display an ordered set of strings. Mouse or keyboard interactions permit users to select one or more items.

An xmScrolledList should be used when the number of items may be too large to display in the allotted space in the interface: the interface is automatically changed to display an xmScrollBar (see below) to move the visible part of the list. A scrolled list widget w is a composite widget that has the following children:

w.HorScrollBar    w.VertScrollBar    w.ClipWindow

The associated names might be used to access them directly, as in the following example:

xmScrolledList .list managed
.list.VertScrollBar setValues -troughColor red

Different selection modes exist:

In all modes, the defaultActionCallback is called when the user double-clicks an item. The following methods are provided to manage the selection list L:

Table 4-32 lists specific resources for xmList.

Other resources are derived from the Core, Primitive, and Label classes.

Supported list-specific callbacks are listed in Table 4-33.

The following substitutions are defined for the above callbacks:

Be sure to enclose item and selected_items between braces, to avoid parsing errors when item strings contain spaces.

Text widgets also inherit the standard callbacks from the Primitive class, namely helpCallback and destroyCallback.

A scale widget produces an adjustable slider for adjusting some value between a minimum and a maximum. This code creates a horizontal slider:

#! /usr/sgitcl/bin/moat 
xtAppInitialize
xmMainWindow .main managed
xmScale .main.slide managed -orientation horizontal \
    -maximum 11 -value 11 -showValue True \
    -titleString "Volume"
. realizeWidget
. mainLoop

Figure 4-6. xmScale Horizontal Slider

The xmScale widget class defines the new resources, as shown in Table 4-34.

The slider may be moved between the integer -minimum and -maximum. Fractional values are obtained using the -decimalPoints resource, to display a decimal point. The slider size may be set by -scaleHeight and -scaleWidth. The resource -showValue toggles display of text showing the current value, while -scaleMultiple is used for large slider moves with a <Ctrl>-Arrow key.

Table 4-35 lists callbacks defined for the xmScale widget.

In addition, xmScale inherits the usual helpCallback from the Primitive abstract class.

In these callbacks, %value substitution may be used to retrieve the current scale position.

The xmScrollBar widget is made to allow moving the current view of a widget that is too large to be displayed all at once. Usually, scroll bars are part of an xmScrolledWidget, an xmScrolledText, or an xmScrolledList widget.

An xmScrollBar may be horizontal or vertical (depending its -orientation resource). An xmScrollBar is composed of two arrows, a long rectangle called the scroll region, and a smaller rectangle called the slider. The data is scrolled by clicking either arrow, clicking inside the scroll region, or by dragging the slider. When the mouse is held down in the scroll region or in either arrow, the data continues to move at a constant speed.

The following example uses two scrollbars to move a target button:

#! /usr/sgitcl/bin/moat 
xtAppInitialize
xmBulletinBoard .top managed
xmScrollBar .top.h managed \
    -orientation horizontal -width 150 \
    -y 160 -minimum 10 -maximum 140
xmScrollBar .top.v managed \
    -orientation vertical -height 150 \
    -x 160 -minimum 10 -maximum 140
xmPushButton .top.target managed -labelString "X"
proc track_it {} {
    .top.h getValues -value x
    .top.v getValues -value y
    .top.target setValues -x [expr 8+$x] -y [expr 8+$y]
}
.top.h dragCallback track_it
.top.v dragCallback track_it
.top.h valueChangedCallback track_it
.top.v valueChangedCallback track_it
track_it
. realizeWidget
. mainLoop

The xmScrollBar widget class defines the new resources listed in Table 4-36.

The -value resource specifies the current position of the scrollbar slider, between the minimum and maximum -sliderSize. The slider moves between -minimum and -maximum by -increment steps (clipped at the ends). Clicking either scrollbar arrow moves the slider by -pageIncrement. The -sliderSize reflects the portion of the widget currently in view.

The -troughColor specifies the scrollbar slider fill color. Constant speed movement can be parameterized with -repeatDelay and -initialDelay. If -showArrows is set to False, the scroll bar will not have arrows at either end.

In the callbacks above, the %value substitution returns the current scroll bar position.

This class is not a subclass of Primitive, but since it has a graphical representation, it shares some of the Primitive class resources and behavior. The Manager abstract class defines the common resource set described in Table 4-38 for xmManager.

The Manager abstract class also defines callbacks for all manager subclasses. These callbacks are described in Table 4-39.

There is no special substitution associated with these callbacks.

The xmBulletinBoard widget is the simplest manager. Its children are positioned using their -x and -y resources. No special management occurs when this widget is resized. Table 4-40 lists the resources associated with xmBulletinBoard.

When -allowOverlap is set to False, any placement of children that would result in an overlap is rejected. Setting -noResize to True disables any resize of the widget, while -resizePolicy may be used to control what kind of resize should be allowed.

The xmBulletinBoard manager places its children in one or more columns (or rows). Different packing styles, directions, and size options permit you to create aligned or unaligned rows (or columns), as in the following examples.

This example uses horizontal orientation, pack_tight packing, and specifies the width and resize characteristics of the widget:

#! /usr/sgitcl/bin/moat 
xtAppInitialize
xmRowColumn .top managed -orientation horizontal \
    -packing pack_tight -width 120 -resizeWidth false
xmPushButton .top.a managed -labelString A
xmPushButton .top.b managed -labelString BBB
xmPushButton .top.c managed -labelString CCCC
xmPushButton .top.d managed -labelString DD
. realizeWidget
. mainLoop

Figure 4-7. xmPushButton and pack_tight

This example uses horizontal orientation, pack_column packing, and explicitly requests two columns:

#! /usr/sgitcl/bin/moat 
xtAppInitialize
xmRowColumn .top managed -orientation horizontal \
    -packing pack_column -numColumns 2
xmPushButton .top.a managed -labelString A
xmPushButton .top.b managed -labelString BBB
xmPushButton .top.c managed -labelString CCCC
xmPushButton .top.d managed -labelString DD
. realizeWidget
. mainLoop

Figure 4-8. xmPushButton and pack_column

This example requests a vertical orientation:

#! /usr/sgitcl/bin/moat 
xtAppInitialize
xmRowColumn .top managed -orientation vertical
xmPushButton .top.a managed -labelString A
xmPushButton .top.b managed -labelString BBB
xmPushButton .top.c managed -labelString CCCC
xmPushButton .top.d managed -labelString DD
. realizeWidget
. mainLoop

Figure 4-9. xmPushButton with Vertical Orientation

Table 4-41 lists the resources associated with xmRowColumn.

A form is a manager widget created to lay out widgets using neighborhood relationships, such as "this widget should be positioned to the left of this one." This is quite general, and allows you to define widget combinations that can resize gracefully. Figure 4-10 shows a combination of xmLabel and xmForm widgets that adjust to fit the data.

Figure 4-10. xmLabel with xmForm

These constraints are defined in terms of attachment of each side of child widgets to the form border, to another widget, to a relative position in the form, or to the initial position of the child. When resizing occurs, children are adjusted according to these constraints.

Table 4-42 lists the resources associated with xmForm.

A paned window is a composite widget used to lay out several children, each in its own pane. Pane separators always contain a sash (see Figure 4-11) to allow users to change the space alloted for each widget.

#! /usr/sgitcl/bin/moat
xtAppInitialize
xmPanedWindow .top managed
xmScrolledText .top.txt managed \
        -rows 3 -editMode multi_line_edit  -value \
"This paned window has three parts:
xmScrolledText, xmScrolledList, and
xmToggleButtons inside xmRowColumn.\n\n\window{paned_window}\n"
xmScrolledList .top.list managed \
        -width 568 \
        -items {Windows, Widgets, Gadgets, Buttons} \
        -itemCount 4
xmFrame .top.f managed
xmRowColumn .top.f.rc managed \
        -orientation horizontal \
        -radioBehavior true
xmToggleButton .top.f.rc.1 managed
xmToggleButton .top.f.rc.2 managed
xmToggleButton .top.f.rc.3 managed
. realizeWidget
. mainLoop

Figure 4-11. xmPanedWindow With Sashes

Table 4-43 lists the resources associated with xmPanedWindow.

The -refigureMode resource indicates whether or not child widgets should be reset to their appropriate positions when the paned window is resized.

Table 4-44 lists the resources for xmPanedWindow that specify pane constraint behavior.

The -skipAdjust constraint resource controls whether or not the paned window should automatically resize this pane.

A command widget is composed of a history area (an xmScrolledList), a label to display the prompt, and a text field to edit the current command. The command widget is a subclass of xmSelectionBox. You may add an extra child, called the work area.

The command widget recognizes several new methods:

Table 4-45 lists the resources associated with xmCommand.

Other resources are inherited xmSelectionBox and its ancestors.

Table 4-46 lists the callbacks associated with xmCommand.

Both of these callbacks support the %value and %length substitution, which are replaced by the string (or string length) that fired the callback.

Tm has limited support for the Xlib drawable area or buttons—you can draw only strings on them. This is the only currently defined drawing method for manipulating the xmDrawingArea and xmDrawnButton widgets:

The following example produces a familiar "Hello world" widget. It is necessary to use an exposeCallback to get the message redisplayed when needed.

#! /usr/sgitcl/bin/moat 
xtAppInitialize
xmDrawingArea .top managed -height 30 -width 150
.top exposeCallback {
    set gc [.top getGC -foreground black]
    .top drawImageString $gc 10 20 "Hello world"
}
. realizeWidget
. mainLoop

Figure 4-12. xmDrawingArea

Table 4-47 lists the resources associated with xmDrawingArea.

Table 4-48 lists the resources associated with xmDrawnButton.

Table 4-49 lists the callbacks associated with xmDrawingArea and xmDrawnButton.

This composite widget is used for the application's main window. As you add children to it (xmMenuBar, xmList, xmMessageBox, a work area, and so forth) it manages them, as you could do manually with xmForm.

The management of the work area is not immediate: the main window must know which of its children is the work area before you can manage that widget. The following example produces a prototype interface for a standard application:

#! /usr/sgitcl/bin/moat 
xtAppInitialize
xmMainWindow .top -showSeparator True \
        -commandWindowLocation command_below_workspace
xmMenuBar .top.bar managed
xmCascadeButton .top.bar.File managed 
xmCascadeButton .top.bar.Help managed
xmDrawingArea .top.work \
        -width 320 -height 240 \
        -background black
.top setValues -workWindow .top.work
.top.work manageChild
xmCommand .top.com managed \
        -historyVisibleItemCount 0 \
        -textFontList  -*-courier-medium-r-*--12-*-*-*-*-*-*
.top.com commandEnteredCallback {%value}
.top setValues -width 600 -height 500
.top manageChild
. realizeWidget
. mainLoop

The xmMainWindow widget defines these resources, renaming resources of the parents, as shown in Table 4-50.

Table 4-51 lists the callbacks associated with xmMainWindow.

Message boxes are used to display simple messages. The xmMessageBox widget can also display a pixmap symbol to indicate warnings or error conditions. This is done by setting the -dialogType resource, or by specifying a pixmap with -symbolPixmap.

This example shows the use of an xmMessageBox with custom pixmap face, which is taken from an external file:

#! /usr/sgitcl/bin/moat 
xtAppInitialize
xmMessageBox .top managed \
    -messageString {Hello world!} \
    -symbolPixmap /usr/share/src/sgitcl/face
. realizeWidget
. mainLoop

Figure 4-13. xmMessageBox With Pixmap

A message box is a composite widget whose component children might be managed or unmanaged. Child widgets can be included or eliminated using the Tcl Motif commands manageChild and unmanageChild applied on the automatically-derived child widgets. With a message box named mw, these are the standard child widgets:

    mw.Cancel    mw.Help        mw.Message
    mw.OK        mw.Separator   mw.Symbol

This example is like the xmMessageBox above, but without the Cancel and Help buttons and the separator line:

#! /usr/sgitcl/bin/moat 
xtAppInitialize
xmMessageBox .mb managed -messageString {Hello world!} \
    -symbolPixmap /usr/share/src/sgitcl/face
foreach child {Cancel Help Separator} {
   .mb.$child unmanageChild
}
. realizeWidget
. mainLoop

Table 4-52 lists the resources associated with xmMessageBox.

Table 4-53 lists the callbacks associated with xmMessageBox.

Furthermore, xmMessageBox also inherits destroyCallback from the Core class.

A selection box is a composite widget designed to ease creation of interfaces that present the user with a list of items from which to choose. A selection box has a number of component children, which the application can manage or unmanage. This is often done to add or remove elements from a dialog. Managing and unmanaging are the only two operations you should perform on elements of a composite selection box widget.

With a selection box named sb, these are the automatically-derived child widgets:

    sb.Apply          sb.OK        sb.Cancel
    sb.Selection      sb.Help      sb.Separator
    sb.ItemsList      sb.Text      sb.Items

Table 4-54 lists the callbacks associated with xmSelectionBox.

These callbacks support the %value and %length substitution, which are replaced by the string (or string length) that fired the callback. The selection box widget also inherits all the callbacks defined in xmList and xmText.

A file selection box is designed to let the user interactively specify a pathname and a file. A filter may be used to display only certain files, based on a regular expression matching those filenames. This surprisingly simple code creates a file selection box:

#! /usr/sgitcl/bin/moat 
xtAppInitialize
xmFileSelectionBox .top managed
. realizeWidget
. mainLoop

With a file selection box named sb, these are the automatically-derived child widgets:

    sb.Apply       sb.FilterLabel     sb.Items         sb.Text
    sb.Cancel      sb.FilterText      sb.ItemsList
    sb.DirList     sb.Help            sb.Selection
    sb.Dir         sb.OK              sb.Separator

The callback substitutions supported for xmFileSelectionBox are

    %value    %value_length    %mask       %mask_length
    %dir      %dir_length      %pattern    %pattern_length

A menu bar is a permanently-displayed horizontal pulldown menu that can contain menu buttons and cascade buttons. It is used to display the buttons that trigger the pulldown menus of an application, usually at the top of the xmMainWindow.

See the section "xmPushButton" for information about this widget.

A pulldown menu is a special kind of vertical xmRowColumn. It is managed only when it should be displayed. Pulldown or cascading menus are managed when the user clicks on the top-level menu button. Popup menus are managed by a more general event, typically through a defined translation of the main window.

Menu items are implemented as child widgets, and include xmLabel, xmPushButton, xmSeparator, and xmCascadeButton. The order of definition controls menu item order. Table 4-55 lists the callbacks associated with xmPulldownMenu.

The cascade button is a special subclass of the push button that forces management of a pulldown menu. Table 4-56 lists the resource associated with xmCascadeButton.

Here are some examples of unusual types of menus:

The simplest dialogs are message boxes. Tm defines five message dialogs with an icon, one without an icon, plus a simple prompt dialog. Table 4-57 lists the simple dialogs:

This example creates a menu that allows you to bring up each of the simple message dialogs listed above:

#! /usr/sgitcl/bin/moat 
xtAppInitialize
xmMainWindow .top managed
xmMenuBar .top.bar managed
xmCascadeButton .top.bar.File managed
xmCascadeButton .top.bar.Dialog managed
xmPulldownMenu  .FileMenu
xmPulldownMenu  .DialogMenu
xmLabel .top.msg managed -labelString {\n
    To see different types of dialog boxes, \n
    choose items from the Dialog menu. \n
}
.top.bar.File setValues -subMenuId .FileMenu
xmPushButton .FileMenu.Quit managed
.FileMenu.Quit activateCallback {exit 0}
.top.bar.Dialog setValues -subMenuId .DialogMenu
foreach b {Error Information Question Warning Working Message Prompt} {
    xmPushButton .DialogMenu.$b managed
    xm${b}Dialog .$b
    .$b.Cancel unmanageChild
    .$b.Help   unmanageChild
    .$b.OK     activateCallback {.$b unmanageChild}
}
.DialogMenu.Error       activateCallback {popup Error}
.DialogMenu.Information activateCallback {popup Information}
.DialogMenu.Question    activateCallback {popup Question}
.DialogMenu.Warning     activateCallback {popup Warning}
.DialogMenu.Working     activateCallback {popup Working}
.DialogMenu.Message     activateCallback {popup Message}
.DialogMenu.Prompt      activateCallback {popup Prompt}

# callback procedure
proc popup {type} {
    .$type setValues -messageString "This is an xm${type}Dialog"
    .$type manageChild
}

. realizeWidget
. mainLoop

The more general dialogs use two multipurpose managers inside. Tcl Motif defines the xmFormDialog and xmBulletinBoardDialog widgets to create them.

Use the xmSelectionDialog widget to select an item from an arbitrary list. See the section "xmSelectionBox" for more information.

Use the xmFileSelectionDialog widget to select a directory and a filename. See the section "xmFileSelectionBox" for more information.