File: FAQ.html

package info (click to toggle)
xbae 4.60.2-2
links: PTS
area: main
in suites: etch, etch-m68k, lenny
size: 5,452 kB
ctags: 2,046
sloc: ansic: 21,858; sh: 8,195; makefile: 577; tcl: 1
file content (539 lines) | stat: -rw-r--r-- 21,038 bytes
parent folder | download | duplicates (7)
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
<html>
<!-- $Header: /cvsroot/xbae/Xbae/doc/FAQ.html,v 1.10 2004/10/13 18:32:24 dannybackx Exp $ -->
<!--
   TODO:
     - updates for 4.9.x
-->

<head>
  <title>Frequently Asked Questions about the XbaeMatrix Widget</title>
</head>


<BODY BGCOLOR="#FFFFFF">

<h1 align=center>
Answers to Frequently Asked Questions
<BR>
about the XbaeMatrix Widget
</h1>

<h2 align=center>
Table of contents
</h2>

<ul>
<li> General Information
   <ul>
	<li><a href="#What_is_the_XbaeMatrix_Widget">What is the XbaeMatrix Widget?</a></li>
	<li><a href="#Who_wrote_the_XbaeMatrix_Widget">Who wrote the XbaeMatrix Widget?</a></li>
	<li><a href="#Where_do_I_get_it">Where do I get it?</a></li>
	<li><a href="#What_are_the_terms_of_usage_of_the_XbaeMatrix_Widget">
		What are the terms of usage of the XbaeMatrix Widget?</a></li>
	<li><a href="#Where_can_I_find_out_more">Where can I find out more?</a></li>
	<li><a href="#Where_do_I_mail_suggestionscomments_for_this_FAQ">
		Where do I mail suggestions/comments for this FAQ?</a></li>
	<li><a href="#Aaargh_I_found_a_bug_what_do_I_do">
		Aaargh, I found a bug - what do I do?</a></li>
	<li><a href="#Does_the_XbaeMatrix_Widget_have_a_home_page">
		Does the XbaeMatrix Widget have a home page?</a></li>
	<li><a href="#I_love_it_How_can_I_contribute">I love it! How can I contribute?</a></li>
  </ul>


<li> Programming Questions
  <ul>
	<li><a href="#How_do_I_change_the_behavior_of_the_XbaeMatrix_so_that">
		How do I change the behavior of the XbaeMatrix so that.... ?</a></li>
	<li><a href="#How_do_I_make_a_cell_noneditable">How do I make a cell non-editable?</a></li>
	<li><a href="#Can_I_display_2byte_characters">Can I display 2-byte characters (e.g. kanji)?</a></li>
	<li><a href="#How_do_I_stop_the_matrix_from_scrolling_back_to_the_selected_cell">
		How do I stop the matrix from scrolling back to the selected cell?</a></li>
	<li><a href="#How_do_I_stop_the_matrix_from_flickering_when_it_redraws">
		How do I stop the matrix from flickering when it redraws? </a></li>
	<li><a href="#Can_I_resize_the_row_height_in_my_matrix">
		Can I resize the row height in my matrix?</a></li>
	<li><a href="#How_do_I_make_the_matrix_emulate_a_list">
		How do I make the matrix emulate a list?</a></li>
	<li><a href="#Can_I_change_the_behaviour_of_the_text_field_in_the_matrix">
		Can I change the behaviour of the text field in the matrix?</a></li>
	<li><a href="#How_can_I_edit_a_cell_in_a_fixed_column_or_fixed_row">
		How can I edit a cell in a fixed column or fixed row?</a></li>
	<li><a href="#Can_I_select_a_fixed_row_or_column">
		Can I select a fixed row or column?</a></li>
	<li><a href="#How_do_I_select_a_row_or_column_without_the_text_field_being_visible">
		How do I select a row or column without the text field being visible?</a></li>
	<li><a href="#How_do_I_redraw_just_a_single_cell">
		How do I redraw just a single cell?</a></li>
	<li><a href="#How_can_I_save_the_current_cell_when_the_matrix_loses_focus">
		How can I save the current cell when the matrix loses focus?</a></li>
	<li><a href="#How_can_I_popup_a_menu_in_a_cell_using_the_right_mouse_button">
		How can I popup a menu in a cell using the right mouse button?</a></li>
	<li><a href="#I_am_having_trouble_using_the_configure_script">
		I am having trouble using the configure script.</a></li>
	<li><a href="#How_do_I_work_with_drag_and_drop">
		How do I work with drag and drop?</a></li>
	<li><a href="#Keyboard_translations_dont_always_work">
		Keyboard translations don't always work</a></li>
	<li><a href="#How_can_I_convert_an_XEvent_message">
		How can I convert an XEvent message on a button label to row/column positions
		</a></li>

	<li><a href="#More_questions"><b>More questions ?</b></a></li>
  </ul>
