Move sources to src/.

Signed-off-by: Matt Turner <mattst88@gmail.com>

1 files changed, 544 insertions, 0 deletions

diff --git a/src/README.XAW3D b/src/README.XAW3D
new file mode 100644
index 0000000..f77be1b
--- /dev/null
+++ b/src/README.XAW3D
@@ -0,0 +1,544 @@
+
+   The Three-D Athena Toolkit (Xaw3d)
+   ----------------------------------
+
+   This is Release 1.5E of the Xaw3d toolkit (dated March 8, 2003), an
+   update that fixes some bugs, and adds many features. There were no
+   public releases of 1.5A through 1.5D.
+
+   I am not Kaleb Keithley. Kaleb has moved on, and no longer supports
+   Xaw3d; it's my baby now. This distribution is not a fork - it is the
+   latest update of the One True Xaw3d.
+
+   While not as insistant as Kaleb was, I 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 discover bugs not already known, do not contact Kaleb; he's had
+   no part in this effort. Feel free to contact me; I'll try to respond
+   in kind. If you're new to the Athena toolkit, 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.
+
+   D. J. Hawkey Jr.
+     _________________________________________________________________
+
+   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
+   accomodate 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,
+   programatically, etc.). The userData resource may be used to "hang"
+   application-specific data on a widget, but this is accessable 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 accomodate multi-plane pixmaps.
+   However, at the top of this distribution's Imakefile are the lines:
+
+       XCOMM For color pixmaps, define MULTIPLANE_PIXMAPS:
+       #undef MULTIPLANE_PIXMAPS
+
+   If you want color pixmaps, and have Arnaud Le Hors's XPM library
+   installed, change the "#undef" to "#define". 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 linked to any and all
+   applications that use Xaw3d. This makes Xaw3d dependant 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. So, at the top of this distribution's Imakefile, are the
+   lines:
+
+       XCOMM For grayed stipple shadows, define GRAY_BLKWHT_STIPPLES:
+       #define GRAY_BLKWHT_STIPPLES
+
+   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. At the top of this
+   distribution's Imakefile are the lines:
+
+       XCOMM For scrollbars with arrows, define ARROW_SCROLLBARS:
+       #undef ARROW_SCROLLBARS
+
+   If you want arrow-style scrollbars, change the "#undef" to "#define".
+   Note that the Scrollbar widget's translations and actions will change
+   accordingly.
+
+   Building Xaw3d within an X11 source tree:
+   -----------------------------------------
+
+   This distribution expects a configured X11R6.[1-6] source tree (by
+   "configured", I mean that the imake infrastructure has been built).
+   You can use the source from X.Org, XFree86, or the X Project Team.
+
+   Change to the directory containing /xc, and issue these commands:
+
+       # gunzip -c Xaw3d-1.5E.tar.gz | tar -xpf -
+       # cd xc/lib/Xaw3d
+       # ../../config/imake/imake -I../../config/cf \
+         -DTOPDIR=../.. -DCURDIR=lib/Xaw3d
+       # make includes; make depend; make; make install
+
+   The Imakefile uses the Xaw symbols in /xc/config/cf, so if you have
+   debug, shared, profile, etc. libraries specified for Xaw, Xaw3d will
+   have them as well.
+
+   Building Xaw3d without an X11 source tree:
+   ------------------------------------------
+
+   Near the top of this distribution's Imakefile are the lines:
+
+       XCOMM When building outside an X11 source tree:
+       XCOMM EXTRA_INCLUDES = -I.
+
+   Uncomment the second line by deleting the "XCOMM ". Then, while still
+   in /xc/lib/Xaw3d, issue these commands:
+
+       # mkdir X11; cd X11; ln -fs .. Xaw3d; cd ..
+       # xmkmf; make depend; make; make install
+
+   If this works for you, great. If not, well, happy hacking.
+
+   Building Xaw3d under X11R5:
+   ---------------------------
+
+   I don't know that Xaw3d will build within an X11R5 source tree, so try
+   the "Building Xaw3d without an X11 source tree" instructions. If the
+   "make" command results in nothing being built, find these lines about
+   half-way into this distribution's Imakefile:
+
+       XCOMM At least one X11R5 distribution needs this:
+       XCOMM #include "Imakefrag.X11R5"
+
+   Uncomment the second line by deleting the "XCOMM ", and re-issue the
+   "xmkmf; make depend; make; make install" commands. This line will
+   insert the quoted file into the Makefile, and is for when the imake
+   configuration files don't create the appropriate rules.
+
+   Xaw3d and Internationalization:
+   -------------------------------
+
+   The Imakefile depends on a conventional system-wide definition for
+   including or omitting I18n support (i.e., "XawI18nDefines"). If the
+   Imakefile erroneously disables support for I18n (see the generated
+   Xaw3dP.h file), I can only suggest searching your imake configuration
+   files for a definition that enables support for "wide characters" (try
+   `egrep 'WCHAR|WCTYPE|XMBTOWC|ISW_FUNCS' *`), and then, about half-way
+   into this distribution's Imakefile, find these lines:
+
+       #ifdef XawI18nDefines
+       #define INTERNATIONALIZATION
+       HEADERS = $(BASE_HDRS) $(I18N_HDRS)
+       SRCS = $(BASE_SRCS) $(I18N_SRCS)
+       OBJS = $(BASE_OBJS) $(I18N_OBJS)
+       ...
+
+   Change the label in the first line to the label of the definition you
+   found. If no suitable definition is found, and I18n really is
+   supported, it's likely implemented in such a way that Xaw3d probably
+   won't include I18n support without some hacking at the Imakefile or
+   Makefile.
+     _________________________________________________________________
+
+   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 compatable 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 <uri@watson.ibm.com>
+   Dimitrios P. Bouras <dbouras@hol.gr>
+   David Flanagan <david@ora.com>
+   D. J. Hawkey Jr. <hawkeyd@visi.com>, current maintainer
+   Achille Hui <eillihca@drizzle.stanford.edu>
+   Kaleb S. Keithley <kaleb@keithley.org>, developed and maintained Xaw3d
+   Alfredo Kojima
+   Gustaf Neumann <neumann@mohegan.wi-inf.uni-essen.de>
+   Keith Packard <keithp@ncd.com>
+   Mark Rawling <mwr@mel.dit.csiro.au>
+   Heiko Schroeder <heiko@pool.informatik.rwth-aachen.de>
+   Mike Schulze <mike@cs.curtin.edu.au>
+   Brian V. Smith <bvsmith@lbl.gov>
+   Malcolm Strickland <chuck-strickland@orl.mmc.com>
+   Frank Terhaar-Yonkers <fty@bizarre.trpnc.epa.gov>
+   Tim Theisen <tim@cs.wisc.edu>
+   Mitch Trachtenberg <mitch@mta.com>
+   Jerry Whelan <guru@stasi.bradley.edu>
+   Robert Withrow <witr@rwwa.com>
+   Jamie Zawinski <jwz@netscape.com>
+
+   And, of course, all the people at X.Org and XFree86.
+