        Frequently Asked Questions about the XbaeMatrix Widget
        ------------------------------------------------------

1. General Information.
    1.1 What is the XbaeMatrix Widget?
    1.2 Who wrote the XbaeMatrix Widget?
    1.3 Where do I get it?
    1.4 What are the terms of usage of the XbaeMatrix Widget?
    1.5 Where can I find out more?
    1.6 If I have questions, who should I ask?
    1.7 Where do I mail suggestions/comments for this FAQ?
    1.8 Aaargh, I found a bug - what do I do?
    1.9 Does the XbaeMatrix Widget have a home page?
    1.10 I love it!  How can I contribute?

2. Programming Questions.
    2.0 How do I change the behavior of the XbaeMatrix so that.... ?
    2.1 How do I make a cell non-editable?
    2.2 Can I display 2-byte characters (e.g. kanji)?
    2.3 How do I stop the matrix from scrolling back to the selected cell?
    2.4 How do I stop the matrix from flickering when it redraws? 
    2.5 Can I resize the row height in my matrix?
    2.6 How do I make the matrix emulate a list?
    2.7 Can I change the behaviour of the text field in the matrix?
    2.8 How can I edit a cell in a fixed column or fixed row?
    2.9 Can I select a fixed row or column?
    2.10 How do I select a row or column without the text field being visible?
    2.11 How do I redraw just a single cell?

--------------------------------------------------------------------------
Answers to Frequently Asked Questions about the XbaeMatrix Widget.

1.1 What is the XbaeMatrix Widget?

The XbaeMatrix is a Motif-based widget which displays a grid of cells
in the same manner as a spreadsheet.  The cell array is scrollable,
editable, and otherwise reasonably configurable in appearance. Each
cell usually displays text, but pixmaps can also be displayed (not
editeable). The XbaeMatrix looks to some extent like a grid of
XmTextField widgets, but is actually implemented with a single
XmTextField. This means a big performance improvement due to less
overhead.

1.2 Who wrote the XbaeMatrix Widget?

The Matrix was originally developed by Andrew Wason of Bellcore. It
was subsequently released on the 'net (version 3.5 seems to be the
first) and the last version from Andrew Wason was version 3.8. Kevin
Brannen became the maintainer briefly and released version 4.0 of the
widget (then seemed to lose his net connection).  Since then Andrew
Lister has been the maintainer of the widget and has contributed many
changes as well as integrating changes contributed by many other
people.  People who have contributed code to XbaeMatrix include:

Philip Aston	(philipa@parallax.co.uk)
Tim Bomgardner	(timbo@apdev.cs.mci.com)
Kevin Brannen	(kbrannen@metronet.com)
Eric Bruno	(bruno@nsipo.arc.nasa.gov)
Matthew Francey	(mdf@angoss.com)
Martin Helmling (mh@c3i.sel.de)
Callum Gibson	(callum.gibson@aus.deuba.com)
Alexander Ivanov(avi@elais.physics.ox.ac.uk)
Adam Kerrison	(adam@micromuse.co.uk)
Vince Li	(vli@mpr.ca)
Andrew Lister	(lister@syd.net.au)
Earl Revett	(erevett@kokomo.bmc.com)
Jay Schmidgall	(jay.schmidgall@spdbump.sungardss.com)
Jason Smith	(js81736@internet.sbi.com)
Mark Steckel	(msteckel@aracada.com)
Daiji Takamori	(daijit@std.teradyne.com)
Dirk Vangestel	(gesteld@sebb.bel.alcatel.be)
Andy Warburton  (andyw@parallax.co.uk)
Andrew Wason	(aw@bae.bellcore.com)
Neil Weber	(neilw@pyramid.com)
D. Craig Wilson (cwilson@mpr.ca)
Q. Frank Xia	(qx@math.columbia.edu)

Sorry, if you have been left out - it was not intentional.

1.3 Where do I get it?

The XbaeMatrix is up for ftp from heaps of different sites around the
world.  The official distribution point is ftp.x.org in
/contrib/widgets/motif. Look on a site nearby, though, or use archie,
gopher, etc to find it.

1.4 What are the terms of usage of the XbaeMatrix Widget?

The LICENSE file describes the terms an conditions but if you (like me)
have trouble understanding legalese here it is in English:

1. Nobody promises that this software works.

2. You can use this software for whatever you want.

3. You may not pretend that you wrote this software.

4. If you use it in a commercial program, you have to acknowledge that
   you've used the Xbae code in your documentation and include the
   copyright notice in the LICENSE file of the distribution being used.

1.5 Where can I find out more?

Join the Xbae mailing list by sending mail to
xbae-request@emjay.apana.org.au with "subscribe" in the Subject:
field. The list is populated with many developers using the XbaeMatrix
widget and contains discussions regarding its use, new or desired
features, upcoming releases, etc.

1.6  If I have questions, who should I ask?

The best way to ask questions is via the mailing list.  If you have
any abject excuse as to being a part of a mailing list then send mail
to the maintainer (lister@syd.net.au).

1.7 Where do I mail suggestions/comments for this FAQ?

If you ask or answer a question on the mailing list, you may find it
is incorporated into the FAQ. Other general comments or suggestions
can be mailed to the maintainer directly

1.8 Aaargh, I found a bug - what do I do?

Send mail to the maintainer or to the mailing list
if you are unsure whether it is a *real* bug or if it may have been
discovered before.  Please include details as to the version you are
using, the circumstances under which the problem occurred and (if you're
really keen) a patch.

