# TclMotif Info

## Welcome to...

A tcl binding to Motif

## Who by

Jan Newmarch (jan@pandonia.canberra.edu.au).

## Availability

The primary site for this is csc.canberra.edu.au:/pub/motif/tclMotif/tclMotif.*.tar.z. (Here)

It is also placed on X and tcl sites ftp.x.org and ftp.aud.alcatel.com ( was archived on harbor.ecn.purdue.edu ) From these sites it will be available on mirrors in lots of places. A binary version for Linux is also available from Linux sites such as sunsite and tsx-11.

## What

This package consists of a set of functions and a standalone interpreter moat that allow tcl programs to use the Motif set of widgets. A tcl file can be read by the standalone interpreter much as the Tk wish does. The difference is that instead of using the Tk library to create and manipulate Tk widgets, this system uses the Tm library to create and manipulate Motif widgets.

## Major changes in version 1.4

- lots of minor bug fixes.
- added methods: getSelectionValue, mrmFetchWidgetOverride, addWMProtocolCallback, pending, windowID, displayInfo, augmentTranslation, overrideTranslations, uninstallTranslations, lowerWindow, raiseWindow, warpPointer, beep, setCommand (many of these from Wolfgang Kechel - wolfgang@pr-wiesbaden.de).
- Modified addwidget syntax to make it easier to define related widgets in a single file.
- INCOMPATABLE CHANGE: if a resource can't be found in a resource list or in a constraint parent list, then we used to complain. Xt says to ignore this, and Motif relies on this behaviour (e.g allowShellResize in CreateFormDialog gets handed to both shell and form). So we don't complain any more, and ignore unrecognised resources silently.
- INCOMPATABLE CHANGE: the string to XmString formatting converter is now used for lists of strings, instead of XmStringCreateLToR.
- Added support for multiple displays so that a topLevelShell may be created on a new (or already open) display (Wolfgang Kechel - wolfgang@pr-wiesbaden.de)
- Lots of code cleanups (Wolfgang Kechel - wolfgang@pr-wiesbaden.de).

## Major changes in version 1.3

- Added Motif 2.0 support for widgets Container, ComboBox, IconGadget, Notebook, SpinBox, CSText and for Render Tables for XmStrings. [This worked on a beta version of Motif 2.0 - it will need updating for the production version, I am sure!]
- Made it easier to add in additional widgets from other sources. This can be done by modifying C code or using a widget description file suggested by Harald Albrecht. (Lots of people have asked for this.)
- Support for uil added. (Lots of people have asked for this.) [This is only a subset of the Mrm functions - feedback would be useful.]
- Hook to allow extra drop type handlers to be added. (Chris Steres, steres@tcltown.wpd.sgi.com).
- Added pattern matching mechanism so that widget names need not use the full path name, but can use a "*" match for the prefix (or any part, really). (Suggested by David Bainbridge, david@ics.com.)
- Added %call_data field to each callback to give a keyed list of values. (Suggested by David Bainbridge, david@ics.com).
- Added support for tear-off menus, and the tearoff child.
- Added regression test for widget creation.
- Added method class.
- Added method removeCallback.
- Widgets created by Motif as children of SelectionBox, FileSelectionBox, MessageBox and ScrolledWindow have a method handler appropriate to their type.

## Major changes in version 1.2

- many memory leaks removed.
- syntax of table of strings changed from Motif comma separated form to tcl form (INCOMPATABLE change).
- string to XmString treats the string as a list of words instead of a string of words (INCOMPATABLE change).
- string to XmString now allows formatting of the string to include direction and font.
- can specify the font of a GC and draw lines and arcs in DrawingArea.
- TextField shares methods with Text instead of Core.
- Added user manual written by Jean-Dominique Gascuel.

## Major changes in version 1.1

- Popup and Option menus added.
- XmDialogShell added.
- TopLevel widget added, and Root uses its methods (popup, popdown).
- Icons can now be set for toplevel widgets.
- Various bug fixes.
- More examples: xmeditor and wtour.
- Imakefile improved for shared libraries, contributed by Joseph E. Sacco (jsacco@ssl.com).