</ul>

<HR>

<H2 align=center>
General Information
</H2>

<h3> <a name="What_is_the_XbaeMatrix_Widget">What is the XbaeMatrix Widget?</A></h3>
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.

<h3><a name="Who_wrote_the_XbaeMatrix_Widget">Who wrote the XbaeMatrix Widget?</a></h3>
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:

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

Sorry, if you have been left out - it was not intentional.
<P>
The last version released by Andrew was 4.7 - in July 1999.
After that he transferred maintenance,
it is now with the 
<A HREF="http://www.lesstif.org" TARGET="_top">LessTif maintainers</A>.

<h3><a name="Where_do_I_get_it">Where do I get it?</a></h3>
Best is to look at it's
<a href="#Does_the_XbaeMatrix_Widget_have_a_home_page">homepage</A>
for updated version about this.
<BR>
<A HREF="ftp://ftp.x.org/contrib/widgets/motif" TARGET="_top">ftp.x.org</a>,
has older releases, but may not carry recent versions.

<h3><a name="What_are_the_terms_of_usage_of_the_XbaeMatrix_Widget">
What are the terms of usage of the XbaeMatrix Widget?</a></h3>
The COPYING file describes the terms an conditions but if you (like me)
have trouble understanding legalese here it is in English:
<ul>
<li>Nobody promises that this software works.
<li>You can use this software for whatever you want.
<li>You may not pretend that you wrote this software.
<li>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.
</ul>

<h3><a name="Where_can_I_find_out_more">Where can I find out more?</a></h3>

There's a mailinglist dedicated to Xbae. For more details
on it check out the homepage at
<A HREF="http://xbae.sourceforge.net" TARGET="_top">http://xbae.sourceforge.net</A>.
<P>


<h3><a name="Where_do_I_mail_suggestionscomments_for_this_FAQ">
Where do I mail suggestions/comments for this FAQ?</a></h3>
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
<a href="mailto:mailto:xbae-discuss@lists.sourceforge.net">mailto:xbae-discuss@lists.sourceforge.net</a> .

<h3><a name="Aaargh_I_found_a_bug_what_do_I_do">
Aaargh, I found a bug - what do I do?</a></h3>
Best is to submit a bug report at our website's bug tracker
facility at:
<A HREF="http://sourceforge.net/tracker/?group_id=31337&amp;atid=401980" TARGET="_top"> 
http://sourceforge.net/tracker/?group_id=31337&amp;atid=401980</A>.
<BR>
As an alternative you may send mail to the mailing list
(see <A HREF="#Where_can_I_find_out_more">above</A>.)
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.
<p>
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.

<h3><a name="Does_the_XbaeMatrix_Widget_have_a_home_page">
Does the XbaeMatrix Widget have a home page?</a></h3>
Yes, of course! It can be found at
<a href="http://xbae.sf.net" TARGET="_top">http://xbae.sf.net</a>.
<BR>
The old home page was at
<a href="http://www.xbae.syd.net.au" TARGET="_top">http://www.xbae.syd.net.au</a>.