1.9 Does the XbaeMatrix Widget have a home page?

At present, no.  But I'm working on it.

1.10 I love it!  How can I contribute?

Send the maintainer a postcard from wherever you are and get your name
in the manual page.  Submitting patches and suggestions enable your
own special place in the README file.  Worthy contributions get a
place in the SPECIAL THANKS section of the manual page along with
other celebrities such as Bill Gates (if you want to be placed as far
away as possible, it can be arranged).

---------------------------------------------------------------------------

2.0 How do I change the behavior of the XbaeMatrix so that.... ?

You might want to read the section on Translations and Action
Routines...  It describes how to modify many parts of the XbaeMatrix
behavior. You also might take a look at the various examples' resource
files; some have special translations that are useful. This is useful
for:
	- changing when the TextField widget is mapped/unmapped;
	- changing how selections/edits are performed;
	- changing how cursor movement is performed;
	- changing when edits are allowed;
	- installing select-drag behavior;
	- installing interactive column resize;
	- installing drag-n-drop-related callbacks.

If you want to change the reaction to various actions (as in Action
routines), several are affected by the behavior of the various
callbacks associated with the XbaeMatrix.  These reactions would
include:
	- making a cell read only; 
	- having the data be looked up by a function rather than
	  stored in the XmNcells resource;
	- confirming that cell edits should be accepted using a
	  function;
	- confirming that cell modifications should be accepted using
	  a function;
	- changing column widths when the entire matrix is resized;
	- changing what is selected when a cell is selected;
	- changing how traversals are made.

[ supplied by (Daiji Takamori) daijit@std.teradyne.com ]

Although more specific answers to changing widget behaviour follow,
some may not be covered by this FAQ. In this case, it is important to
follow the advice above and carefully read the manpage. More than
likely the answer is in there.

2.1 How do I make a cell non-editable?

To make a cell non editable you need to install an
XmNenterCellCallback.  In the callback, you should set the doit member
of the callback struct to False.  For example:

void
enterCB( Widget w, XtPointer cd, XtPointer cb )
{
    XbaeMatrixEnterCellCallbackStruct *cbs =
        ( XbaeMatrixEnterCellCallbackStruct * )cb;

    switch( cbs->column )
    {
    case 2:
	/*
	 * Make all of column 2 non editable except for row 4
	 */
	if( cbs->row != 4 )
	    cbs->doit = False;
	break;
    default:
	cbs->doit = True;	/* Default behaviour */
	break;
    }
}

It really is as easy as that!

2.2 Can I display 2-byte characters (e.g. kanji)?

Technically no.  The code currently exists in the widget to achieve
*some* of the steps to display 2-byte characters but is incomplete in
the respect that a two byte character string is represented as a
wchar_t *.  Anybody who uses two byte charaters and is willing to come
up with an effective patch is hereby granted the opportunity!

2.3 How do I stop the matrix from scrolling back to the selected cell?

Use XmNselectScrollVisible.  Setting this to False should prevent
any non desirable scrolling.

2.4 How do I stop the matrix from flickering when it redraws? 

By using the function XbaeMatrixDisableRedisplay() you are able to
stop the matrix from redrawing during lengthy updates.  At the end of
the update, XbaeMatrixEnableRedisplay() will redraw the matrix.

Another option is to unmanage the widget via XtUnmanageChild() and
manage it again once the redraw is complete.

2.5 Can I resize the row height in my matrix?

At the moment - no.  Although work is underway to allow different row
heights depending on the contents of a particular cell.

2.6 How do I make the matrix emulate a list?

Documentation for an enhanced list widget does not and will not exist.
Use of the documentation and example program named "list" is highly
recommended.

2.7 Can I change the behaviour of the text field in the matrix?

The XmTextField (or, to be entirely correct, the XqTextField) is
available from the XmNtextField resource.  If you wish to change the
behaviour of the text field, obtain the widget id via this resource
and use XtSetValues to set the text field's resource.

2.8 How can I edit a cell in a fixed column or fixed row?

By setting the resource XmNtraverseFixedCells, fixed rows and columns act
exactly the same way as non-fixed cells.

2.9 Can I select a fixed row or column?

Yes you can.  To do this, however, you need to override the
translations on the matrix widget either with resources or using
XtOverrideTranslations().  With the former, something along the
lines of

*mw*translations: #override\n\
	<Btn1Down>: SelectCell()

and the latter, an

    XtOverrideTranslations(mw, XtParseTranslationTable(
			":<Btn1Down>: SelectCell()"));

will do the trick.

In the selectCellCallback, you then need to select the row/column as
indicated in the callback struct.

Also, refer to the choice example program which demonstrates this
ability.

2.10 How do I select a row or column without the text field being visible?

Normally this is required when a matrix is non editable.  The text
field is mapped as a result of the EditCell action being called which
is the default behaviour of the widget.  You need to replace the
default action with the SelectCell action (see 2.9 above) which does
not map the text field.  By adding an XmNselectCellCallback you can
select a row/column/cell without editing the cell that was clicked.
Setting XmNtraversalOn to False will also help, depending on your
application.

2.11 How do I redraw just a single cell?

Use XbaeMatrixRefreshCell(Widget w, int row, int column).  This
function uses the internal drawing routines of the widget to
explicitly redraw a single cell.