## Relation to Wafe

The Wafe project also provides a binding of Xt widgets to tcl. Originally just the Athena widgets, it has been extended to other sets, and has a Motif binding in beta.

- Wafe uses Motif 1.1, tclMotif uses Motif 1.2. This gives me better coverage of some parts of Motif, because Motif 1.2 supplies extra hooks.
- The language syntax differs. tclMotif is closer to Tk than Wafe is.
  Wafe (and WKSH) use
    command object ...
  syntax. Both Tk and tclMotif use
    object command ...
- I use the standard Motif callbacks, Wafe has its own callback model.
- Wafe has more Xt support.
- The primary aim of wafe is as a tcl/Xt front-end to other languages. My binding is just tcl to Motif, so I have been able to tune this to the Motif model easier.

I am in correspondence with the authors of Wafe, and we share code and developments.

## Status

This is being actively maintained, as of March 1995. New versions are released approx every 2-3 months, although this depends on many factors. Please report any bugs either in existing code, or omissions that reduce the way you would like to use tclMotif.

The changes over the releases are summarised below (CHANGES)

## Requirements

TclMotif-1.1 has been built using tcl7.3 and the Motif 1.2.1 development libraries. You need both. It has been tested on

- SunOS 4.1
- SunOS 4.1.3
- 486 running Linux (0.99 pl26, 1.0pl9)

Earlier versions used tcl6.7, but this is no longer supported. It should compile using tcl7.0b3 onwards, and all versions of Motif 1.2. There is some Motif 1.1 support i.e. it will compile and most things will run, but some things such as getting resource values of scalars such as XmNarrowDirection won't.

The Motif 2.0 support is based on a beta version of Motif 2.0 that I had access to at one time. This will probably change when I get access to the production release.

## Files

- The directory src contains the source files.
- doc contains the man pages, a skimpy user manual, and a draft paper.
- The examples directory contains a number of good programs that show how Tm works.
- The wtour directory contains a widget-tour program based on Andrew Payne's wtour program for Tk.
- The tests directory contains the regression test files for Tm. These cover many features of Tm, but are not designed for easy reading. The file index in this directory shows what is tested.
- The programs directory contains adhoc programs used in developing Tm. These are in no particular order, not documented. You may see some useful examples in here, but it is pot-luck.
- At the top level, INSTALL tells you how to build Tm and moat, MOTIFBUGS explains why things aren't my fault and COPYRIGHT tells who owns it and why. CHANGES documents what has happened between versions.

## Changes History

### alpha release 0.1 June 1993

1. INCOMPATABLE CHANGE: Widgets must be explicitly managed
2. Third arg of a widget creation command can be "managed"
3. The ScrolledX and ..Dialog calls have the parent hidden as in Motif. A method ``parent'' is available to get at them.
4. A problem with setting some resources at create time (width, etc) has been fixed.
5. The verify callbacks for Text now work.
6. The size of a StringTable is deduced from the resource name.

   ### alpha release 0.2 July 1993

7. INCOMPATABLE CHANGE: all widget creation commands have changed, adding xm at the front. This avoids a name clash with tcl's list.
8. Motif 1.2 drag and drop is supported in a simple way.
9. Translations are now supported
10. Access is available to SelectionBox children using their Motif names.
11. Can now draw strings in XmDraw* widgets using XDrawImageString.
12. Can map/unmap widgets.
13. INCOMPATABLE CHANGE: ported to tcl7.0, and support for tcl6.7 removed.
14. Program added "actions" are now available.
15. Can create GCs using XtGetGC.
16. Pixel to String converter added.
17. Class name is deduced from tcl source file.

    ### alpha release 0.3 September 17, 1993

18. Tcl_AppInit added.
19. Compiles under Sun cc as well as gcc.
20. Imakefile makes libtclM.a

    ### alpha release 0.4 September 21, 1993

21. Fixed bug using return value of Tcl_SetVar.

    ### alpha release 0.5 September 23, 1993

