        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?
    2.12 What do I do with the files Xbae-?.?-?.?.diff
    2.13 How can I save the current cell when the matrix loses focus?
    2.14 How can I popup a menu in a cell using the right mouse button?
    2.15 I am having trouble using the configure script.

--------------------------------------------------------------------------
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
editable). 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 an empty message to
xbae-subscribe@lists.frogdream.com. The list is populated with
many developers using the XbaeMatrix widget and contains discussions
regarding its use, new or desired features, upcoming releases, etc.

The LessTif mailing list will probably carry increasingly more
Xbae related questions because as of August 1999, Xbae is under
maintenance by the LessTif crew. You can join the LessTif mailing
list by sending a message to lesstif-subscribe@lesstif.org .

The LessTif web site contains more information about their mailing
lists; it's at http://www.lesstif.org .

1.6  If I have questions, who should I ask?

The best way to ask questions is via the mailing list.
See above.

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.
If it is a bug it needs to be confirmed by the maintainer.  If, even
better, you have a patch for the bug then it should be forwarded to
the maintainer and not to the mailing list.  If the maintainer feels
it is an urgent fix that may put lives at stake then it is up to him
or her to forward it to the mailing list.  If not, then it will be
included in the next release.

In any case, 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?

	http://www.xbae.syd.net.au

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).  Monetary contributions are
not required but will not be refused.

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

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 text field (or, to be entirely correct, the XbaeInput widget, 
which is pretty much the same as an XmText widget) 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.

2.12 What do I do with the files Xbae-?.?-?.?.diff

You need a utility called 'patch' which is readily available on most
systems.  If not, you can pick it up from an FTP site near you.  As
for its usage I suggest you consult the manual page.

2.13 How can I save the current cell when the matrix loses focus?

The best way is to obtain the widget id of the matrix's text field
and add an XmNlosingFocusCallback to it which calls XbaeMatrixCommitEdit().
Similarly, you can add a call to XbaeMatrixCommitEdit() in other callbacks
as necessary.

2.14 How can I popup a menu in a cell using the right mouse button?

Firstly, you need to change the translations so <Btn3Down> calls the
SelectCell routine.  Something like:

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

The "menu" parameter then gets passed to the selectCellCallback in the
callback struct as params[0] so a simple strcmp() should suffice in
detecting the parameter.

The menu needs to be created using XmCreatePopupMenu() so see your
trusty manual page on how to do this.

To position the menu, you should use XmMenuPosition().  Once again,
you should refer to the manual page.  The event structure is passed
through in the XmNselectCellCallbackStruct.

2.15 I am having trouble using the configure script.

I do not support autoconf, automake, libtool, autogen, autoscan or
configure scripts.  My best advice is to find someone who knows
something about it or use xmkmf.

