The Three-D Athena Toolkit (Xaw3d) ---------------------------------- This is a new release of the Xaw3d toolkit, an update from 1.5E. X.Org has now picked up the mantle of Xaw3d maintenance, previously carried by Xaw3d creator Kaleb Keithley, and then by D. J. Hawkey Jr. While not as insistant as Kaleb was, we do suggest you include this file, as is, with any product that includes Xaw3d, in whole or in part, in any form. This file is the authoritative documentation for Xaw3d. If you're new to the Athena toolkit, please understand that it is highly configurable, and some resources will interact (or not) with undesirable results. Some of these are bugs, but many are just the nature of the beast. _________________________________________________________________ Usage: ------ This release of Xaw3d is based on X.Org's X11R6.3 Athena toolkit, with bits and pieces thrown in from other sources. It is intended to be a general-purpose replacement for the Athena (Xaw) toolkit. In general, you should be able to link almost any Athena-based application to this Xaw3d Athena toolkit, for a three-dimensional appearance on most of the widgets. On systems with shared libraries, you might be able replace your shared libXaw.* with libXaw3d.* to obtain the appearance without even relinking, but the odds of this working is slim, and not recommended. Applications written for Xaw3d might have to test the library for a particular feature (see the "Xaw3d build options" section below). To accommodate this, a private header is installed which reflects the library's capabilities. Xaw3dP.h contains four definitions that may be used for this purpose. For example: #define XAW_INTERNATIONALIZATION #define XAW_MULTIPLANE_PIXMAPS #define XAW_GRAY_BLKWHT_STIPPLES #undef XAW_ARROW_SCROLLBARS Xaw3dP.h need not be included by the application source, as the public headers that reference any 3D features include this header. The default configuration is set up to match the capabilities of X.Org's Xaw toolkit. The use of most shadow resources should be intuitive enough, and may be set or read conventionally (e.g., resource files, editres, programmatically, etc.). The userData resource may be used to "hang" application-specific data on a widget, but this is accessible to programs only. Other resources and less-than-obvious features are documented throughout this file. The default resource values present a not-as-pretty-as-it-could-be appearance, due to stippled shadows (as opposed to allocated colors) in order to conserve colormap space, and by allowing non-rectangular pushbuttons, which are not shadowed. To specify otherwise, set these resources: *beNiceToColormap: False *shapeStyle: Rectangle You might also want to remove the borders from some widgets: *Text.borderWidth: 0 *SimpleMenu.borderWidth: 0 *Paned.internalBorderWidth: 0 To revert to reverse-video highlighting in menus: *SmeBSB.shadowWidth: 0 Note that shadows "grow outward" in the SimpleMenu and Text widgets, increasing these widgets' sizes, "grow inward" in the Viewport and Scrollbar widgets, decreasing the size of the clip widget and thumb, respectively, and "grow inward" in the Label (and superclasses of) and SmeBSB widgets, encroaching on their label parts. Fat shadows will probably mean some futzing with size or margin resources for a proper appearance. _________________________________________________________________ Xaw3d build requirements: ------------------------- Many header files have changed since Release 1.5. This means that any installed Xaw3d headers must be removed before building this distribution, to see that these source files include these header files. Renaming the directory that the existing headers live in is sufficient. Xaw3d build options: -------------------- Like Xaw, the default Xaw3d does not accommodate multi-plane pixmaps. If you want color pixmaps, and have the XPM library installed, pass the --enable-multiplane-bitmaps flag to configure. You may then specify either XPM or XBM files for any Xaw3d bitmap resource, whether by resource files, with editres, programmatically, etc.. And yes, the transparency of XPM files is honored. Note that this enables the use of structures and functions in the XPM library; the XPM library include file (xpm.h) must be available when building Xaw3d, and the XPM library must then be available when running applications that use Xaw3d. This makes Xaw3d dependent on the XPM library, so think twice about it. The default stippled shadows used when the beNiceToColormap resource is True work well enough, except for widgets that have black or white backgrounds. This can be changed by passing the --enable-gray-stipples flag to configure when building. This makes Xaw3d allocate a gray colorcell, and use it in stippled shadows when 1) widgets have black or white backgrounds and 2) the beNiceToColormap resource is True and 3) the display allows it. This option was disabled in previous Xaw3d releases. The default Xaw3d does not use arrow scrollbars. If you want arrow-style scrollbars, pass the --enable-arrow-scrollbars flag to configure when building. Note that the Scrollbar widget's translations and actions will change accordingly. _________________________________________________________________ New in 1.5A: ------------ The SimpleMenu widget now supports scrolling through entries too numerous to fit on the screen, with a new resource supporting a scroll jump value. The record variable is simple_menu.jump_val, resourced as XtNjumpScroll, and classed as XtCJumpScroll. Adapted from an early neXtaw toolkit. Added 3D support to the SimpleMenu, Text, and Viewport widgets. Four minor changes in ThreeD.c and SmeThreeD.c to have the widgets use the app's colormap, rather than the screen's default, for those apps that create their own. Added the deletion of laygram.h to the Imakefile. Created Xaw3dP.c, for functions shared by other modules that have no other appropriate home. A new directory containing sample resource files for a few apps. See the README.AD file in that directory. New in 1.5B: ------------ Made Imakefile a bit more friendly to build options. Makefile now defines the build options in Xaw3dP.h during the build. Added to the key translation tables in Panner.c and TextTr.c, and some rules to Imakefile, to make this distribution X11R5 compliant. Tested on exactly one X11R5 system; your mileage may vary. Made internationalization support conditional, for systems lacking or broken. Tested on exactly two systems, one with and one without; your mileage may vary. New in 1.5C: ------------ Enabled multi-plane pixmap support with a new Xt resource type converter. The "Xaw3d build options" section has more information. Added private Pixmap resources to the Label and SmeBSB widgets for stippled copies of the public Pixmap resources (record variables label.stippled, label.right_stippled, sme_bsb.left_stippled, and sme_bsb.right_stippled, respectively). Insensitive pixmaps are now rendered properly. New in 1.5D: ------------ Added two resources to the SimpleMenu widget for setting margins. The SmeBSB widgets have a tighter relationship with their parent and siblings; menus and their entries now respond properly to changes in themselves or their parent. See the section "The SimpleMenu widget and margins" below for a detailed explanation. New in 1.5E: ------------ Enabled a new resource in the ThreeD widget to specify one of five shadow types. The record variable is threeD.relief (the record part is transparent), resourced as XtNRelief and classed as XtCRelief. It accepts as values XtReliefNone, XtReliefRaised, XtReliefSunken, XtReliefRidge, and XtReliefGroove. Note that the Text, SimpleMenu, Scrollbar, and Viewport widgets ignore this resource, and display only raised or sunken shadows. Built on the unfinished work of an early neXtaw toolkit. Added support for sub-menus in the SimpleMenu widget. Inspired by the xfig application, adapted from XFree86's X11R6.6 "Xaw7" toolkit, and made better than both. See the section "The SimpleMenu widget and sub-menus" below for usage. Added a resource to the SmeBSB widget to specify an underlined character in the label. The record variable is sme_bsb.underline, resourced as XtNunderline, and classed as XtCUnderline. It accepts an integer as an index to the character; a value less than zero or greater than or equal to the label length inhibits underlining. Adapted from a recent distribution of the xfig application. Made the SmeThreeD widget sensitive to the GRAY_BLKWHT_STIPPLES build option (see the "Xaw3d build options" section for what this is and does). Added support for "tooltips". Inspired by the xfig application and adapted from XFree86's X11R6.6 "Xaw7" toolkit. See the section "The Tip widget" below for usage. Fixed some geometry and positioning bugs in the Label widget. It's internalHeight and internalWidth resources are now used to enforce a minimum size when it's resize resource is True. The Label (and superclasses of) widget now resizes properly to changes in label parts and internal margins (subject to any constraints placed on the widgets, of course). Swapped the top and bottom colors in the stippled pixmap shadows. Fixed a shadow drawing bug in the Command widget, when the shape is changed. Fixed the shadow state bug in the SmeBSB widget. Dropped support for Linux shared a.out libraries. _________________________________________________________________ Bugs and deficiencies: ---------------------- You may not be be able to replace shared libXaw.* libraries with libXaw3d.* libraries on systems with SVR3-style shared libraries. The lexer in the Layout widget doesn't work well when a program that uses the Layout widget is linked with GNU's malloc(). This is a problem on older releases of Linux, where the libc malloc() is is GNU malloc(). It's also a problem on older releases of FreeBSD if "ExtraLibraries -lgnumalloc" is specified in imake's FreeBSD.cf configuration file (this may be a problem on other BSDs too, but I don't know this as fact). The solution under FreeBSD is to delete the "ExtraLibraries" line(s) in the vendor.cf configuration file, or edit the Makefile to not link with "-lgnumalloc". I don't have a solution for older Linux distributions, nor do I have the time (or inclination) to figure one out. If you discover a fix, you're more than welcome to send it in. The samples in Layout.h are wrong and don't work. Example programs written by Keith Packard that use the Layout widget are available at ftp://ftp.x.org/R5contrib/. If an application subclasses Athena's Simple or Sme classes, or subclasses thereof, there is a high probability that Xaw3d isn't source compatible. Sorry, I have no plans (or ideas) on how to fix this. Xaw3d pixel allocation may not behave well when beNiceToColormap is False and the colormap (default or application) is full. Non-rectangular Command widgets are not rendered with shadows. All geometry management routines should fully account for shadow widths, but some don't, and it can show. A few bugs and ambiguities in the Athena toolkit from which this distribution is derived have been resolved. While trying to be true to Athena documentation, these changes may make Xaw3d behave oddly for some applications. Nothing that can't be fixed by tweaking the appropriate resources, I'll wager. A comment that appears in the xterm source: ------------------------------------------- * * ...There be serious and nasty dragons here. * xterm is, well, xterm. The auto-scroll with arrow-style scrollbars won't work in xterm because it relies on timeouts. xterm, perhaps for speed, circumvents XtAppNextEvent() by using XNextEvent() to get its X events, with the unfortunate side effect of completely ignoring "other sources", like timeouts. At this time there is no patch to fix the X11R6 xterm, but there is a patch for the X11R5 xterm at ftp://ftp.x.org/contrib/widgets/Xaw3d/R5/; it shouldn't be too hard to integrate it into the X11R6 sources. _________________________________________________________________ The SimpleMenu widget and margins: ---------------------------------- Two resources have been added to the SimpleMenu widget for margin management. The record variables are simple_menu.left_whitespace and simple_menu.right_whitespace, resourced as XtNleftWhitespace and XtNrightWhitespace, and classed as - yup - XtCLeftWhitespace and XtCRightWhitespace. They can be also be referenced together by the class XtCHorizontalWhitespace. To illustrate, the leftMargin resource can be different values in each SmeBSB widget, and SimpleMenu will oblige. If a pixmap wider than the margin is specified in any SmeBSB widget, the result is less than desirable (refer to ORA X, Vol 5 Sec 6, SmeBSB.*Bitmap and SmeBSB.*Margin). Set the leftWhitespace resource in the parent SimpleMenu widget, and SimpleMenu will set all children SmeBSB leftMargins to that value. Specify a pixmap of any width for any SmeBSB child, and SimpleMenu will separate the elements (menu edge, pixmap, and text) of all SmeBSB children with that minimum distance as it vertically aligns their text elements. The SimpleMenu widget now resizes not only to the above, but also to changes in these SmeBSB traits: Labels and fonts, pixmaps, and margins. Implementation notes: The SimpleMenu *Whitespace resources override and replace the values of SmeBSB *Margin resources. To nullify this behavior, a *Whitespace resource must first be set to zero, and the corresponding *Margin resources then set appropriately. The *Margin resources remain unchanged in and of themselves; they behave just as always when the *Whitespace resources are not used. The SimpleMenu widget and sub-menus: ------------------------------------ Resources have been added to the SimpleMenu and SmeBSB widgets to support sub-menus. The record variables are simple_menu.sub_menu and simple_menu.state (neither are public), and sme_bsb.menu_name, which is resourced as XtNmenuName, and classed as XtCMenuName. It's the latter resource that is used by an application, and by default it is NULL; menus behave as they always have. When this resource is set to a menu name, the parent SimpleMenu widget will use the SmeBSB widget as the entry point to a child SimpleMenu widget, managing it's visibility and location. No constraints are placed on focus or the pointer. Consider this code fragment: /* create a menu button */ opsbutton = XtCreateManagedWidget("ops", menuButtonWidgetClass, parent, NULL, 0); /* create a menu for the button */ opsmenu = XtCreatePopupShell("opsMenu", simpleMenuWidgetClass, opsbutton, NULL, 0); XtSetArg(args[0], XtNmenuName, "fileMenu"); XtSetArg(args[1], XtNrightBitmap, rightArrow); filebutton = XtCreateManagedWidget("file", smeBSBObjectClass, opsmenu, args, 2); XtSetArg(args[0], XtNmenuName, "pageMenu"); XtSetArg(args[1], XtNrightBitmap, rightArrow); pagebutton = XtCreateManagedWidget("page", smeBSBObjectClass, opsmenu, args, 2); quitbutton = XtCreateManagedWidget("quit", smeBSBObjectClass, opsmenu, NULL, 0); /* create a sub-menu for the first menu item */ filemenu = XtCreatePopupShell("fileMenu", simpleMenuWidgetClass, opsmenu, NULL, 0); openbutton = XtCreateManagedWidget("open", smeBSBObjectClass, filemenu, NULL, 0); printbutton = XtCreateManagedWidget("print", smeBSBObjectClass, filemenu, NULL, 0); /* create a sub-menu for the second menu item */ pagemenu = XtCreatePopupShell("pageMenu", simpleMenuWidgetClass, opsmenu, NULL, 0); prevbutton = XtCreateManagedWidget("prev", smeBSBObjectClass, pagemenu, NULL, 0); nextbutton = XtCreateManagedWidget("next", smeBSBObjectClass, pagemenu, NULL, 0); The SimpleMenu widget named "opsMenu" will inherit the SimpleMenu widgets named "fileMenu" and "pageMenu" as children sub-menus. It will position the first sub-menu next to the SmeBSB widget named "file", and the second next to the SmeBSB widget named "page". A sub-menu will be mapped (or unmapped) when the pointer enters (or leaves) the superior SmeBSB widget. Note that a sub-menu's parent must be the superior SimpleMenu widget, not the superior SmeBSB widget. The other resources of SmeBSB widgets are unaffected by the menuName resource. The Tip widget: --------------- This Tip widget is not compatible with XFree86's "Xaw7" Tip widget. I couldn't grok how it links the specified widgets to a Tip widget, nor how their labels are set. Perhaps it's all done with an "Xaw7" DisplayList, I don't know. So, this XawTipEnable() function requires a second parameter, to set the label: /* create a menu button */ opsbutton = XtCreateManagedWidget("ops", menuButtonWidgetClass, parent, NULL, 0); /* add a tooltip */ XawTipEnable(opsbutton, "Application functions"); ... /* for some reason, disable the tooltip */ XawTipDisable(opsbutton); The XawTipEnable() function creates a Tip widget (one per screen, as required), and links the specified widget and label to the correct Tip widget. Nothing else is required of the application; Tip widgets manage themselves. The XawTipDisable() function removes the timeout and event handler, and unmaps the Tip window if necessary, but does not destroy the widget or its linked list. Note that the labels of Tip widgets are set individually, but the font, colors, margins, etc., can only be set globally, for all Tip widget instances. For example, a resource file might contain: *Tip.font: 7x13bold *Tip.background: yellow *Tip.foreground: blue *Tip.borderColor: blue Note also that the *Margin resources of XFree86's "Xaw7" Tip widget are not in this Tip widget; they have been reduced to internalHeight and internalWidth resources, like those of the Label widget. _________________________________________________________________ Authors and contributors, in alphabetical order: ------------------------------------------------ Uri Blumenthal Dimitrios P. Bouras David Flanagan D. J. Hawkey Jr. , current maintainer Achille Hui Kaleb S. Keithley , developed and maintained Xaw3d Alfredo Kojima Gustaf Neumann Keith Packard Mark Rawling Heiko Schroeder Mike Schulze Brian V. Smith Malcolm Strickland Frank Terhaar-Yonkers Tim Theisen Mitch Trachtenberg Jerry Whelan Robert Withrow Jamie Zawinski And, of course, all the people at X.Org and XFree86.