22. Fixed bug in ClientData for widget creation.

    ### alpha release 0.6 October 12, 1993

23. Fixed zero size of _comm widget.

    ### alpha release 0.7 October 19, 1993

24. Fixed bug in ClientData in Tm_DestroyWidgetHandler.
25. Can now access children of MessageBox using their name.
26. Can now access children of SelectionBox outside of dialogs.
27. New method for all widgets: callActionProc. This allows actions to be called from code, so that interactive input can be "faked".
28. New commands xtAppInitialize, new methods realizeWidget and mainLoop.
29. Class can be set in the program using an option to xtAppInitialize.
30. Fallback resources can be set using an option to xtAppInitialize.
31. INCOMPATABLE CHANGE: All of tmMain.c moved into tmAppInit.c so that tm now becomes just an extension to tcl, with common extension methods. This *requires* use of xtAppInitialize, realizeWidget and mainLoop.
32. New method addInput so that alternative input sources can be monitored. They can be removed by removeInput.
33. Regression test method added from tcl and "tests" dir created.
34. Fixed bug in getting resources of ".".
35. Fixed failure to copy path in RowColumn widget info creation.
36. #ifdef protected Motif 1.2 code so that it will sort of run under Motif 1.1 (but things like getting scalars e.g. arrowDirection won't work). This fix due to Jean-Dominique Gascuel (Jean-Dominique.Gascuel@imag.fir).
37. Protected function defs by #ifdef __cplusplus to allow compilation under C++. Thanks to Jean-Dominique Gascuel for this.
38. Erroneous definition of appContext in tmFuncs.h removed (Jean-Dominique Gascuel).
39. Added type info to getGC value so that a naive type check can be performed when its value is used (prefixed GC value with gc).
40. New widget command type added internally with a command handler Tm_RootCmd.
    This is for application context things such as XtAppAddInputHandler, which are handled from "." alone.
41. Improved error handling for malformed or non-convertible resource options.
42. New method resources added for all widgets. This returns a list of lists {option-string option class type value} giving info about all resources.
43. Now use more general (and more correct) tclXtSend package for send.
44. Used some debugging malloc packages to eliminate memory overruns. Highly recommended: Connor Cahil's dbmalloc package posted to comp.sources.unix (use archie to find it), which caught some overruns on the Sun; Mark Moraes malloc package caught some more under Linux. This is available only from the Uni Toronto site.
45. Changed userman.txt to tclMotif.man as section one man page entry.
46. Added man page for TmRoot
47. Addded man page for moat.
48. Added timer handlers.
49. Added man pages for SelectionBox and MessageBox.

    ### alpha release 0.8 November 24, 1993

