December 20, 1991

1.  Introduction and Background

This package includes a Mahjongg solitaire game for both XView/X11
and SunView.  The XView version was developed 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.
     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.  I also
pursued this 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 Source Code -- Tips and Tricks

The XView source code 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.
I mention this 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.

There are two XView features I used which 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--I have no idea
at this point, but I plan to ask.  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

    (Some of this is meant primarily for any fellow employees of
    The Boeing Company who might be reading this.  If after reading
    it you think I'm a little paranoid, well, maybe it's because
    you haven't worked for a big company 8-).)

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.


(This is not official legalese, it's just off the top of my head...)
Neither I nor my employer, The Boeing Company, 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.

As the playing of computer games on company equipment is strictly
against Boeing Company policy, I feel it necessary to state for the
record that in developing and distributing this software that I
neither endorse nor encourage the playing of this game, especially
on Boeing Company equipment.
     If I used company time (most of it was done in my spare time)
or equipment during development of this program, it was with the
primary goal of gaining new knowledge and experience in the
building of applications employing graphical user interfaces.
Because what I learned in doing this work is directly applicable
to future non-game-related programs that I may build, I believe
the positives to the Boeing Company, in terms of my improved skills,
vastly outweigh the negatives that I may have incurred or caused
by building and/or using this software.


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

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