
Disclaimer

This user manual is shockingly short.
The whole system should currently only be attempted by someone who is brave,
knows either Motif or Tk, or preferably knows both.

Introduction

This is a binding of the tcl language to the Motif widgets.
It gives the full set of Motif widgets, but accessible through the simple
interpreted tcl language.

Running tcl/Motif programs

tcl/Motif programs may be run by the `moat' (MOtif And Tcl) interpreter.
When called with no arguments it reads tcl commands from standard input.
When called by

moat -file file-name

it reads tcl commands from `file-name', executes them and then enters the
Tm event loop.  This is similar to the Tk `wish', but does not support
abbreviations of the option `-file'.

Depending on your shell interpreter, you will probably be able to run 
tcl/Motif programs as standalone programs. If your moat interpreter is
installed in say `/usr/local/bin/moat', make this the first line of your
executable program:

#!/usr/local/bin/moat -file

Widget naming

Widgets are visual objects that exist on the screen.
They are organised as a hierarchy, with the application itself forming the
root of this hierarchy.
The naming of objects within this hierarchy is similar to the ``absolute
path names'' of Unix files with a `.' replacing the `/' of Unix.
The application itself is known as `.'.
A Form in the application may be known as `.form1'.
A Label in this form may be `.form1.okLabel', and so on.
Note that Xt requires that `.' can only have one child
(except for dialogs).
This naming convention is the same as in Tk.

Widget creation

Widgets belong to classes, such as Label, PushButton or List.
For each class there is a creation command which takes the pathName of the
object as first argument with optional further arguments:

form .form1

label .form1.okLabel

label .form1.cancelLabel -labelString "Get rid of me"

creates a Form `form1' as child of `.', and two Labels `okLabel' and
`cancelLabel' as children of `form1'. The `cancelLabel' has additional
arguments that set the labelString to "Get rid of me".

The set of classes generally mirrors the Motif set.
Some widgets in Motif and Xt are not accessible from this binding because
they are intended for use in inheritance only, such as Core and Primitive.

Motif has two special commands for creating a ScrolledList and a ScrolledText.
These commands actually create a pair of widgets: a List or Text inside a
 ScrolledWindow. To use these commands within Tm, the path of both the
ScrolledWindow and the Text or List must be given.  For example,

form .form1

scrolledList .form1.sw.list2

Motif also has convenience functions that create dialogs.
These don't create ordinary widgets, but Motif pretends that they do.
Tm follows this, and allows you to use commands such as

questionDialog .askMe

to create such dialogs.

The set of creation commands can be found from the Motif Programmer's
Reference. 
Although this refers to the C binding, a simple convention allows the
Tm command to be worked out. For each C command XmCreate..., simply
drop the XmCreate and make the first letter lower case. So the C
XmCreateSelectionBox gives the Tm command

selectionBox

(There are some provisos: gadgets are not supported by Tm, nor are the
``simple'' menu functions. The drag and drop mechanism has not been
implemented yet.)

Widget commands

Creating a widget actually creates a tcl command known by its pathName.
This command may be executed with at least one parameter 
to either change the behavior of the object
or the value of its components, or to get information about the object.
The parameter acts like a ``method'' to the object, and specifies an action
that it should perform. The parameters that are recognised by every object
include:

manageChild

unmanageChild

getValues

setValues

any string ending in ``Callback''

For example,

.form1.okLabel unmanageChild

.form1.okLabel activateCallback {puts stdout "I was pushed into it..."}

Unmanaging a widget removes it from the display, and rom the geometry
management of its parent. Managing it reverses this. The other methods
are explained later.

Widget resources

Each widget has a set of resources that can be set at creation time,
set at a later time, or queried for their value.  All resource names are
prefixed by a minus `-'. On setting a value, all resources take the next
word as value, and on getting a value the next word is the name of a variable
to  store the value in.

On creation, the resource/value pairs come after the widget pathName, as in

.okLabel -labelType pixmap -labelPixmap xlogo32

which set the labelType to pixmap and the labelPixmap to xlogo32.

Resources can be set at any time using the setValues method

.text setValues -editMode editable -value "Initial text"

Resources can be obtained from the widget using the getValues method.
For example

.fileSelectionBox getValues -dirSpec file_selected -directory dir

stores in the tcl variable file_selected the filename that was entered, and
in the tcl variable dir the directory in which the file selection occurred.

Each widget inherits resources from superclasses. For example, Label is a
subclass of Primitive which in turn is a subclass of Core.  From Core it
inherits resources such as background, height and width.  From Primitive it
inherits resources such as foreground.  It is neccessary to look at these
superclasses.  In addition, each class adds extra resources.  For example,
Label has the additional resources labelType, labelPixmap and labelString,
among others.

Resource names can be obtained from the Motif documentation for each
widget.  In the table of resources, the names are given prefixed by
``XmN'', such as XmNeditMode.  Drop the prefix to get the tcl resource
name. Case is important here.

Resource values can also be obtained from the Motif documentation.  For
each resource look at its type.  Types such as Dimension and Position are
numeric types, and along with int types need an integer value.  In the tcl
program they are implemented as tcl Strings, as is everything.  In fact,
all resource values are tcl strings.  Pixmaps, for example, are the string
name of a pixmap such as ``xlogo32''.  Pixel is a color such as ``blue'',
or a hexadecimal representation of the color.  Types such as the
arrowDirection of an ArrowButton form a discrete set with values listed as
XmARROW_UP, XmARROW_DOWN, etc.  For these types, drop the ``Xm'' and use
the rest of the string as the value.  On setting values, case is not
important but on getting values the string will be lower case for these
discrete types.

Callbacks

When the user does things to a widget, it may cause the widget to take certain
actions.  For example, when a button is pressed it changes appearance to
look pressed in. Some of these actions can have tcl code attached to them,
so that the tcl code is evaluated when the action is performed. The tcl
code is attached to a ``callback'' by a widget command.  For example, a
pushButton has an activateCallback that is called when the user presses and
releases the left mouse button inside the widget; it has an armCallback
that is called when the user presses the mouse button; it has a
disarmCallback that is called when the user releases the mouse button
inside the widget.

Tcl code is attached to a callback by giving it as the second argument to the
appropriate widget methodod. For example,

.button armCallback {puts stdout "Stop squashing me!!!"}

.button disarmCallback {puts stdout "That's better!"}

The names of the callbacks available for a particular widget are derived
from the resource documentation for the Motif widget.  Each callback ends
with the string "Callback" in its name.  Drop the "XmN" from the Motif
description to gain the widget command.  Callbacks are treated differently
to other resources because the Xt toolkit treats them differently - the
resource is not meant to be handled directly by any ordinary application.

Callback substitutions

Motif supplies information to each callback function that is specific to
the widget type.  Generally this is not of much interest. However, for some
widgets such as List this is used to supply important information, such as
what item in the List was selected! To make this available to the tcl
callback function a pattern substitution mechanism may be used.  Any ``%''
followed by a word will be treated as a pattern for potential substitution.
For example, ``%item'' in a List will be replaced by the item selected,and
``%item_position'' will be replaced by its position in the list.
An example list callback is

.list singleSelectionCallback {print_info %item %item_position}

proc print_info {item position} {

    puts stdout "item was $item, at position $position

}

The substitutions allowed may be found from the Motif documentation.  In
the description of callback information one or more structures will be
defined. The field names in these structures are the names used in ``%''
substitutions.

Examples

A number of examples are in the programs directory. Those with `DH' in
them duplicate the examples in Dan Heller's ``Motif Programming Manual'',
O'Reilly & Associates Inc.