50. Added children to FileSelectionBox and FileSelectionDialog.
51. Man page for FileSelectionBox added.
52. DrawImageString method for DrawnButton documented.
53. ScrolledWindow children added in, and ScrolledWindow manpage created.
54. Changed fileno to filenum to avoid clash with macro of that name
55. Fixed bug in registering action as an action.
56. Added "rocessEvent to root widget, to allow event processing loop at a point in program. This is needed for modal-style programming.
57. Separated tmAppInit.c into files tmAppInit.c and tmBasic.c so that tmAppInit.c can be replaced in toto in using other tcl extensions. Any replacement should include tmFuncs.h and call Tm_Init(interp).
58. Added reason field to callback substitutions for all widgets.
59. Many callback substitutions added and all documented.
60. More list methods added. Half-way there :-(
61. Added methods appendValue, setValue, error for Command widget.
62. Fixed bug in converter for XmStringTable->String that left a pointer into the stack instead of to static space.
63. Added methods to Text. Almost there on this one too!
64. Extended regression tests to cover hidden children, extra children and new methods in List and Text.

    ### beta release 1.0 December 22, 1993

65. XmDialogShell added.
66. tcl variables with version info added.
67. PopupMenu added.
68. OptionMenu added.
69. TopLevel widget added, and Root uses its methods (popup, popdown).
70. Icons can now be set for toplevel widgets.
71. bug of double delete of widget on destroyWidget fixed.
72. time stamp now uses XtLastTimestampProcessed instead of time().
73. Added WidgetList to String converter for children resource.
74. Interpreter name for send mirrors title resource (plus maybe #n).
75. wtour example program added (based on Andrew Payne's wtour for Tk).

    ### beta release 1.1 February 8, 1994

76. Method getAppResources moved from Root widget to Core widget so that it is available for any widget.
77. Method defineCursor added.
78. TextField shares methods of Text, instead of Core (Ulrich Ring).
79. Tests for equality with class changed to XtIsSubclass() (Ulrich Ring).
80. Replaced call to _XtCopyToArgs() with suitable code.
81. Can specify font in a gc (Ross Wakelin )
82. New methods for DrawingArea: drawLine and drawArc (Ross Wakelin )
83. Macros in tm.h renamed to avoid common name clashes (ok@daveg.PFM-Mainz.de, Olaf Kirch))
84. Fixed bug in error messages when a method fails which said "method not found" instead of "method failed".
85. More checks in Text modify verify callbacks (Ulrich Ring).
86. Lots of memory leaks eliminated - thanks to Purify!!!
87. Fixed bugs in registering send command (Chris Steres).
88. Tcl command specified as the argument to a callback need not be a single word. A set of words are "merged" to form the command if there is more than one word (request from Jeff Lankford).
89. INCOMPATABLE CHANGE: list format is changed from Motif to tcl format.
90. INCOMPATABLE CHANGE: string to XmString converter changed.
91. Fixed bug in getting full resource list of a widget.
92. Motif bug of some widget resources labelled as type string causes problem when we really do need to convert a window. Patched windowGroup case. There may be others...
93. Added user manual written by Jean-Dominique Gascuel.
94. Fixed nroff problems in tclMotif.man.

    ### beta release 1.2 June 2, 1994

95. Added Motif 2.0 support for widgets Container, ComboBox, IconGadget, Notebook, SpinBox, CSText and for Render Tables for XmStrings.
96. Improved error reporting for failed resource conversions.
97. Fixed old-style use of List items in wtour.
98. Removed all references to XmStringGetLtoR.
99. Added % substitutions to XmTextField.
100. Added %call_data field to each callback to give a keyed list of values. (Suggested by David Bainbridge, david@ics.com).
101. Test added to ensure that actions only called on Motif widgets with userData field (Sriram Srinivasan sriram@tcs.com).
102. Changed **argv to *argv[] for funcs called by Tcl_CreateCommand, to keep C++ happy (Sriram Srinivasan sriram@tcs.com).
103. Fixed bugs in destroyCallback.
104. Added method class.
105. Added regression test for widget creation.
106. Added support for tear-off menus, and the tearoff child.
107. Made it easier to add in additional widgets from other sources. (Lots of people have asked for this.)
108. Support for uil added. (Lots of people have asked for this.)
109. Added pattern matching mechanism so that widget names need not use the full path name, but can use a "*" match for the prefix (or any part, really). (Suggested by David Bainbridge, david@ics.com.)
110. Added String to WidgetClass converter which uses the class name (e.g. ``XmPushButton'') for the String.
111. Fixed error messages that said "wrong option" to say "wrong method" when appropriate.
112. Added method removeCallback.
113. Widgets created by Motif as children of SelectionBox, FileSelectionBox, MessageBox and ScrolledWindow have a method handler appropriate to their type.
114. Added shell command addwidget to simplify adding widgets by using a widget description file. Suggested by Harald Albrecht (albrecht@igpm.rwth-aachen.de).
115. Added a method to extend the data types accepted by a drop operation. (Chris Steres, steres@tcltown.wpd.sgi.com).

     ### release 1.3 Sept 5, 1994

116. Added /usr/local/lib to TLC_LIB search path in src/Imakefile.
117. Bug fixes to addwidget.
118. Fixed ref through unassigned wPtr in MyCreateCmd template in tmExtern.c
119. Added method getSelectionValue to all widgets.
120. Fixed bug on not expanding %% as % in callbacks.
121. Modified addwidget syntax to make it easier to define related widgets in a single file.
122. Some uil widgets have a delayed creation mechanism that means that a tree traversal of the widget tree after uil tree creation may not pick up some widgets. Fixed by Jean-Noel Albert (albert@lalcls.in2p3.fr)
123. Fixed bug in Tm_CreateTmInfo causing crash on destroyWidget for UIL widgets (Jean-Noel Albert, albert@lalcls.in2p3.fr).
124. Added MenuWidget to String converter to handle XmNmenuHistory resource of Option menus.
125. INCOMPATABLE CHANGE: if a resource can't be found in a resource list or in a constraint parent list, then we used to complain. Xt says to ignore this, and Motif relies on this behaviour (e.g allowShellResize in CreateFormDialog gets handed to both shell and form). So we don't complain any more, and ignore unrecognised resources silently. This only affects programs with resource errors.
126. Fixed bugs in converting strings to XmStrings that dropped newlines.
127. Improved error recovery in erroneous string to XmString specs (Wolfgang Kechel - wolfgang@pr-wiesbaden.de)
128. Fixed bugs in XmString to strings that dropped newlines.
129. Added method mrmFetchWidgetOverride.
130. Added entry to tclMotif.man describing XmString formatting syntax.
131. Added method AddWMProtocolCallback to root widget.
132. Fixed erroneous NULL pointer fix on fallbackResources, because tcl supplies the NULL anyway (Soren Juul Moller, slm@dde.dk).
133. INCOMPATABLE CHANGE: the string to XmString formatting converter is now used for lists of strings, instead of XmStringCreateLToR.
134. Added pending method to root widget to check for events on the queue.
135. Added method windowId (Wolfgang Kechel - wolfgang@pr-wiesbaden.de)
136. Added method displayInfo (Wolfgang Kechel - wolfgang@pr-wiesbaden.de)
137. Added support for multiple displays so that a topLevelShell may be created on a new (or already open) display (Wolfgang Kechel - wolfgang@pr-wiesbaden.de)
138. When method destroyWidget is run, the tcl command is deleted then rather than at widget destruction time. This may avoid problems of destroying and recreating widgets which under the delayed version may end up trashing the new command rather than the old one (which may have been overwritten by the new one).
139. In the children method, the WidgetList to String converter now ignores widgets that are "being destroyed", because no-one should want to know about these.
140. Flush event queue after defineCursor so that cursor changes immediately.
141. String to XmStringTable now has NULL entry at end, to terminate list. (Chris Craig, craig@ics.com)
142. Fixed bugs in Tm_ConvertShort/LongToString that used Dimension (Till Immanuel Patzsche, tip@pr-wiesbaden.de)
143. Fixed erroneous unitType setting - must be set after creation, not using the parent.
144. Added methods augmentTranslation, overrideTranslations, uninstallTranslations.
145. Added widget children OptionLabel and OptionButton to OptionMenu so that they can be manipulated.
146. Restored Motif 1.1 compilation, protecting TEAR_OFF, OBSCURED_TRAVERSAL, TextField widget.
147. Added converters BoolToString, ShellHoriz/VertDim/PosToString Immanuel Patzschke (tip@pr-wiesbaden.de).
148. Added methods lowerWindow, raiseWindow, warpPointer, beep (Wolfgang Kechel - wolfgang@pr-wiesbaden.de).
149. Lots of code cleanups (Wolfgang Kechel - wolfgang@pr-wiesbaden.de).
150. Fixed OptionMenu children getting wrong cmdInfo - bug introduced from #145.
151. Added method GetCommand for X11R5 session management.
152. Added converter StringTableToString.
153. No longer free array containing app resource XmNargv (cleans up bodgy fix to -geometry resource too!).
154. Fixed callback list traversal in removeCallbacks - Ruven Brooks (brooks@austin.sar.slb.com)
155. Compensated for bug in Motif 1.2 that didn't allow me to get the secondary resource data out of an XmDialogShell by special test in Tm_SetValues

Hops (hops@sco.com)
This page htmlised from the tclMotif-1.4 README and CHANGES pages