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