<h3><a name="I_love_it_How_can_I_contribute">
I love it!  How can I contribute?</a></h3>
Submitting patches and suggestions enable your
own special place in the README file.

<HR>

<H2 align=center>
Programming Questions
</H2>


<h3><a name="How_do_I_change_the_behavior_of_the_XbaeMatrix_so_that">
How do I change the behavior of the XbaeMatrix so that.... ?</a></h3>
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:

<ul>
<li> changing when the TextField widget is mapped/unmapped;
<li> changing how selections/edits are performed;
<li> changing how cursor movement is performed;
<li> changing when edits are allowed;
<li> installing select-drag behaviour;
<li> installing interactive column resize;
<li> installing drag-n-drop related callbacks.
</ul>

<p>
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:

<ul>
<li> making a cell read only; 
<li> having the data be looked up by a function rather than
	  stored in the XmNcells resource;
<li> confirming that cell edits should be accepted using a
	  function;
<li> confirming that cell modifications should be accepted using
	  a function;
<li> changing column widths when the entire matrix is resized;
<li> changing what is selected when a cell is selected;
<li> changing how traversals are made.
</ul>

<i>supplied by <a href="mailto:daijit@std.teradyne.com">Daiji Takamori</a></i>.
<p>
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.

<h3><a name="How_do_I_make_a_cell_noneditable">How do I make a cell non-editable?</a></h3>
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:
<pre>
void enterCB( Widget w, XtPointer cd, XtPointer cb )
{
    XbaeMatrixEnterCellCallbackStruct *cbs =
        (XbaeMatrixEnterCellCallbackStruct *)cb;

    switch(cbs-&gt;column)
    {
    case 2:
	/*
	 * Make all of column 2 non editable except for row 4
	 */
	if(cbs-&gt;row != 4)
	    cbs-&gt;doit = False;
	break;
    default:
	cbs-&gt;doit = True;	/* Default behaviour */
	break;
    }
}
</pre>
It really is as easy as that!

<h3><a name="Can_I_display_2byte_characters">Can I display 2-byte characters (e.g. kanji)?</a></h3>
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 *.
<p>
Anybody who uses two byte characters and is willing to come
up with an effective patch is hereby granted the opportunity!

<h3><a name="How_do_I_stop_the_matrix_from_scrolling_back_to_the_selected_cell">
How do I stop the matrix from scrolling back to the selected cell?</a></h3>
Use XmNselectScrollVisible.
Setting this to False should prevent
any non desirable scrolling.

<h3><a name="How_do_I_stop_the_matrix_from_flickering_when_it_redraws">
How do I stop the matrix from flickering when it redraws?</a></h3>
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.
<p>
Another option is to unmanage the widget via XtUnmanageChild() and
manage it again once the redraw is complete.

<h3><a name="Can_I_resize_the_row_height_in_my_matrix">
Can I resize the row height in my matrix?</a></h3>
Yes, starting of version 4.9.0 this is possible.

<h3><a name="How_do_I_make_the_matrix_emulate_a_list">
How do I make the matrix emulate a list?</a></h3>
Documentation for an enhanced list widget does not and will not exist.
Use of the documentation and example program named "list" is highly
recommended.

<h3><a name="Can_I_change_the_behaviour_of_the_text_field_in_the_matrix">
Can I change the behaviour of the text field in the matrix?</a></h3>
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.

<h3><a name="How_can_I_edit_a_cell_in_a_fixed_column_or_fixed_row">
How can I edit a cell in a fixed column or fixed row?</a></h3>
By setting the resource XmNtraverseFixedCells,
fixed rows and columns act
exactly the same way as non-fixed cells.

<h3><a name="Can_I_select_a_fixed_row_or_column">
Can I select a fixed row or column?</a></h3>
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
<pre>
*mw*translations: #override\n\
	&lt;Btn1Down&gt;: SelectCell()
