Created:  December 20, 1991
Updated:  December 21, 1992

1.  Introduction and Background

This package includes a Mahjongg solitaire game for both XView/X11
and SunView.  I developed the XView version in the 8/91 to
9/91 time frame, using XView 2.0, with some clean-up and
XView 3.0/OpenWindows 3.0 testing and compatibility work done
in 12/91.   A small code change was made in 12/92.
     The XView version was ported from the SunView version, which
was originally developed in 1988 by Mark A. Holm (and others).
The XView version supports the same multi-colored icons and game
playing interface as the SunView version.  Also, the XView source
code re-uses a fair amount of code from the SunView version.
     Minor changes were made to the SunView code distributed in
this package so that both sets of code could share all the icon
files, and one of the source files.  The icon files had to be
patched as well, since there were extraneous bits set that had
no effect under SunView but did cause problems under XView.
I also implemented a compression scheme for the icon files,
to significantly reduce the size of the source package for
distribution purposes.

There is another X11 compatible version of Mahjongg, the xmahjongg
program by Jeff S. Young, which was available as early as June 1989,
and probably earlier, although I first came across it in Sept. 90.
This version is also derived from Mark A. Holm's program, although
perhaps only the monochrome icons were re-used.  Xmahjongg has several
new features unique to it, including the ability to define different
board layouts.
     However, that program does not support the multi-colored icons,
nor the game playing interface of SunView Mahjongg, which includes
the ability to cancel a move and also to undo moves.  I felt that
these were some of the best features of the original Mahjongg game,
and used this as motivation to port the program to XView.  This was
pursued mainly as a learning exercise, as I am a novice-level
XView programmer.  I wasn't sure how successful I'd be when I
started, but now that it's finished, might as well make it public.

2.  The XView Version Source Code -- Tips and Tricks

The XView version of mahjongg was derived from the SunView source
with an assist from the SunView to XView conversion program that
Sun provides with both OpenWindows and the XView toolkit package.
Although most of the code converted had to be changed in some
way, it still provided a good starting point.

The trickiest part of the port was in making an XView canvas
act the same way as a SunView panel.  SunView mahjongg used
a panel and PANEL_BUTTON's with PANEL_LABEL_IMAGE's for the game
tiles.  This was not going to work under XView because XView
wraps a 3D button image around image buttons.  So I used a canvas
and via event handlers and color map tricks and pixwin calls,
was able to make it behave as in SunView mahjongg.  Implementing
the high-lighting of tiles in XView was the toughest part.

The final source code has a fair number of lines that were
essentially unchanged from the SunView version.  I purposely
avoided editing or re-formatting this code in most cases.
This is mentioned only because if you look at the code you will
find some strange-looking indentation and spacing sometimes.
I always try to be consistent in my coding style, but my style
differs somewhat from the prior author's style.

Two XView features were used that are undocumented,
although they work fine in both XView 2.0 and 3.0
(and OpenWindows 2.0 and 3.0).  Nevertheless, they may or may
not be supported in future versions of XView.
The two features were used to implement two different methods
of inverting colors on the game tiles.  Both methods are
supplied because one provides a fallback method for the other,
and also because certain X server environments might need to
use one method rather than the other.  The two methods are
selectable via command-line options.
    The two undocumented features are:
(1) the use of the xv_destroy_status() routine, which is
    similar in spirit to the documented xv_destroy() routine
(2) the modifying of an internal XView data structure, as
    shown by the declaration:
	extern struct pixrectops mem_ops;
    Access to this struct allowed me to install a routine to
    enable pw_read() to work.

See the code for more details on the use of these undocumented
features.

3.  Copyrights and Disclaimers

Mark A. Holm, the author of the original 1988 SunView version, has
a copyright on the icons and the SunView source code.  Some of the
code in the XView version comes straight from the SunView version,
so that code is covered by Mark A. Holm's copyright as well.
I might as well claim a copyright on the rest of the code in the
XView version.  The common and new code can be determined by
running a diff comparison between the old and the new code.  Since
Mark A. Holm distributed the original code under the following policy:

    Permission is given to copy and distribute for non-profit purposes.

by rights the new XView version should (and will) maintain this policy.
So you can't sell this program, but you can give it away freely.

Neither I nor my employer warrant or guarantee
the fitness, functionality or suitability of this software for any
purpose, nor shall we be held liable for any damages, reprimands
or job losses that may result from the use of the program, or from
re-use of source code or documentation contained within.


			Stanley Ken Tazuma
			Boeing Computer Services, a division of
			The Boeing Company

			skt@sundry.boeing.com
			uw-beaver!bcsaic!sundry!skt
