1
2 The Three-D Athena Toolkit (Xaw3d)
3 ----------------------------------
4
5 This is Release 1.5E of the Xaw3d toolkit (dated March 8, 2003), an
6 update that fixes some bugs, and adds many features. There were no
7 public releases of 1.5A through 1.5D.
8
9 I am not Kaleb Keithley. Kaleb has moved on, and no longer supports
10 Xaw3d; it's my baby now. This distribution is not a fork - it is the
11 latest update of the One True Xaw3d.
12
13 While not as insistant as Kaleb was, I do suggest you include this
14 file, as is, with any product that includes Xaw3d, in whole or in
15 part, in any form. This file is the authoritative documentation for
16 Xaw3d.
17
18 If you discover bugs not already known, do not contact Kaleb; he's had
19 no part in this effort. Feel free to contact me; I'll try to respond
20 in kind. If you're new to the Athena toolkit, understand that it is
21 highly configurable, and some resources will interact (or not) with
22 undesirable results. Some of these are bugs, but many are just the
23 nature of the beast.
24
25 D. J. Hawkey Jr.
26 _________________________________________________________________
27
28 Usage:
29 ------
30
31 This release of Xaw3d is based on X.Org's X11R6.3 Athena toolkit, with
32 bits and pieces thrown in from other sources. It is intended to be a
33 general-purpose replacement for the Athena (Xaw) toolkit.
34
35 In general, you should be able to link almost any Athena-based
36 application to this Xaw3d Athena toolkit, for a three-dimensional
37 appearance on most of the widgets. On systems with shared libraries,
38 you might be able replace your shared libXaw.* with libXaw3d.* to
39 obtain the appearance without even relinking, but the odds of this
40 working is slim, and not recommended.
41
42 Applications written for Xaw3d might have to test the library for a
43 particular feature (see the "Xaw3d build options" section below). To
44 accomodate this, a private header is installed which reflects the
45 library's capabilities. Xaw3dP.h contains four definitions that may be
46 used for this purpose. For example:
47
48 #define XAW_INTERNATIONALIZATION
49 #define XAW_MULTIPLANE_PIXMAPS
50 #define XAW_GRAY_BLKWHT_STIPPLES
51
52 Xaw3dP.h need not be included by the application source, as the public
53 headers that reference any 3D features include this header. The
54 default configuration is set up to match the capabilities of X.Org's
55 Xaw toolkit.
56
57 The use of most shadow resources should be intuitive enough, and may
58 be set or read conventionally (e.g., resource files, editres,
59 programatically, etc.). The userData resource may be used to "hang"
60 application-specific data on a widget, but this is accessable to
61 programs only. Other resources and less-than-obvious features are
62 documented throughout this file.
63
64 The default resource values present a not-as-pretty-as-it-could-be
65 appearance, due to stippled shadows (as opposed to allocated colors)
66 in order to conserve colormap space, and by allowing non-rectangular
67 pushbuttons, which are not shadowed. To specify otherwise, set these
68 resources:
69
70 *beNiceToColormap: False
71 *shapeStyle: Rectangle
72
73 You might also want to remove the borders from some widgets:
74
75 *Text.borderWidth: 0
76 *SimpleMenu.borderWidth: 0
77 *Paned.internalBorderWidth: 0
78
79 To revert to reverse-video highlighting in menus:
80
81 *SmeBSB.shadowWidth: 0
82
83 Note that shadows "grow outward" in the SimpleMenu and Text widgets,
84 increasing these widgets' sizes, "grow inward" in the Viewport and
85 Scrollbar widgets, decreasing the size of the clip widget and thumb,
86 respectively, and "grow inward" in the Label (and superclasses of) and
87 SmeBSB widgets, encroaching on their label parts. Fat shadows will
88 probably mean some futzing with size or margin resources for a proper
89 appearance.
90 _________________________________________________________________
91
92 Xaw3d build requirements:
93 -------------------------
94
95 Many header files have changed since Release 1.5. This means that any
96 installed Xaw3d headers must be removed before building this
97 distribution, to see that these source files include these header
98 files. Renaming the directory that the existing headers live in is
99 sufficient.
100
101 Xaw3d build options:
102 --------------------
103
104 Like Xaw, the default Xaw3d does not accomodate multi-plane pixmaps.
105 However, at the top of this distribution's Imakefile are the lines:
106
107 XCOMM For color pixmaps, define MULTIPLANE_PIXMAPS:
108 #undef MULTIPLANE_PIXMAPS
109
110 If you want color pixmaps, and have Arnaud Le Hors's XPM library
111 installed, change the "#undef" to "#define". You may then specify
112 either XPM or XBM files for any Xaw3d bitmap resource, whether by
113 resource files, with editres, programmatically, etc.. And yes, the
114 transparency of XPM files is honored.
115
116 Note that this enables the use of structures and functions in the XPM
117 library; the XPM library include file (xpm.h) must be available when
118 building Xaw3d, and the XPM library must then be linked to any and all
119 applications that use Xaw3d. This makes Xaw3d dependant on the XPM
120 library, so think twice about it.
121
122 The default stippled shadows used when the beNiceToColormap resource
123 is True work well enough, except for widgets that have black or white
124 backgrounds. So, at the top of this distribution's Imakefile, are the
125 lines:
126
127 XCOMM For grayed stipple shadows, define GRAY_BLKWHT_STIPPLES:
128 #define GRAY_BLKWHT_STIPPLES
129
130 This makes Xaw3d allocate a gray colorcell, and use it in stippled
131 shadows when 1) widgets have black or white backgrounds and 2) the
132 beNiceToColormap resource is True and 3) the display allows it. This
133 option was disabled in previous Xaw3d releases.
134
135 Building Xaw3d within an X11 source tree:
136 -----------------------------------------
137
138 This distribution expects a configured X11R6.[1-6] source tree (by
139 "configured", I mean that the imake infrastructure has been built).
140 You can use the source from X.Org, XFree86, or the X Project Team.
141
142 Change to the directory containing /xc, and issue these commands:
143
144 # gunzip -c Xaw3d-1.5E.tar.gz | tar -xpf -
145 # cd xc/lib/Xaw3d
146 # ../../config/imake/imake -I../../config/cf \
147 -DTOPDIR=../.. -DCURDIR=lib/Xaw3d
148 # make includes; make depend; make; make install
149
150 The Imakefile uses the Xaw symbols in /xc/config/cf, so if you have
151 debug, shared, profile, etc. libraries specified for Xaw, Xaw3d will
152 have them as well.
153
154 Building Xaw3d without an X11 source tree:
155 ------------------------------------------
156
157 Near the top of this distribution's Imakefile are the lines:
158
159 XCOMM When building outside an X11 source tree:
160 XCOMM EXTRA_INCLUDES = -I.
161
162 Uncomment the second line by deleting the "XCOMM ". Then, while still
163 in /xc/lib/Xaw3d, issue these commands:
164
165 # mkdir X11; cd X11; ln -fs .. Xaw3d; cd ..
166 # xmkmf; make depend; make; make install
167
168 If this works for you, great. If not, well, happy hacking.
169
170 Building Xaw3d under X11R5:
171 ---------------------------
172
173 I don't know that Xaw3d will build within an X11R5 source tree, so try
174 the "Building Xaw3d without an X11 source tree" instructions. If the
175 "make" command results in nothing being built, find these lines about
176 half-way into this distribution's Imakefile:
177
178 XCOMM At least one X11R5 distribution needs this:
179 XCOMM #include "Imakefrag.X11R5"
180
181 Uncomment the second line by deleting the "XCOMM ", and re-issue the
182 "xmkmf; make depend; make; make install" commands. This line will
183 insert the quoted file into the Makefile, and is for when the imake
184 configuration files don't create the appropriate rules.
185
186 Xaw3d and Internationalization:
187 -------------------------------
188
189 The Imakefile depends on a conventional system-wide definition for
190 including or omitting I18n support (i.e., "XawI18nDefines"). If the
191 Imakefile erroneously disables support for I18n (see the generated
192 Xaw3dP.h file), I can only suggest searching your imake configuration
193 files for a definition that enables support for "wide characters" (try
194 `egrep 'WCHAR|WCTYPE|XMBTOWC|ISW_FUNCS' *`), and then, about half-way
195 into this distribution's Imakefile, find these lines:
196
197 #ifdef XawI18nDefines
198 #define INTERNATIONALIZATION
199 HEADERS = $(BASE_HDRS) $(I18N_HDRS)
200 SRCS = $(BASE_SRCS) $(I18N_SRCS)
201 OBJS = $(BASE_OBJS) $(I18N_OBJS)
202 ...
203
204 Change the label in the first line to the label of the definition you
205 found. If no suitable definition is found, and I18n really is
206 supported, it's likely implemented in such a way that Xaw3d probably
207 won't include I18n support without some hacking at the Imakefile or
208 Makefile.
209 _________________________________________________________________
210
211 New in 1.5A:
212 ------------
213
214 The SimpleMenu widget now supports scrolling through entries too
215 numerous to fit on the screen, with a new resource supporting a scroll
216 jump value. The record variable is simple_menu.jump_val, resourced as
217 XtNjumpScroll, and classed as XtCJumpScroll. Adapted from an early
218 neXtaw toolkit.
219
220 Added 3D support to the SimpleMenu, Text, and Viewport widgets.
221
222 Four minor changes in ThreeD.c and SmeThreeD.c to have the widgets use
223 the app's colormap, rather than the screen's default, for those apps
224 that create their own.
225
226 Added the deletion of laygram.h to the Imakefile.
227
228 Created Xaw3dP.c, for functions shared by other modules that have no
229 other appropriate home.
230
231 A new directory containing sample resource files for a few apps. See
232 the README.AD file in that directory.
233
234 New in 1.5B:
235 ------------
236
237 Made Imakefile a bit more friendly to build options. Makefile now
238 defines the build options in Xaw3dP.h during the build.
239
240 Added to the key translation tables in Panner.c and TextTr.c, and some
241 rules to Imakefile, to make this distribution X11R5 compliant. Tested
242 on exactly one X11R5 system; your mileage may vary.
243
244 Made internationalization support conditional, for systems lacking or
245 broken. Tested on exactly two systems, one with and one without; your
246 mileage may vary.
247
248 New in 1.5C:
249 ------------
250
251 Enabled multi-plane pixmap support with a new Xt resource type
252 converter. The "Xaw3d build options" section has more information.
253
254 Added private Pixmap resources to the Label and SmeBSB widgets for
255 stippled copies of the public Pixmap resources (record variables
256 label.stippled, label.right_stippled, sme_bsb.left_stippled, and
257 sme_bsb.right_stippled, respectively). Insensitive pixmaps are now
258 rendered properly.
259
260 New in 1.5D:
261 ------------
262
263 Added two resources to the SimpleMenu widget for setting margins. The
264 SmeBSB widgets have a tighter relationship with their parent and
265 siblings; menus and their entries now respond properly to changes in
266 themselves or their parent. See the section "The SimpleMenu widget and
267 margins" below for a detailed explanation.
268
269 New in 1.5E:
270 ------------
271
272 Enabled a new resource in the ThreeD widget to specify one of five
273 shadow types. The record variable is threeD.relief (the record part is
274 transparent), resourced as XtNRelief and classed as XtCRelief. It
275 accepts as values XtReliefNone, XtReliefRaised, XtReliefSunken,
276 XtReliefRidge, and XtReliefGroove. Note that the Text, SimpleMenu,
277 Scrollbar, and Viewport widgets ignore this resource, and display only
278 raised or sunken shadows. Built on the unfinished work of an early
279 neXtaw toolkit.
280
281 Added support for sub-menus in the SimpleMenu widget. Inspired by the
282 xfig application, adapted from XFree86's X11R6.6 "Xaw7" toolkit, and
283 made better than both. See the section "The SimpleMenu widget and
284 sub-menus" below for usage.
285
286 Added a resource to the SmeBSB widget to specify an underlined
287 character in the label. The record variable is sme_bsb.underline,
288 resourced as XtNunderline, and classed as XtCUnderline. It accepts an
289 integer as an index to the character; a value less than zero or
290 greater than or equal to the label length inhibits underlining.
291 Adapted from a recent distribution of the xfig application.
292
293 Made the SmeThreeD widget sensitive to the GRAY_BLKWHT_STIPPLES build
294 option (see the "Xaw3d build options" section for what this is and
295 does).
296
297 Added support for "tooltips". Inspired by the xfig application and
298 adapted from XFree86's X11R6.6 "Xaw7" toolkit. See the section "The
299 Tip widget" below for usage.
300
301 Fixed some geometry and positioning bugs in the Label widget. It's
302 internalHeight and internalWidth resources are now used to enforce a
303 minimum size when it's resize resource is True. The Label (and
304 superclasses of) widget now resizes properly to changes in label parts
305 and internal margins (subject to any constraints placed on the
306 widgets, of course).
307
308 Swapped the top and bottom colors in the stippled pixmap shadows.
309
310 Fixed a shadow drawing bug in the Command widget, when the shape is
311 changed.
312
313 Fixed the shadow state bug in the SmeBSB widget.
314
315 Dropped support for Linux shared a.out libraries.
316 _________________________________________________________________
317
318 Bugs and deficiencies:
319 ----------------------
320
321 You may not be be able to replace shared libXaw.* libraries with
322 libXaw3d.* libraries on systems with SVR3-style shared libraries.
323
324 The lexer in the Layout widget doesn't work well when a program that
325 uses the Layout widget is linked with GNU's malloc(). This is a
326 problem on older releases of Linux, where the libc malloc() is is GNU
327 malloc(). It's also a problem on older releases of FreeBSD if
328 "ExtraLibraries -lgnumalloc" is specified in imake's FreeBSD.cf
329 configuration file (this may be a problem on other BSDs too, but I
330 don't know this as fact). The solution under FreeBSD is to delete the
331 "ExtraLibraries" line(s) in the vendor.cf configuration file, or edit
332 the Makefile to not link with "-lgnumalloc". I don't have a solution
333 for older Linux distributions, nor do I have the time (or inclination)
334 to figure one out. If you discover a fix, you're more than welcome to
335 send it in.
336
337 The samples in Layout.h are wrong and don't work. Example programs
338 written by Keith Packard that use the Layout widget are available at
339 ftp://ftp.x.org/R5contrib/.
340
341 If an application subclasses Athena's Simple or Sme classes, or
342 subclasses thereof, there is a high probability that Xaw3d isn't
343 source compatible. Sorry, I have no plans (or ideas) on how to fix
344 this.
345
346 Xaw3d pixel allocation may not behave well when beNiceToColormap is
347 False and the colormap (default or application) is full.
348
349 Non-rectangular Command widgets are not rendered with shadows.
350
351 All geometry management routines should fully account for shadow
352 widths, but some don't, and it can show.
353
354 A few bugs and ambiguities in the Athena toolkit from which this
355 distribution is derived have been resolved. While trying to be true to
356 Athena documentation, these changes may make Xaw3d behave oddly for
357 some applications. Nothing that can't be fixed by tweaking the
358 appropriate resources, I'll wager.
359
360 A comment that appears in the xterm source:
361 -------------------------------------------
362
363 *
364 * ...There be serious and nasty dragons here.
365 *
366
367 xterm is, well, xterm. The auto-scroll with arrow-style scrollbars
368 won't work in xterm because it relies on timeouts. xterm, perhaps for
369 speed, circumvents XtAppNextEvent() by using XNextEvent() to get its X
370 events, with the unfortunate side effect of completely ignoring "other
371 sources", like timeouts. At this time there is no patch to fix the
372 X11R6 xterm, but there is a patch for the X11R5 xterm at
373 ftp://ftp.x.org/contrib/widgets/Xaw3d/R5/; it shouldn't be too hard to
374 integrate it into the X11R6 sources.
375 _________________________________________________________________
376
377 The SimpleMenu widget and margins:
378 ----------------------------------
379
380 Two resources have been added to the SimpleMenu widget for margin
381 management. The record variables are simple_menu.left_whitespace and
382 simple_menu.right_whitespace, resourced as XtNleftWhitespace and
383 XtNrightWhitespace, and classed as - yup - XtCLeftWhitespace and
384 XtCRightWhitespace. They can be also be referenced together by the
385 class XtCHorizontalWhitespace.
386
387 To illustrate, the leftMargin resource can be different values in each
388 SmeBSB widget, and SimpleMenu will oblige. If a pixmap wider than the
389 margin is specified in any SmeBSB widget, the result is less than
390 desirable (refer to ORA X, Vol 5 Sec 6, SmeBSB.*Bitmap and
391 SmeBSB.*Margin). Set the leftWhitespace resource in the parent
392 SimpleMenu widget, and SimpleMenu will set all children SmeBSB
393 leftMargins to that value. Specify a pixmap of any width for any
394 SmeBSB child, and SimpleMenu will separate the elements (menu edge,
395 pixmap, and text) of all SmeBSB children with that minimum distance as
396 it vertically aligns their text elements.
397
398 The SimpleMenu widget now resizes not only to the above, but also to
399 changes in these SmeBSB traits: Labels and fonts, pixmaps, and
400 margins.
401
402 Implementation notes: The SimpleMenu *Whitespace resources override
403 and replace the values of SmeBSB *Margin resources. To nullify this
404 behavior, a *Whitespace resource must first be set to zero, and the
405 corresponding *Margin resources then set appropriately. The *Margin
406 resources remain unchanged in and of themselves; they behave just as
407 always when the *Whitespace resources are not used.
408
409 The SimpleMenu widget and sub-menus:
410 ------------------------------------
411
412 Resources have been added to the SimpleMenu and SmeBSB widgets to
413 support sub-menus. The record variables are simple_menu.sub_menu and
414 simple_menu.state (neither are public), and sme_bsb.menu_name, which
415 is resourced as XtNmenuName, and classed as XtCMenuName. It's the
416 latter resource that is used by an application, and by default it is
417 NULL; menus behave as they always have. When this resource is set to a
418 menu name, the parent SimpleMenu widget will use the SmeBSB widget as
419 the entry point to a child SimpleMenu widget, managing it's visibility
420 and location. No constraints are placed on focus or the pointer.
421 Consider this code fragment:
422
423 /* create a menu button */
424 opsbutton = XtCreateManagedWidget("ops", menuButtonWidgetClass,
425 parent, NULL, 0);
426
427 /* create a menu for the button */
428 opsmenu = XtCreatePopupShell("opsMenu", simpleMenuWidgetClass,
429 opsbutton, NULL, 0);
430 XtSetArg(args[0], XtNmenuName, "fileMenu");
431 XtSetArg(args[1], XtNrightBitmap, rightArrow);
432 filebutton = XtCreateManagedWidget("file", smeBSBObjectClass,
433 opsmenu, args, 2);
434 XtSetArg(args[0], XtNmenuName, "pageMenu");
435 XtSetArg(args[1], XtNrightBitmap, rightArrow);
436 pagebutton = XtCreateManagedWidget("page", smeBSBObjectClass,
437 opsmenu, args, 2);
438 quitbutton = XtCreateManagedWidget("quit", smeBSBObjectClass,
439 opsmenu, NULL, 0);
440
441 /* create a sub-menu for the first menu item */
442 filemenu = XtCreatePopupShell("fileMenu", simpleMenuWidgetClass,
443 opsmenu, NULL, 0);
444 openbutton = XtCreateManagedWidget("open", smeBSBObjectClass,
445 filemenu, NULL, 0);
446 printbutton = XtCreateManagedWidget("print", smeBSBObjectClass,
447 filemenu, NULL, 0);
448
449 /* create a sub-menu for the second menu item */
450 pagemenu = XtCreatePopupShell("pageMenu", simpleMenuWidgetClass,
451 opsmenu, NULL, 0);
452 prevbutton = XtCreateManagedWidget("prev", smeBSBObjectClass,
453 pagemenu, NULL, 0);
454 nextbutton = XtCreateManagedWidget("next", smeBSBObjectClass,
455 pagemenu, NULL, 0);
456
457 The SimpleMenu widget named "opsMenu" will inherit the SimpleMenu
458 widgets named "fileMenu" and "pageMenu" as children sub-menus. It will
459 position the first sub-menu next to the SmeBSB widget named "file",
460 and the second next to the SmeBSB widget named "page". A sub-menu will
461 be mapped (or unmapped) when the pointer enters (or leaves) the
462 superior SmeBSB widget. Note that a sub-menu's parent must be the
463 superior SimpleMenu widget, not the superior SmeBSB widget. The other
464 resources of SmeBSB widgets are unaffected by the menuName resource.
465
466 The Tip widget:
467 ---------------
468
469 This Tip widget is not compatable with XFree86's "Xaw7" Tip widget. I
470 couldn't grok how it links the specified widgets to a Tip widget, nor
471 how their labels are set. Perhaps it's all done with an "Xaw7"
472 DisplayList, I don't know. So, this XawTipEnable() function requires a
473 second parameter, to set the label:
474
475 /* create a menu button */
476 opsbutton = XtCreateManagedWidget("ops", menuButtonWidgetClass,
477 parent, NULL, 0);
478
479 /* add a tooltip */
480 XawTipEnable(opsbutton, "Application functions");
481
482 ...
483
484 /* for some reason, disable the tooltip */
485 XawTipDisable(opsbutton);
486
487 The XawTipEnable() function creates a Tip widget (one per screen, as
488 required), and links the specified widget and label to the correct Tip
489 widget. Nothing else is required of the application; Tip widgets
490 manage themselves. The XawTipDisable() function removes the timeout
491 and event handler, and unmaps the Tip window if necessary, but does
492 not destroy the widget or its linked list.
493
494 Note that the labels of Tip widgets are set individually, but the
495 font, colors, margins, etc., can only be set globally, for all Tip
496 widget instances. For example, a resource file might contain:
497
498 *Tip.font: 7x13bold
499 *Tip.background: yellow
500 *Tip.foreground: blue
501 *Tip.borderColor: blue
502
503 Note also that the *Margin resources of XFree86's "Xaw7" Tip widget
504 are not in this Tip widget; they have been reduced to internalHeight
505 and internalWidth resources, like those of the Label widget.
506 _________________________________________________________________
507
508 Authors and contributors, in alphabetical order:
509 ------------------------------------------------
510
511 Uri Blumenthal <uri@watson.ibm.com>
512 Dimitrios P. Bouras <dbouras@hol.gr>
513 David Flanagan <david@ora.com>
514 D. J. Hawkey Jr. <hawkeyd@visi.com>, current maintainer
515 Achille Hui <eillihca@drizzle.stanford.edu>
516 Kaleb S. Keithley <kaleb@keithley.org>, developed and maintained Xaw3d
517 Alfredo Kojima
518 Gustaf Neumann <neumann@mohegan.wi-inf.uni-essen.de>
519 Keith Packard <keithp@ncd.com>
520 Mark Rawling <mwr@mel.dit.csiro.au>
521 Heiko Schroeder <heiko@pool.informatik.rwth-aachen.de>
522 Mike Schulze <mike@cs.curtin.edu.au>
523 Brian V. Smith <bvsmith@lbl.gov>
524 Malcolm Strickland <chuck-strickland@orl.mmc.com>
525 Frank Terhaar-Yonkers <fty@bizarre.trpnc.epa.gov>
526 Tim Theisen <tim@cs.wisc.edu>
527 Mitch Trachtenberg <mitch@mta.com>
528 Jerry Whelan <guru@stasi.bradley.edu>
529 Robert Withrow <witr@rwwa.com>
530 Jamie Zawinski <jwz@netscape.com>
531
532 And, of course, all the people at X.Org and XFree86.
533
534