</pre>
and the latter, an
<pre>
    XtOverrideTranslations(mw, XtParseTranslationTable(
			":&lt;Btn1Down&gt;: SelectCell()"));
</pre>
will do the trick.
<p>
In the selectCellCallback, you then need to select the row/column as
indicated in the callback struct.
<p>
Also, refer to the choice example program which demonstrates this
ability.

<h3><a name="How_do_I_select_a_row_or_column_without_the_text_field_being_visible">
How do I select a row or column without the text field being visible?</a>
</h3>
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 <a href="#How_can_I_edit_a_cell_in_a_fixed_column_or_fixed_row">
"How can I edit a cell in a fixed column or fixed row"</a>)
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.

<h3>
<a name="How_do_I_redraw_just_a_single_cell">How do I redraw just a single cell?</a>
</h3>
Use XbaeMatrixRefreshCell(Widget w, int row, int column).  This
function uses the internal drawing routines of the widget to
explicitly redraw a single cell.

<h3>
<a name="How_can_I_save_the_current_cell_when_the_matrix_loses_focus">
How can I save the current cell when the matrix loses focus?</a>
</h3>
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.

<h3>
<a name="How_can_I_popup_a_menu_in_a_cell_using_the_right_mouse_button">
How can I popup a menu in a cell using the right mouse button?</a>
</h3>
Firstly, you need to change the translations so &lt;Btn3Down&gt; calls the
SelectCell routine.  Something like:
<p>
*mw*translations: #override\n\
	&lt;Btn3Down&gt;: SelectCell(menu)
<p>
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.
<p>
The menu needs to be created using XmCreatePopupMenu() so see your
trusty manual page on how to do this.
<p>
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.

<h3>
<a name="I_am_having_trouble_using_the_configure_script">
I am having trouble using the configure script.</a>
</h3>
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.
<p>
In a few specific circumstances, the configure command needs a little
help. Please ask us and we'll try to help you.
<p>
If all that fails, an alternative build method for Xbae exists : Imake.
Use "xmkmf -a; make" and things *should* build as well.

<h3>
<a name="How_do_I_work_with_drag_and_drop">
How do I work with drag and drop?</a>
</h3>
<i>
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.
<br>
The same question applies when dragging within a matrix.
</i>
<p>
When you register your drop site you also add a drop callback,
ie
<pre>
XtSetArg(args[n],XmNdropProc,ddDrop);
</pre>
And in this drop function you can do this:
<pre>
	void ddDrop(Widget w,XtPointer clientData,XtPointer callData)
	{
        	XmDropProcCallback dropData = (XmDropProcCallback) callData;
        	int x = dropData-&gt;x;                    // drop x coord
        	int y = dropData-&gt;y;                    // drop y coord
	....
</pre>
However since I wanted to use
<pre>
	XbaeMatrixGetEventRowColumn(Widget, event, &amp;row, &amp;col);
</pre>
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!

<h3>
<a name="Keyboard_translations_dont_always_work">
Keyboard translations don't always work</a>
</h3>
<i>
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".
</i>
<p>
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.
<p>
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.
<p>
Doing :
<pre>
	XbaeMatrixEditCell(mw, 0, 0);
	XbaeMatrixCommitEdit(mw, True); /* unmap it again */
</pre>
when you first create the matrix should be virtually undetectable.

<h3>
<a name="How_can_I_convert_an_XEvent_message">
How can I convert an XEvent message on a button label to row/column positions ?</a>
</h3>
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).
<p>
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.
<i>Not any more ;-)</i>


<h3>
<a name="More_questions">More questions ?</a>
</h3>
If you have more questions, or if you would be able to answer some of the
currently addressed questions better, then please
<A HREF="mailto:xbae-discuss@lists.sourceforge.net">send us mail</A>.
<P>
<small>
Latest change to this document : $Date: 2004/10/13 18:32:24 $
</small>

</body>
</html>