Answers to Frequently Asked Questions
about the XbaeMatrix Widget
Table of contents
- General Information
- Programming Questions
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
The Matrix was originally developed by Andrew Wason of Bellcore.
(Bellcore has changed its name to 'Telcordia Technologies'.)
The widget was subsequently released on the 'net
(version 3.5 seems to be the first),
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,
he has contributed many changes as well as integrating changes
contributed by many other people.
People who have contributed code to XbaeMatrix include:
Sorry, if you have been left out - it was not intentional.
- Philip Aston (firstname.lastname@example.org)
- Danny Backx (email@example.com)
- Tim Bomgardner (firstname.lastname@example.org)
- Kevin Brannen (email@example.com)
- Eric Bruno (firstname.lastname@example.org)
- Matthew Francey (email@example.com)
- Martin Helmling (firstname.lastname@example.org)
- Callum Gibson (email@example.com)
- Alexander Ivanov (firstname.lastname@example.org)
- Adam Kerrison (email@example.com)
- Vince Li (firstname.lastname@example.org)
- Andrew Lister (email@example.com)
- Earl Revett (firstname.lastname@example.org)
- Jay Schmidgall (email@example.com)
- Jason Smith (firstname.lastname@example.org)
- Mark Steckel (email@example.com)
- Daiji Takamori (firstname.lastname@example.org)
- Dirk Vangestel (email@example.com)
- Andy Warburton (firstname.lastname@example.org)
- Andrew Wason (email@example.com)
- Neil Weber (firstname.lastname@example.org)
- D. Craig Wilson (email@example.com)
- Q. Frank Xia (firstname.lastname@example.org)
The last version released by Andrew was 4.7 - in July 1999.
After that he transferred maintenance,
it is now with the
Best is to look at it's
for updated version about this.
has older releases, but may not carry recent versions.
The COPYING file describes the terms an conditions but if you (like me)
have trouble understanding legalese here it is in English:
There's a mailinglist dedicated to Xbae. For more details
on it check out the homepage at
- Nobody promises that this software works.
- You can use this software for whatever you want.
- You may not pretend that you wrote this software.
- 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 COPYING file of the distribution being used.
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 maintainers at
Best is to submit a bug report at our website's bug tracker
As an alternative you may send mail to the mailing list
If you have a patch for the bug then please send it along in your message.
It will probably 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 (which operating
system, which Motif library, etc.) and (if you can) a patch.
Yes, of course! It can be found at
The old home page was at
Submitting patches and suggestions enable your
own special place in the README file.
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 behaviour;
- 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:
supplied by Daiji Takamori.
- 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
- confirming that cell modifications should be accepted using
- changing column widths when the entire matrix is resized;
- changing what is selected when a cell is selected;
- changing how traversals are made.
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.
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 =
* Make all of column 2 non editable except for row 4
if(cbs->row != 4)
cbs->doit = False;
cbs->doit = True; /* Default behaviour */
It really is as easy as that!
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
Anybody who uses two byte characters and is willing to come
up with an effective patch is hereby granted the opportunity!
Setting this to False should prevent
any non desirable scrolling.
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.
Yes, starting of version 4.9.0 this is possible.
Documentation for an enhanced list widget does not and will not exist.
Use of the documentation and example program named "list" is highly
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.
By setting the resource XmNtraverseFixedCells,
fixed rows and columns act
exactly the same way as non-fixed cells.
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
and the latter, an
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
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
"How can I edit a cell in a fixed column or fixed row")
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
Use XbaeMatrixRefreshCell(Widget w, int row, int column). This
function uses the internal drawing routines of the widget to
explicitly redraw a single cell.
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
Firstly, you need to change the translations so <Btn3Down> calls the
SelectCell routine. Something like:
The "menu" parameter then gets passed to the selectCellCallback in the
callback struct as params 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.
It has been built using the GNU standard tools automake, autoconf,
(Note: you don't require these tools, only the maintainers do.)
These tools support all platforms known to mankind
(with the possible exception of microwave ovens),
so it is very likely that they configuration will just work for you.
In a few specific circumstances, the configure command needs a little
help. Please ask us and we'll try to help you.
If all that fails, an alternative build method for Xbae exists : Imake.
Use "xmkmf -a; make" and things *should* build as well.
Question : I am trying to use drag and drop to move an item
from an XmList to a XbaeMatrix.
I need to know the Matrix row for the drop,
but the Event that I get is NULL,
so I can't use the Event to RowColumn public routine.
The same question applies when dragging within a matrix.
When you register your drop site you also add a drop callback,
And in this drop function you can do this:
void ddDrop(Widget w,XtPointer clientData,XtPointer callData)
XmDropProcCallback dropData = (XmDropProcCallback) callData;
int x = dropData->x; // drop x coord
int y = dropData->y; // drop y coord
However since I wanted to use
XbaeMatrixGetEventRowColumn(Widget, event, &row, &col);
to get my row/column position I needed an event structure,
so I made a copy of one I got before I started the drag,
and then I adjusted the x and y value and passed it to the
XbaeMatrix function.. and it all works fine!
We want to have the Home key move you to the top of the list
and select the first item.
We are not able to get the keyboard traversals to work for the matrix.
We can get them to work for the TextField widget if it has the focus.
We don't want to make the customer click in an editable field before hitting "Home".
You'll find that things won't work until the text field has been mapped.
We've been trying to get Page Up/Down going but until the text
field has been mapped (even if it is then subsequently unmapped) the
actions don't work.
This seems to be because the initial focus goes to
the clip child (not the matrix itself) which doesn't know what to do
with the key events.
I haven't found any way around this yet,
except that you could manage then unmanage the text field
programmatically and see if that works.
XbaeMatrixEditCell(mw, 0, 0);
XbaeMatrixCommitEdit(mw, True); /* unmap it again */
when you first create the matrix should be virtually undetectable.
Use the XbaeMatrixGetEventRowColumn() function.
This function takes the XEvent structure and then sets the row and column
parameters to the required positions for all cells on the table
(including label buttons).
A -1 for row position indicates the header row,
and a -1 for a col position indicates the header column.
If the cell is a normal table cell (ie not a header label)
the function also returns True.
Note that even when the function returns a
False the values 'row' and 'col' are still set with correct positions
(assuming the XEvent position is within the table of course).
This is apparently an undocumented feature, according to the source code.
Not any more ;-)
If you have more questions, or if you would be able to answer some of the
currently addressed questions better, then please
send us mail.
Latest change to this document : $Date: 2004/10/13 18:32:24 $