Answers to Frequently Asked Questions
about the XbaeMatrix Widget

Table of contents

General Information

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.

Who wrote the XbaeMatrix Widget?

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.

The last version released by Andrew was 4.7 - in July 1999. After that he transferred maintenance, it is now with the LessTif maintainers.

Where do I get it?

Best is to look at it's homepage for updated version about this.
ftp.x.org, has older releases, but may not carry recent versions.

What are the terms of usage of the XbaeMatrix Widget?

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

Where can I find out more?

There's a mailinglist dedicated to Xbae. For more details on it check out the homepage at http://xbae.sourceforge.net.

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 maintainers at mailto:xbae-discuss@lists.sourceforge.net .

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

Best is to submit a bug report at our website's bug tracker facility at: http://sourceforge.net/tracker/?group_id=31337&atid=401980.
As an alternative you may send mail to the mailing list (see above.) 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.

Does the XbaeMatrix Widget have a home page?

Yes, of course! It can be found at http://xbae.sf.net.
The old home page was at http://www.xbae.syd.net.au.

I love it! How can I contribute?

Submitting patches and suggestions enable your own special place in the README file.

Programming Questions

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:

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.

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.

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!

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 characters and is willing to come up with an effective patch is hereby granted the opportunity!

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.

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.

Can I resize the row height in my matrix?

Yes, starting of version 4.9.0 this is possible.

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.

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.

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.

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.

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 "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 application.

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.

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.

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.

I am having trouble using the configure script.

It has been built using the GNU standard tools automake, autoconf, and libtool. (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.

How do I work with drag and drop?

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, ie 

XtSetArg(args[n],XmNdropProc,ddDrop);
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!

Keyboard translations don't always work

Question : 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.

Doing : 

	XbaeMatrixEditCell(mw, 0, 0);
	XbaeMatrixCommitEdit(mw, True); /* unmap it again */
when you first create the matrix should be virtually undetectable.

How can I convert an XEvent message on a button label to row/column positions ?

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 ;-)

More questions ?

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 $