1
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
2
<!--Converted with LaTeX2HTML 98.1p1 release (March 2nd, 1998)
3
originally by Nikos Drakos (nikos@cbl.leeds.ac.uk), CBLU, University of Leeds
4
* revised and updated by: Marcus Hennecke, Ross Moore, Herb Swan
5
* with significant contributions from:
6
Jens Lippmann, Marek Rouchal, Martin Wilck and others -->
9
<TITLE>4. TCM User Interface</TITLE>
10
<META NAME="description" CONTENT="4. TCM User Interface">
11
<META NAME="keywords" CONTENT="TechDoc">
12
<META NAME="resource-type" CONTENT="document">
13
<META NAME="distribution" CONTENT="global">
14
<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1">
15
<LINK REL="STYLESHEET" HREF="TechDoc.css">
16
<LINK REL="next" HREF="developersguidenode6.html">
17
<LINK REL="previous" HREF="developersguidenode4.html">
18
<LINK REL="up" HREF="TechDoc.html">
19
<LINK REL="next" HREF="developersguidenode6.html">
22
<!--Navigation Panel-->
24
HREF="developersguidenode6.html">
25
<IMG WIDTH="37" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="next" SRC="next_motif.gif"></A>
28
<IMG WIDTH="26" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="up" SRC="up_motif.gif"></A>
30
HREF="developersguidenode4.html">
31
<IMG WIDTH="63" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="previous" SRC="previous_motif.gif"></A>
33
HREF="developersguidenode1.html">
34
<IMG WIDTH="65" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="contents" SRC="contents_motif.gif"></A>
36
<B> Next:</B> <A NAME="tex2html315"
37
HREF="developersguidenode6.html">5. TCM Class Hierarchy</A>
38
<B> Up:</B> <A NAME="tex2html312"
39
HREF="TechDoc.html">Toolkit for Conceptual Modeling</A>
40
<B> Previous:</B> <A NAME="tex2html306"
41
HREF="developersguidenode4.html">3. Source Code Organization</A>
44
<!--End of Navigation Panel-->
45
<!--Table of Child-Links-->
46
<A NAME="CHILD_LINKS"><strong>Subsections</strong></A>
48
<LI><A NAME="tex2html316"
49
HREF="developersguidenode5.html#SECTION00510000000000000000">4.1 X/Motif user interface</A>
50
<LI><A NAME="tex2html317"
51
HREF="developersguidenode5.html#SECTION00520000000000000000">4.2 User interface implementation</A>
53
<LI><A NAME="tex2html318"
54
HREF="developersguidenode5.html#SECTION00521000000000000000">4.2.1 Overview</A>
55
<LI><A NAME="tex2html319"
56
HREF="developersguidenode5.html#SECTION00522000000000000000">4.2.2 Application startup</A>
57
<LI><A NAME="tex2html320"
58
HREF="developersguidenode5.html#SECTION00523000000000000000">4.2.3 Main window structure</A>
59
<LI><A NAME="tex2html321"
60
HREF="developersguidenode5.html#SECTION00524000000000000000">4.2.4 Calling functions from the user interface</A>
62
<LI><A NAME="tex2html322"
63
HREF="developersguidenode5.html#SECTION00530000000000000000">4.3 Xlib drawing</A>
65
<!--End of Table of Child-Links-->
68
<H1><A NAME="SECTION00500000000000000000">
69
4. TCM User Interface</A>
74
<H1><A NAME="SECTION00510000000000000000">
75
4.1 X/Motif user interface</A>
80
<DIV ALIGN="CENTER"><A NAME="fig:gui_libs"> </A><A NAME="387"> </A>
82
<CAPTION><STRONG>Figure 4.1:</STRONG>
83
typical X/Motif application structure.</CAPTION>
87
<!-- MATH: $\includegraphics[width=4in]{p/gui.eps}$ -->
89
WIDTH="458" HEIGHT="377" ALIGN="BOTTOM" BORDER="0"
90
SRC="developersguideimg14.gif"
91
ALT="\includegraphics[width=4in]{p/gui.eps}"></DIV></TD></TR>
96
Figure <A HREF="developersguidenode5.html#fig:gui_libs">4.1</A> shows the relationships between the
97
built-in X, Motif and Unix libraries and an arbitrary X/Motif
98
application. All X, Motif and Unix libraries have a C interface
99
(functions, defines, typedefs, structs, enums, unions and variables).
100
When a library is depicted on top of another library, this means
101
that a library is implemented by means of the interface provided
102
by the underlying layer. You are referred to the X and Motif
103
books and manuals in the list of references at the end of this text.
106
The TCM X/Motif user interface is restricted to that part of the source
107
(classes and functions) that directly uses the Motif, Xt and Xlib
108
libraries. That part consists of most of the classes in the <TT>src/ui</TT>
109
directory and <I>some</I> of the classes in the other editor libraries.
110
The names of the editor specific user interface classes all
111
end on <TT>Window</TT> or <TT>Stubs</TT>, such as <A NAME="tex2html113"
112
HREF="../sourcecode/ERWindow.html"><TT>ERWindow</TT></A>,
113
<A NAME="tex2html114"
114
HREF="../sourcecode/DFWindow.html"><TT>DFWindow</TT></A>
116
<A NAME="tex2html115"
117
HREF="../sourcecode/DiagramStubs.html"><TT>DiagramStubs</TT></A>,
118
<A NAME="tex2html116"
119
HREF="../sourcecode/TableStubs.html"><TT>TableStubs</TT></A>
121
The window classes are all specializations of the abstract class
122
<A NAME="tex2html117"
123
HREF="../sourcecode/MainWindow.html"><TT>ui/MainWindow</TT></A>.
124
The stub classes contain functions that are called from the user interface
125
widgets (menus, push buttons, text fields etc.) and these functions in turn
126
call application specific functions of non-GUI objects.
129
The <A NAME="tex2html118"
130
HREF="../sourcecode/DrawingArea.html"><TT>ed/DrawingArea</TT></A>
132
is not part of libgui but of libeditor because it also has application specific
133
behavior (albeit at a high level). The drawing area needs a viewer class (a
134
descendent of class <A NAME="tex2html119"
135
HREF="../sourcecode/Viewer.html"><TT>ed/Viewer</TT></A>).
136
The viewer class should provide functions that are called when mouse
137
buttons are pressed or dragged in the drawing area, when the mouse pointer
138
is moved or when a characters are typed in while the mouse pointer is
142
When asked what code contains X/Motif calls (and forms the GUI) then
143
the answer is: almost all code of <A NAME="tex2html120"
144
HREF="../../src/ui">src/ui</A>,
145
all classes that end on <TT>Window</TT> or end on <TT>Stubs</TT> and the
149
The entire TCM distribution of the current version consists of about 450
150
classes and about 83000 lines of code (source and headers files,
151
including white spaces and comments, but excluding the 20-line header
152
part of the GNU General Public License).
153
The X/Motif dependent part is about 19000 lines of code.
154
This is the part that should be rewritten when TCM is translated to
155
a non-X Windows environment.
158
The TCM user interface is more or less insulated into a restricted
159
part of the source code, put in a number of C++ classes that are
160
clearly distinguishable from the rest. But
161
the user interface code is spread over all the TCM libraries
162
(except libglobal). The reason for this organization is that factoring
163
out the commonalities between all different tools was for us more
164
important than a complete separation of the entire application code on
165
one hand and the entire user interface code on the other. This means that
166
each diagram editor has its own specific node and edge buttons. The code
167
for creating tiled buttons in general is part of libgui but the specific
168
initialization is done in the code of a specific diagram editor.
171
The approach of factoring out commonalities was a design for <B>evolution</B>
172
and that has proved to work for TCM. It makes it
173
relatively easy to add new tools or modify individual existing tools
174
while maintaining a stable core of libraries and unrelated tools. When
175
features are added to some library or to some tool, all tools that are
176
included in the area of that library or tool (see figure <A HREF="developersguidenode4.html#fig:src_organization">3.1</A>)
177
are also updated minimizing the risk of code redundancy or inconsistencies.
181
<H1><A NAME="SECTION00520000000000000000">
182
4.2 User interface implementation</A>
187
<H2><A NAME="SECTION00521000000000000000">
192
Like all X11 applications, the TCM tools are event driven. This means they
193
have the following basic structure:
196
<DD>Create the widgets.
198
<DD>Register the event handlers for these widgets.
200
<DD>Go into the main event loop.
202
<DD>Activate the appropriate event handler when a specific event
203
occurs on a specific widget.
205
<DD>Return to the main event loop when done.
208
When a TCM tool is started the widgets that form the main window are created.
209
The class <A NAME="tex2html121"
210
HREF="../sourcecode/EditWindow.html"><TT>ed/EditWindow</TT></A>
211
and its specializations contain the functions to create the
212
constituent parts of the main window. These widgets have one or more so-called
213
<B>call-back functions</B>: the widget reacts to a certain set of X events
214
(that set is built-in) and when such an event occurs a user-supplied action,
215
in the form of ordinary C functions, will be called. In our implementation we do not
216
use ordinary C functions but instead we provide C++ static member functions.
219
An exception to this use of callbacks, is the drawing area widget
220
which, by default, does not react on the events that are needed to
221
draw pictures as we like to
222
do in TCM. Therefore, so-called <I>translations</I> are used, an X-Toolkit data
223
structure to define some specified mapping of X events to user
224
supplied actions. All details of translations and drawing area events
225
are hidden in the <A NAME="tex2html122"
226
HREF="../sourcecode/DrawingArea.html"><TT>ed/DrawingArea</TT></A>
230
Most pop-up window <A NAME="tex2html123"
231
HREF="../sourcecode/Dialog.html">dialog widgets</A>
232
are created during initialization.
233
When they are popped up they do not have to be created (which is much
234
faster) and when these dialogs are dismissed they are not destroyed,
235
but they are simply kept unmanaged (invisible).
236
An exception to this are so-called <A NAME="tex2html124"
237
HREF="../sourcecode/MessageDialog.html">message dialogs</A>, for error and warning
238
messages etc. These are created on the fly because we can not determine
239
in advance how many of which kind will be necessary.
242
A special kind of message dialog is the <A NAME="tex2html125"
243
HREF="../sourcecode/QuestionDialog.html">question dialog</A>
245
modal. This means that the user can only respond to this dialog and other
246
user actions in the applications are prohibited. This is necessary when the
247
application has to have an answer before it can proceed (e.g.
248
the `save before quit?' dialog).
251
The main event loop is built-in in Motif, as well as the calling
252
of the event handlers (via callback or translation).
256
<H2><A NAME="SECTION00522000000000000000">
257
4.2.2 Application startup</A>
261
In contrast with an ordinary C program the editors don't start by directly
262
entering the <TT>main()</TT> function. Instead, each editor is compiled with
263
a distinct file <TT>??editor.c</TT>, e.g. <A NAME="tex2html126"
264
HREF="../../src/sd/gd/gdeditor.c"><TT>gdeditor.c</TT></A>
266
file two global objects are created (but the two instance variables are
267
not visible outside this file). For example:
270
Application *app = new Application("Tcm");
271
MainWindow *mw = new GDWindow("Tcm");
273
This means that the very first thing that is done on start-up is
274
calling the constructor <BR> <TT>Application::Application</TT>
275
and then the constructor <TT>GDWindow::GDWindow</TT>.
276
So, for each editor first an instance of class <A NAME="tex2html127"
277
HREF="../sourcecode/Application.html"><TT>ui/Application</TT></A>
278
is created and then an instance of an editor specific
279
main window class is created (but both are not initialized yet).
280
<A NAME="tex2html128"
281
HREF="../sourcecode/MainWindow.html">MainWindow</A>
283
both part of libgui. Specific main window classes such as
284
<A NAME="tex2html129"
285
HREF="../sourcecode/GDWindow.html">GDWindow</A>
286
are specializations of
287
MainWindow and are included in the specific diagram editor sources.
290
There should be just one instance of class Application per editor instance,
291
which can be accessed via the global variable named <TT>theApplication</TT>.
292
The application opens the X display, sets the color map and
293
does some other things that are applicable for the entire application.
294
Furthermore, the application class keeps track of a list of
295
the application (main)
296
windows. The current TCM implementation is limited to a single main
297
window (the other windows are made as pop-up dialog windows) but in principle
298
the framework of libgui can be utilized in programs that have
299
multiple main windows.
302
After the creation of both class instances, the function
303
<TT>main(argc, argv)</TT> is entered in which
304
<TT>theApplication->Initialize(argc, argv)</TT> is called.
305
The <TT>main</TT> function is generic and is part of libgui.
306
The application then creates an object config of type <A NAME="tex2html130"
307
HREF="../sourcecode/Config.html">Config</A>, which reads in the configuration file and keeps
308
tracks of various editor defaults. Then the application
309
initializes the Xt application context and subsequently
310
calls the main window initialization functions.
313
The main window initialization consists of the
314
creation of the main window widgets.
315
After the main window widgets are created, some other important
316
objects are created (in the <A NAME="tex2html131"
317
HREF="../sourcecode/DiagramWindow.html">DiagramWindow</A>
318
or <A NAME="tex2html132"
319
HREF="../sourcecode/TableWindow.html">TableWindow</A>
325
<LI><TT>printer</TT> of class <A NAME="tex2html133"
326
HREF="../sourcecode/Printer.html"><TT>ed/Printer</TT></A>. This object keeps
327
track of all page and print options and takes care of printing
328
and generating PostScript.
329
<LI><TT>helper</TT> of class <A NAME="tex2html134"
330
HREF="../sourcecode/Helper.html"><TT>ed/Helper</TT></A>. This object shows
331
the on-line help messages. It reads the help messages from file.
332
<LI><TT>document</TT> of an editor specific specialization of the
333
abstract class <A NAME="tex2html135"
334
HREF="../sourcecode/Document.html"><TT>ed/Document</TT></A>, depending on the base class of the
335
main window. E.g. <A NAME="tex2html136"
336
HREF="../sourcecode/GDWindow.html">GDWindow</A>
338
<A NAME="tex2html137"
339
HREF="../sourcecode/GDDiagram.html">GDDiagram</A>,
340
<A NAME="tex2html138"
341
HREF="../sourcecode/DFWindow.html">DFWindow</A>
343
<A NAME="tex2html139"
344
HREF="../sourcecode/DFDiagram.html">DFDiagram</A>
346
object keeps track of the document information (like document name, author etc.)
347
and takes amongst others care of loading documents from file and saving them
349
<LI>Depending on the kind of document that is created some
350
extra objects are created such as a <A NAME="tex2html140"
351
HREF="../sourcecode/Graph.html">graph object</A>
353
editors (a <A NAME="tex2html141"
354
HREF="../sourcecode/GDGraph.html">GDGraph</A>
356
that manages the nodes and edges of the document and a
357
<A NAME="tex2html142"
358
HREF="../sourcecode/DiagramViewer.html">viewer object</A>
359
(<A NAME="tex2html143"
360
HREF="../sourcecode/GDViewer.html">GDViewer</A>
362
that manages in the case of a diagram editor one or more views containing a set of
363
graphical shapes. In the case of a table editor the
364
<A NAME="tex2html144"
365
HREF="../sourcecode/TableViewer.html">viewer object</A>
367
the rows and columns of the table.
370
These objects (of which exactly one instance exist per
371
main window), will be supplied as parameter to the Motif
372
callback functions <A NAME="tex2html145"
373
HREF="#foot486"><SUP>4.1</SUP></A>. The callback function are
374
static member functions of one of the stub classes. When the
375
stub is called then the object is casted to the right type
376
(because the parameters to stubs are simply pointers)
377
and the appropriate class member of this object is called
378
possibly with some other parameters that are supplied to
382
And finally, after the creation of the main window, the application
383
object and the other main editor objects, the X main
384
event loop is entered, giving X the control.
388
<H2><A NAME="SECTION00523000000000000000">
389
4.2.3 Main window structure</A>
394
<DIV ALIGN="CENTER"><A NAME="fig:mainwindow"> </A><A NAME="491"> </A>
396
<CAPTION><STRONG>Figure 4.2:</STRONG>
397
Main window of the generic diagram editor.</CAPTION>
401
<!-- MATH: $\includegraphics[width=6in]{p/mainwin.eps}$ -->
403
WIDTH="687" HEIGHT="465" ALIGN="BOTTOM" BORDER="0"
404
SRC="developersguideimg15.gif"
405
ALT="\includegraphics[width=6in]{p/mainwin.eps}"></DIV></TD></TR>
410
See figure <A HREF="developersguidenode5.html#fig:mainwindow">4.2</A> for the basic main window's widget structure.
411
The boxes are Motif widgets (widget type and name between parentheses).
412
The arrows connect widgets with their parents. The root is the top-level
413
shell (TCM). To be more exact: the figure shows the main window of the
414
generic diagram editor, TGD. The other diagram editors look almost
415
the same, the main difference are their node and edge buttons.
416
The table editors are almost similar too but they do not have
417
node and edge buttons of course.
420
When libeditor.so is compiled with the option <TT>-DDUMPWIDGETTREE</TT>,
421
a textual representation of the widget structure will be written to standard output
422
when the editor is started (its output is also used for making
426
The details about creation of the widgets can be found in the classes
427
<A NAME="tex2html147"
428
HREF="../sourcecode/MainWindow.html"><TT>ui/MainWindow</TT></A>,
429
<A NAME="tex2html148"
430
HREF="../sourcecode/EditWindow.html"><TT>ed/EditWindow</TT></A>,
431
<A NAME="tex2html149"
432
HREF="../sourcecode/DrawWindow.html"><TT>ed/DrawWindow</TT></A>,
433
<A NAME="tex2html150"
434
HREF="../sourcecode/DiagramWindow.html"><TT>dg/DiagramWindow</TT></A>,
435
<A NAME="tex2html151"
436
HREF="../sourcecode/TableWindow.html"><TT>tb/TableWindow</TT></A>
438
See the class hierarchy of chapter <A HREF="developersguidenode6.html#chap:class_hierarchy">5</A> for the relationships and
439
all the members of these classes.
443
<H2><A NAME="SECTION00524000000000000000">
444
4.2.4 Calling functions from the user interface</A>
448
Menus are created by the constructor function of class
449
<A NAME="tex2html152"
450
HREF="../sourcecode/Menu.html"><TT>ui/Menu</TT></A>.
451
For an example for how to create a menu see <TT>dg/DiagramWindow::CreateMenuBar</TT>.
454
The items of a menu are specified by means of the
455
<A NAME="tex2html153"
456
HREF="../sourcecode/MenuItem.html"><TT>ui/MenuItem</TT></A>
458
A menu contains a list of menu items, which can be supplied to the menu
459
constructor function. The menus common to all drawing editors are made in
460
<A NAME="tex2html154"
461
HREF="../sourcecode/DrawWindow.html"><TT>ed/DrawWindow</TT></A>, the
462
menus common to all diagram editors are made in
463
<A NAME="tex2html155"
464
HREF="../sourcecode/DiagramWindow.html"><TT>dg/DiagramWindow</TT></A>
465
and the menus common to all table editors are made in
466
<A NAME="tex2html156"
467
HREF="../sourcecode/TableWindow.html"><TT>tb/TableWindow</TT></A>.
468
Likewise, menus that are specific for a single editor, are made
469
in the corresponding main window class.
472
One of the fields of a MenuItem is the function that will be called when
473
the menu item is selected. These functions are called stubs and have to
474
be static C++ class members. The functions that are supplied are all part of a
475
<TT>...Stubs</TT> class which consist entirely of these static functions.
476
Menu items also have a so-called callback data.
477
The callback data is always used to pass a pointer to the object
478
whose class member should be called. For example, the Print menu item
479
has as callback function the Print function of
480
<A NAME="tex2html157"
481
HREF="../sourcecode/EditStubs.html"><TT>ed/Editstubs</TT></A>
482
and as callback data a pointer to a printer of class
483
<A NAME="tex2html158"
484
HREF="../sourcecode/Printer.html"><TT>ed/Printer</TT></A>.
485
In the stubs function <TT>Printer::Print</TT> is called.
488
You can also call functions via the other main window widgets, for instance
489
the diagram name text field or the node and edge toggle buttons.
490
This works similar as with menus. You have to supply a callback function
491
(<TT>XtCallBack</TT>) after the widget creation. These callbacks are also
492
listed in the stub classes.
496
<H1><A NAME="SECTION00530000000000000000">
501
This is a very short introduction to drawing lines etc. in Xlib. For the
502
rest you are referred to the documentation mentioned in the references.
505
X has 16 drawing modes (so called raster operations). A technique for
506
simulating graphical objects moving or stretching (like resizing a box
507
or a ``rubber band'' line), is to set the Graphics Context
508
to the eXclusive-OR raster operation mode. The Graphics Context
509
is an Xlib data structure which determines how an object will be drawn
510
when a drawing routine is called (XDrawLine, XDrawRectangle etc.).
511
In XOR mode, the new destination pixel is produced by the exclusive
512
or of the old destination pixel with the source pixel.
513
In this mode, you can easily draw and erase a figure. You draw a figure
514
to let it appear, and when you redraw it, you erase it. By sequencing
515
drawing and redrawing you can simulating an object being moved or
516
dragged. Furthermore, in XOR mode, objects can overlap each other
517
without damaging each other. The overlapping part is then white, and
518
when one of the objects is moved or removed it will be redrawn, so
519
that the overlapping part will appear black again.
520
All details of drawing graphics with Xlib is hidden in
521
the <A NAME="tex2html159"
522
HREF="../sourcecode/XGrafport.html"><TT>XGrafport</TT></A>
524
An XGrafport has as attributes some GCs.
527
Note that each Xlib drawing operation is performed twice: one on the
528
drawing area (window) and one on a Pixmap that serves as a backup
529
store. This is needed because X does not automatically save the window
530
contents when the window is overlapped or resized.
533
All the entire Xlib drawing functionality is hidden in the
534
<TT>ui/XGrafport</TT> class which is a descendant of the abstract
535
<A NAME="tex2html160"
536
HREF="../sourcecode/Grafport.html"><TT>ui/Grafport</TT></A>
538
Because XGrafport only uses a reference to the X Display and an X Window it
539
can be used rather easily in any 2D drawing program under X (it uses Xlib
540
but it does not use Motif nor the other classes of libgui that use Motif).
543
<BR><HR><H4>Footnotes</H4>
545
<DT><A NAME="foot486">... functions </A><A NAME="foot486"
546
HREF="developersguidenode5.html#tex2html145"><SUP>4.1</SUP></A>
547
<DD>`callback' is Motif-speak. `stub' is
548
TCM-speak and means in this context the kind of callback
549
function that is used in TCM and it forms an intermediate between
550
the GUI (which uses X/Motif) and the other classes which do
551
not depend on X/Motif.
554
<!--Navigation Panel-->
555
<A NAME="tex2html314"
556
HREF="developersguidenode6.html">
557
<IMG WIDTH="37" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="next" SRC="next_motif.gif"></A>
558
<A NAME="tex2html311"
560
<IMG WIDTH="26" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="up" SRC="up_motif.gif"></A>
561
<A NAME="tex2html305"
562
HREF="developersguidenode4.html">
563
<IMG WIDTH="63" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="previous" SRC="previous_motif.gif"></A>
564
<A NAME="tex2html313"
565
HREF="developersguidenode1.html">
566
<IMG WIDTH="65" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="contents" SRC="contents_motif.gif"></A>
568
<B> Next:</B> <A NAME="tex2html315"
569
HREF="developersguidenode6.html">5. TCM Class Hierarchy</A>
570
<B> Up:</B> <A NAME="tex2html312"
571
HREF="TechDoc.html">Toolkit for Conceptual Modeling</A>
572
<B> Previous:</B> <A NAME="tex2html306"
573
HREF="developersguidenode4.html">3. Source Code Organization</A>
574
<!--End of Navigation Panel-->
576
<I>Henk van de Zandschulp</I>
577
<BR><I>2003-01-07</I>
added
removed
doc/developersguide/developersguidenode5.html
