
                   Three-D Athena Widgets (Xaw3d)
                          Kaleb S. KEITHLEY
                             kaleb@x.org

Features:

  This is Release 1.1 (30 March, 1995) of a set of 3-D widgets based on the 
  R6 Athena Widget set.  The Three-D Athena may be used as a general 
  replacement for the Athena (Xaw) Widget set.

  In general, you may relink almost any Athena Widget based application with 
  the Three-D Athena Widget set and obtain a three dimensional appearance on
  some of the widgets. On systems with shared libraries, you may be able to
  replace your shared libXaw with libXaw3d and obtain the three dimensional 
  appearance without even relinking.

  Top and bottom shadow colors, shadow width, top and bottom shadow contrast
  should be self explanatory, and may be set via the usual and customary 
  methods, e.g. app-defaults, .Xdefaults, programmatically, with editres, 
  etc.  The user data resource may be used to "hang" application specific 
  data on a widget, and is only settable programmatically.


The following changes were made in this release:

    o Addition of jump_funcs, jump_ignore, and jump_vars files and
      support in the Imakefile for building shared libraries on Linux.

    o Many minor bug fixes.


Known problems:

    o You may not be be able to replace shared libXaw with libXaw3d on 
      systems with SVR3 style shared libraries.

    o Xaw3d pixel allocation doesn't behave well when beNiceToColormap
      is False and the Default Colormap is full.

    o The samples in Layout.h are wrong and don't work.  Example programs
      written by Keith Packard that use the Layout widget are available
      on export in /R5contrib/Layout.tar.Z

    o If you subclass Athena's Simple or Sme classes, or subclasses
      thereof, then there's a definite chance that Xaw3d isn't source 
      code compatible with your widgets. Sorry. I have no plans to fix 
      this.

    o laylex.l is not compatible with flex because it redefines input().
      The laylex.c file that comes with the distribution should work
      fine with most ANSI C compilers. If you're building on a machine
      without an ANSI C compile, e.g. SunOS 4 with the bundled compiler
      then remove laylex.c and type 'make laylex.c' to create a new
      one suitable for your system.


Comments:

    o Linux. I don't have much to say about Linux except to wonder why
      you aren't using FreeBSD instead. Building shared libraries on 
      Linux is harder than it ought to be. Some day Linux will use the 
      ELF object file format and then it will be easier, but until then 
      you had either better know what you're doing, or be satisfied to 
      use libraries built by someone who does know what they're doing.

      In what is perhaps typical Linux style, there seem to be several 
      variations and non-official versions of Xaw3d with enhancements and 
      bug fixes of dubious or unknown quality, and little or no information 
      about how to contact the person who built the libraries. All this 
      leads to is confusion among users and frustration when programs 
      don't work or dump core when they're linked against these libraries. 
      There's only one official version of Xaw3d source, and that's the 
      one on ftp.x.org and its mirrors. I don't mind that people fix bugs 
      or make enhancements for their own use, that's what freely 
      redistributable source is all about, but if you do that, it's no 
      longer Xaw3d. Name the sources and libraries you distribute something 
      else.

    o The source is really (really really really) intended to be built
      in an R6 source tree. You might be able to build it outside the
      source tree, but if you try, you're on your own. It's hard enough
      to find time to put out these releases, I don't have time for
      handholding if you choose to disregard this advice. If you don't 
      have a source tree, for whatever reason, plan on using binaries 
      built by someone else. I'm sorry, that's just the way it has to be. 

    o Many people have written to me with enhancements and bug fixes.
      If your enhancement or bug fix didn't make it into this release
      then please understand that I'm very busy with other work and I 
      have very little time to devote to Xaw3d. Your enhancement may 
      appear in some future release. Again, I'm sorry, but that's just 
      the way it has to be.


xterm:

      A comment that appears in the xterm source:
         *
         * ...There be serious and nasty dragons here.
         *

      xterm is, well, xterm.  The auto-scroll in the arrow-style scrollbar 
      doesn't work in xterm because it relies on XtTimeouts.  xterm, perhaps 
      in the name of speed, circumvents XtAppNextEvent() and goes direct to 
      XNextEvent() to get it's XEvents, with the unfortunate side effect of 
      completely ignoring "other sources" like timeouts.  At this time I
      do not have a patch to fix the R6 xterm. There is a patch to the R5 
      xterm on ftp://ftp.x.org/contrib/widgets/Xaw3d/R5. It shouldn't be 
      hard to integrate it into the R6 sources.


Getting:

  Xaw3d may be found on:

    ftp://ftp.x.org/contrib/widgets/Xaw3d/R6/Xaw3d-1.1.tar.gz

  and mirror sites around the world. 


Building:  

  Untar the distribution from the base of your X Consortium source tree
  with the command:

    'gunzip -c Xaw3d-1.1.tar.gz | tar xpf -'

  This will create the directory .../xc/lib/Xaw3d.  'cd' there and..

  If building on SunOS 4 with the bundled compiler or any other machine
  with a non-ANSI C compiler:

    'rm laylex.c; make laylex.c'  Proceed to the next step...

  Otherwise just enter the following commands:

    'make Makefile; make includes; make depend; make; make install'.  

  The Imakefile contains the line:

#    EXTRA_DEFINES = -DARROW_SCROLLBAR

  If you want the arrow-scrollbar, then uncomment the line by deleting the '#'.

  The Imakefile uses the Xaw symbols in .../xc/config/cf, so if you have 
  debugging, profiling, shared libs, etc. specified for Xaw, you'll get 
  them in Xaw3d too.


Using:

  Just relink your Xaw based application with -lXaw3d.

  To obtain an appearance similar to another well know widget set, use the 
  following resources:
    *background:        LightSkyBlue
    *shapeStyle:        Rectangle
    *beNiceToColormap:  False

  By default, Label widgets do not have shadows drawn for them.  You can
  force shadows to be drawn for specifying:
    *Label*shadowWidth: 2

  If you'd like the default behavior (i.e. not 3-D) on pulldown menus, use:
    *SmeBSB*shadowWidth: 0


  Credits (in chronological order of their contribution):

          All the people at the X Consortium

          Achille Hui (eillihca@drizzle.stanford.edu)
          Robert Withrow (witr@rwwa.com)
          Malcolm Strickland (chuck-strickland@orl.mmc.com
          David Flanagan (david@ora.com)
          Jamie Zawinski (jwz%thalidomide@lucid.com
          Frank Terhaar-Yonkers (fty@bizarre.trpnc.epa.gov)
          Mike Schulze (mike@cs.curtin.edu.au)
          Gustaf Neumann (neumann@dec4.wu-wien.ac.at)
          Jerry Whelan (guru@stasi.bradley.edu)
          Mark Rawling (mwr@mel.dit.csiro.au)
          Tim Theisen (tim@cs.wisc.edu)
          Mitch Trachtenberg (mitch@mta.com)
          Keith Packard (keithp@ncd.com)
          Dimitri P. Bouras (dimitri@ee.ubc.ca)

