__  __                 __  __
\ \/ /__ ___      __   \ \/ /_ __  _ __ ___
 \  // _` \ \ /\ / /____\  /| '_ \| '_ ` _ \
 /  \ (_| |\ V  V /_____/  \| |_) | | | | | |
/_/\_\__,_| \_/\_/     /_/\_\ .__/|_| |_| |_| (v1.1)
                            |_|(Hacked by Ben Buxton <bb@zip.com.au>)

(The Xaw-XPM web page is at http://www.zip.com.au/~bb/XawXpm/ - check here
for updates, bug fixes, sample configs, etc)

Xaw-xpm is a hack on Xaw3d, which is in turn based on the 'standard' X11 Xaw
widget set. It adds the ability to insert colour images into the backgrounds
of widgets, vastly improving the look of your Xaw apps. Just put the library
(libXaw.so.6.0) in place of your current one (usually /usr/X11R6/lib on Linux
systems) and customise away with editres, etc.

IF YOU DONT INSTALL THE INCLUDE FILES, APPS YOU COMPILE WILL DUMP CORE!
You should also install them if you plan to compile XawXpm without
using the supplied Makefile.

It uses an efficient linked list algorithm whereby each xpm file is loaded only
once. This saves *masses* of memory and time when setting the background for
many widgets. Setting XPMs via editres works for all new resources.

NOTE - I *strongly* recommend that you have a 16-bit display if you
use the pixmaps feature, as you may run out of colours on an 8-bit display.

NEW SINCE v1.0b

- Added many more new resources, including sound. Below is a complete list.
- Sounds are implemented using direct system calls and forking to pipe to
  /dev/audio. This saves time and memory over system().
- Better handling in 8-bit mode. If you run out of colours, it will use 
  the nearest available colour instead.
- Label, Command, Toggle widgets can be **shaped** :)
- Fixed a bug that caused core dumps unless setPixmap was defined for
  all widgets.
- 3d borders around SimpleMenu widget. The subwidget for this is 'threeD' if
  you want to set and resources for it. Also 3d SmeLine (lineWidth should
  be a multiple of 2 for this to look good - default is 2)
- Widget defaults are much more sensible. :)
- Amiga/neXt style scrollbar (can be disabled with resources ; see below)
- Scrollbars can be removed with resources.
- Better look and feel to some widgets. Eg Motif style arm shadow for Command,
  Toggle, text displaces when pressed, others as well.
- Text widget over-scrolling 'bug' fixed.
- Compile problems fixed up a bit. Some apps that were rejecting the lib
  should now work.
- Other changes I can't remember. :)

The following extra resources have been added:
-------------------------------------------------------------------------------
Resource:       pixmapName
Description:    Filename of xpm to be used for 'normal' background of widget.
Used in:        Command, Label, Toggle, Simple, Text, Scrollbar, Panner, Tree,
		SimpleMenu, MenuButton, Form, Box (ie just about every widget :)

Resource:       setPixmap
Description:    Filename of xpm to be used for 'set' state of widget.
Used in:	Command, Toggle.

Resource:       hlPixmap
Description:    Filename of xpm used for 'highlight' state of widget, ie
                when the pointer is moved over the widget.
Used in:        Command, Toggle, MenuButton, others based on Command.

Resource:	thumbPixmap
Description:	xpm to be used for the thumb (slider) of scrollbars.
Used in:	Scrollbar

Resource:	sliderPixmap
Description:    Filename of xpm to be used for the foreground slider of a Panner
		widget.
Used in:	Panner
--------------------------------New since 1.0b----------------------------
Resource:	pixDir
Description:	Specifies a directory to be searched when loading pixmaps
		in all pixmap resources. Current directory is searched first,
		then the one specified here.

Resource:	doubleArrow
Description:	Whether to use an Amiga/neXt style double-arrow scrollbar
Used in:	Scrollbar
Default:	True

Resource:	thumbMargin
Description:	Margin distance between thumb and scrollbar shadows
Used in:	Scrollbar
Default:	1

Resource:	showSliderMark
Description:	Whether to show a 3d grip on the slider (thumb)
Used in:	Scrollbar
Default:	True

Description:	notifySound
Description:	Filename of .au file to play when button has been pressed
		and released.
Used in:	Command, Toggle, Repeater, SmeBSB (menu entry)

Resource:	armSound
Description:	Filename of .au file to play when button has been armed
		(pressed)
Used in:	Command, Toggle

Resource:	hlSound
Description:	Filename of .au file to play when pointer is over the
		widget.
Used in:	Command, Toggle, MenuButton

Resource:	drawTextBorder
Description:	Whether to draw a 1 pixel wide border around widget
		text.
Used in:	Command, Label, List, Toggle, Repeater, SmeBSB
Default:	False

Resource:	textBorder
Description:	Colour of above-mentioned text border
Used in:	Same as drawTextBorder
Default:	Widget background

Resource:	shaped
Description:	Whether to shape the widget.
Used in:	Label, Toggle, Repeater, Command
Default:	False

Resource:	shapeMask
Description:	Filename of .xpm file used to shape the widget (if enabled
		as above). If unspecified and 'shaped' is True, 'pixmapName'
		is used to determine shape.
Used in:	Same as 'shaped'.
Default:	xpm specified in pixmapName

Resource:	downSound
Description:	Filename of .au file played when menu pops down (ie goes
		away).
Used in:	SimpleMenu

Resource:	upSound
Description:	Filename of .au file to play when menu pops up.
Used in:	SimpleMenu

Resource:	showGroove
Description:	Whether to show a groove down the trough of a scrollbar.
Used in:	Scrollbar
Default:	True

Resource:	showArrows
Description:	Whether to show scrollbar arrows
Used in:	Scrollbar
Default:	True

Resource:	ridgeShadow
Description:	Whether to display the widget shadow as a 'ridge' or
		'groove' (depending on 'invertBorder' setting).
Used in:	Scrollbar, Command, Label, Toggle, etc
Default:	False

Resource:	armPixel
Description:	Colour to use for background of a 'pressed' button.
Used in:	Command, Toggle, etc
Default:	Halfway between normal background and top shadow (ie
		similar to Motif).

-------------------------------------------------------------------------------
(All pixmaps are automagically tiled where necessary)

Known problems/annoyances (ie dont email me about them :)

- Horizontal scrolling of text flickers. This is because I dont use 
  XCopyAreas for text scrolling (as I want it to preserve the background), 
  but rather just redraws. Vertical scrolling is completely smooth, however.
- Apps that create their own composite widgets at compile time *might*
  dump core when you run them. The solution is to recompile/link them with
  XawXpm. Programs affected include xterm, xarchie, xxgdb, xman. 
  Interestingly, whether or not they core dump depends on the resources you've
  set.
- If a program fails to recognise the library, try making a symlink from
  /usr/lib/libXaw.so.6 to the binary. This seems to work.

TODO:
- Free the pixmaps when they are no longer required. This would need a reliable 
  way of catching all widgets being destroyed (Destroy callback is unreliable..
  any ideas?).
- Separate pixmaps for individual (or highlighted) menu entries.
- ThreeD text widget.

Look at the sample Xdefaults file for hints/examples. The sample resources
and pixmaps are *NOT* 8-bit friendly!


Thanks to Rasterman (raster@zip.com.au) for extensive testing, pixmaps and
ideas. Go get his awesome Enlightenment window manager now!

Xaw-XPM, version 1.1 (28 Nov 1996)
Ben Buxton (bb@zip.com.au)
