Callback Information
XmNdefaultActionCallback
Callbacks on the XmNdefaultActionCallback list are
called when the DefaultAction() action occurs. The
application can bind the DefaultAction() action to
any pointer based event. When a double click occurs
on this pointer event, DefaultAction() will call the
call backs on the XmNdefaultActionCallback list:
typedef struct
{
XbaeReasonType reason;
int row, column;
XEvent *event;
} XbaeMatrixDefaultActionCallbackStruct;
reason Set to XbaeDefaultActionReason.
row The row number of the cell in which the
double click occurred.
column The column number of the cell in which the
double click occurred.
event The XEvent which invoked the SelectCell()
action.
If an application has an XmNdefaultActionCallback,
then the callbacks on the list will be called when
the user clicks twice in a cell within XmNdou-
bleClickInterval, enabling some action to occur for
the particular cell.
XmNdrawCellCallback
Callbacks on the XmNdrawCellCallback list are called
when the widget needs to draw a cell. A pointer to
the following structure is passed to each callback on
the XmNdrawCellCallback list:
typedef struct
{
XbaeReasonType reason;
int row, column;
int width, height;
XbaeCellType type;
String string;
Pixmap pixmap;
Pixmap mask;
Pixel foreground, background;
} XbaeMatrixDrawCellCallbackStruct;
reason Set to XbaeDrawCellReason.
row The row number of the cell that needs to be
be drawn.
height The height of the cell that needs to be
drawn.
width The width of the cell that needs to be
drawn.
type The type of ``data'' the programmer wants
drawn in the cell, or which field should be
looked at for data to draw: string or
pixmap.
string The string to draw if type is set to
XbaeString.
pixmap The pixmap to copy if type is set to
XbaePixmap. It will be clipped to width by
height if necessary.
mask A mask for the pixmap as obtained from the
XPM library. mask is only necessay when
pixmap has a depth greater than one.
foreground
The foreground color of the cell.
background
The background color of the cell.
If the application adds this callback, when the Xbae-
Matrix determines that a cell at (row, column) needs
to be redrawn, the normal cell drawing mechanism will
be skipped and this callback called so the applica-
tion can tell the widget what to put in the cell.
The type field is defaulted to XbaeString and no
cacheing or saving of the string or pixmap is done.
If the application sets type to XbaePixmap, the
width, height and depth of the returned pixmap will
be calculated with a call to XGetGeometry(). If a
mask is also provided, it will be used to display the
pixmap transparently. Pixmaps drawn in cells also
respect the value of XmNcolumnAlignments.
By defining an XmNdrawCellCallback the need for the
storage of the XbaeMatrix data within the matrix is
eliminated and can prove to be advantageous for mem-
ory usage.
To write the data back to the application, use the
Callbacks on the XmNenterCellCallback list are called
from the EditCell() action just before a cell is
edited to determine it's editability. A pointer to
the following structure is passed to each callback on
the XmNenterCellCallback list:
typedef struct
{
XbaeReasonType reason;
int row, column;
Boolean select_text;
Boolean map;
Boolean doit;
} XbaeMatrixEnterCellCallbackStruct;
reason Set to XbaeEnterCellReason.
row The row number of the cell about to be
edited.
column The column number of the cell about to be
edited.
select_text
Indicates whether the text in the cell
should be highlighted (only valid if doit
is set to True also.
map Tells the matrix if the XmTextField should
be mapped onto the cell. Only makes sense
if doit is set to False.
doit Indicates whether or not this cell is
editable. Setting doit to False will make
this cell not editable. The default value
is True.
If the application determines that the cell at (row,
column) is not editable, it should set the doit flag
to False. If the map flag is also set to False,
XbaeMatrix will not place the XmTextField cell editor
on the cell. If map is left as True, the XmTextField
will be placed on the cell but the user will not be
able to add or delete characters from it. If the
application leaves doit as True, then the TextField
will be editable. In addition, if select_text is set
to True, the text in the cell will be selected via
XmTextFieldSetSelection. Assuming XmNpendingDelete
for the XmTextField is also True, the selected text
will be deleted as soon as the next text insertion
Callbacks on the XmNlabelActivateCallback list are
called after a button label has been activated via a
mouse click. A pointer to the following structure is
passed to each callback on the XmNlabelActivateCall-
back list:
typedef struct
{
XbaeReasonType reason;
XEvent *event;
Boolean row_label;
int row, column;
String label;
} XbaeMatrixLabelActivateCallbackStruct;
reason Set to XbaeLabelActivateReason.
row_label If the button label that invoked the call-
back is a row label, then this value is set
to True. If it was a column label then it
is set to False.
row The row number of the button label or -1 if
the button was a column label.
column The column number of the button label or -1
if the button was a row label.
label The label on the button that was pressed.
When the XbaeMatrix receives a ButtonRelease event on
the same button label that it received a ButtonPress
event, the XmNlabelActivateCallback is called to
allow the programmer to respond to the event. The
callback has been provided to emulate some popular
spreadsheets on the market.
XmNleaveCellCallback
Callbacks on the XmNleaveCellCallback list are called
from the EditCell() and CommitEdit() actions just
before the edit to the current cell is committed. The
application can validate the changes made to the
cell, and allow or disallow them. A pointer to the
following structure is passed to each callback on the
XmNleaveCellCallback list:
typedef struct
{
XbaeReasonType reason;
int row, column;
String value;
Boolean doit;
} XbaeMatrixLeaveCellCallbackStruct;
reason Set to XbaeLeaveCellReason.
row The row number of the cell being edited.
column The column number of the cell being edited.
value Contains the new data which will be stored
in this cell if doit is True. The memory
pointed to by value may be modified, or if
the new contents are larger than the cur-
rent contents, then value should be set to
point to a larger piece of allocated mem-
ory.
doit Indicates whether the edits applied to this
cell should actually be stored into XbaeMa-
trix. Setting doit to False will cause the
changes to be discarded and the cell will
retain its original value. The default
value is True.
If the application determines that the value entered
in the cell at (row, column) is not valid, it should
set the doit flag to False. This will prevent the
changes from being stored in the cell. The TextField
edit widget will remain on the current cell. If the
application leaves doit as True, then the changes
made to the cell will be committed and the TextField
will move to the next cell or be unmapped. The appli-
cation can also modify the String in value, e.g. to
force a String to be all upper case.
XmNmodifyVerifyCallback
Callbacks on the XmNmodifyVerifyCallback list are
called while a cell is being edited. The callbacks
are called before text is inserted into or deleted
from the TextField edit widget. A pointer to the fol-
lowing structure is passed to each callback on the
XmNmodifyVerifyCallback list:
typedef struct
{
XbaeReasonType reason;
int row, column;
XmTextVerifyCallbackStruct *verify;
const char *prev_text;
} XbaeMatrixModifyVerifyCallbackStruct;
reason Set to XbaeModifyVerifyReason.
row The row number of the cell being edited.
column The column number of the cell being edited.
verify The contents of this structure and its use
are documented in the XmTextField(3X) man
page.
prev_text The contents of the cell as seen by this
user before the new text. If other text
has already been entered, this value will
not match the official XbaeMatrix value of
the cell. This pointer and the string
should not be modified.
XmNprocessDragCallback
Callbacks on the XmNprocessDragCallback list are
called from the ProcessDrag() action. The application
can bind the ProcessDrag() action to any pointer
based event, though by default it is bound to the
Button2Down event. When this event occurs,
ProcessDrag() will call the callbacks on the XmNpro-
cessDragCallback list. A pointer to the following
structure is passed to each callback on the XmNpro-
cessDragCallback list:
typedef struct
{
XbaeReasonType reason;
int row, column;
String string;
XbaeCellType type;
Pixmap pixmap;
Pixmap mask;
Cardinal num_params;
String *params;
XEvent *event;
} XbaeMatrixProcessDragCallbackStruct;
row The row number of the cell where the drag
was initiated..
column The column number of the cell where the
drag was initiated..
string The string in the cell where the drag was
initiated if type is XbaeString. This is
provided as a convenience to the applica-
tion.
type The type of the cell in which the drag was
initiated.
pixmap The pixmap in the cell where the drag was
initiated if type is XbaePixmap. This is
provided as a convenience to the applica-
tion.
mask A mask for the pixmap as obtained from the
XPM library. mask is only necessary when
pixmap has a depth greater than one. Also
provided as a convenience to the applica-
tion.
num_params
The number of String parameters passed to
the ProcessDrag() action.
params An array containing the num_params String
parameters passed to the ProcessDrag()
action.
event The XEvent which invoked the ProcessDrag()
action.
The application can use the XmNprocessDragCallback
list to implement particular processing for Motif's
drag-and-drop.
XmNresizeCallback
Callbacks on the XmNresizeCallback list are called
when the XbaeMatrix widget is resized. A pointer to
the following structure is passed to
each callback on the XmNresizeCallback list:
typedef struct
{
XbaeReasonType reason;
Dimension width;
Dimension height;
} XbaeMatrixResizeCallbackStruct;
reason Set to XbaeResizeReason.
width The new width of the XbaeMatrix widget.
height The new height of the XbaeMatrix widget.
The application can use the XmNresizeCallback to
adjust such resources as XmNcolumnWidths, XmNvisi-
bleColumns and XmNvisibleRows when the widget con-
taining an XbaeMatrix widget is resized.
XmNresizeColumnCallback
Callbacks on the XmNresizeColumnCallback list are
called when a column of the XbaeMatrix widget is
dynamically resized by the user. A pointer to the
following structure is passed to each callback on the
XmNresizeColumnCallback list:
typedef struct
{
XbaeReasonType reason;
int which;
int columns;
short * column_widths;
XEvent * event;
} XbaeMatrixResizeCallbackStruct;
reason Set to XbaeResizeColumnReason.
which The column that was resized in the
ResizeColumn() action.
columns The number of columns in the XbaeMatrix
widget.
column_widths
The widths of each column as they stand
after the ResizeColumn() action.
event The XEvent that ended the resize. The
event will be of type XButtonReleasedEvent.
to perform post processing after a column has been
resized. By adjusting the values contained in col-
umn_widths the XbaeMatrix widget will use the values
upon return from the callback. Changing the number
of columns in the matrix in the XmNresizeColumnCall-
back should be used carefully as it may cause unex-
pected results.
XmNselectCellCallback
Callbacks on the XmNselectCellCallback list are
called from the SelectCell() action. The application
can bind the SelectCell() action to any pointer based
event. When this event occurs, SelectCell() will call
the callbacks on the XmNselectCellCallback list. A
pointer to the following structure is passed to each
callback on the XmNselectCellCallback list:
typedef struct
{
XbaeReasonType reason;
int row, column;
Boolean **selected_cells;
String **cells;
Cardinal num_params;
String *params;
XEvent *event;
} XbaeMatrixSelectCellCallbackStruct;
reason Set to XbaeSelectCellReason.
row The row number of the cell which was
selected.
column The column number of the cell which was
selected.
selected_cells
The value of the XmNselectedCells resource.
This is provided as a convenience to the
application.
cells The value of the XmNcells resource. This is
provided as a convenience to the applica-
tion.
num_params
The number of String parameters passed to
the SelectCell() action.
action.
event The XEvent which invoked the SelectCell()
action.
The application can use the XmNselectCellCallback
list to implement it's own selection model. The Xbae-
MatrixSelectCellCallbackStruct contains the array of
String parameters passed to the SelectCell() action
which invoked this callback. By binding the
SelectCell() action to various events via the trans-
lation manager, and using String action parameters to
distinguish them, the application can implement vari-
ous selection models. For example, the following
translations could be used to implement a model in
which a modifier key indicates whether a single cell
or an entire row should be selected. The callbacks on
the XmNselectCellCallback list would examine the
parameter and take the appropriate action.
#override\n\
Shift<Btn1Down>: SelectCell(cell)\n\
Ctrl<Btn1Down>: SelectCell(row)
The callbacks on the XmNselectCellCallback list can
also be used in other ways, e.g. to pop up a cell
specific menu.
NOTE: If no cells have been selected, the value of
selected_cells will be NULL. The same applies for
cells. Care must be taken so as not to dereference
these members of the callback struct.
XmNtraverseCellCallback
Callbacks on the XmNtraverseCellCallback list are
called from the EditCell() action, they are also
called when XbaeMatrix receives the focus while the
TextField edit widget is unmapped. The application
can customize cell traversal using these callbacks.
XbaeMatrix has a default traversal order, outlined
below, which the application can override. A pointer
to the following structure is passed to each callback
on the XmNtraverseCellCallback list:
typedef struct
{
XbaeReasonType reason;
int row, column;
int next_row, next_column;
int fixed_rows, fixed_columns;
int trailing_fixed_rows, trailing_fixed_columns;
int num_rows, num_columns;
String param;
XrmQuark qparam;
} XbaeMatrixTraverseCellCallbackStruct;
reason Set to XbaeTraverseCellReason.
row The row number of the cell currently being
edited.
column The column number of the cell currently
being edited.
next_row The row number of the next cell to be
edited, this can be changed by the applica-
tion.
next_column
The column number of the next cell to be
edited, this can be changed by the applica-
tion.
fixed_rows
The value of the XmNfixedRows resource.
This is provided as a convenience for the
application in calculating the next_row and
next_column fields.
fixed_columns
The value of the XmNfixedColumns resource.
This is provided as a convenience for the
application in calculating the next_row and
next_column fields.
trailing_fixed_rows
The value of the XmNtrailingFixedRows
resource. This is provided as a convenience
for the application in calculating the
next_row and next_column fields.
trailing_fixed_columns
The value of the XmNtrailingFixedColumns
resource. This is provided as a convenience
for the application in calculating the
next_row and next_column fields.
provided as a convenience for the applica-
tion in calculating the next_row and
next_column fields.
num_columns
The value of the XmNcolumns resource. This
is provided as a convenience for the appli-
cation in calculating the next_row and
next_column fields.
param The String value of the parameter passed to
the EditCell() action.
qparam The XrmQuark value of the parameter passed
to the EditCell() action.
The EditCell() action takes an arbitrary parameter
which it passes through to the callbacks on the XmN-
traverseCellCallback list in both String and XrmQuark
forms. The EditCell() action recognizes five special
parameters which it uses to implement it's default
cell traversal. These parameters and their corre-
sponding traversal results are:
Pointer Set next_row and next_column to the cell
underneath the mouse pointer.
Left If we are currently editing cell (XmN-
fixedRows, XmNfixedColumns), then do not
move. Otherwise move one column to the
left, if that column is less than XmNfixed-
Columns , then move up to the last column
of the row above.
Right If we are currently editing cell (XmNrows -
1, XmNcolumns - 1), then do not move. Oth-
erwise move one column to the right, if
that column is greater than or equal to
XmNcolumns , then move down to column XmN-
fixedColumns of the row below.
Up Move up one row. If that row is less than
XmNfixedRows , then move to the last row.
Down Move down one row. If that row is greater
than or equal to XmNrows , then move to row
XmNfixedRows.
If the EditCell() action recognizes one of these spe-
cial parameters, it calculates the new cell to be
edited accordingly and stores the results in the
does not recognize it's parameter, it sets next_row
and next_column to the current row and column. It
also stores a String and XrmQuark version of it's
parameter in the param and qparam fields. EditCell()
then calls the callbacks on the XmNtraverseCellCall-
back list. These callbacks can examine the parameter
and recalculate the next_row and next_column fields
appropriately. The application can override the
default calculation for the special parameters, or it
can define an entirely new parameter with a corre-
sponding new calculation. It would do this by bind-
ing EditCell() with a new application specific param-
eter to an event in a translation table. It is
expected that application callbacks will use the
XrmQuark version of the parameter for efficiency rea-
sons (by statically creating the new XrmQuarks and
comparing them against the incoming qparam).
When XbaeMatrix receives the focus and the TextField
edit widget is unmapped, it will call the XmNtraver-
seCellCallback callbacks before attempting to auto-
matically edit the upper left most visible cell. The
XbaeMatrixTraverseCellCallbackStruct will have a
param of NULL, a qparam of NULLQUARK and a row and
column of 0.
XmNwriteCellCallback
Callbacks (although it probably only makes sense to
have one) on the XmNwriteCellCallback list are called
when the widget needs to write data to a cell, but
only when XmNdrawCellCallback is defined. A pointer
to the following structure is passed to each callback
on the XmNwriteCellCallback list:
typedef struct
{
XbaeReasonType reason;
int row, column;
XbaeCellType type;
String string;
Pixmap pixmap;
Pixmap mask;
} XbaeMatrixWriteCellCallbackStruct;
reason Set to XbaeWriteCellReason.
row The row number of the cell that needs to be
written.
type The type of ``data'' contained in the cell,
either XbaeString or XbaePixmap.
string The string to store if type is set to
XbaeString.
pixmap The pixmap to store if type is set to
XbaePixmap.
mask A mask for the pixmap as obtained from the
XPM library. mask is only necessary when
pixmap has a depth greater than one.
If the application adds this callback, when the Xbae-
Matrix is editable and has been assigned an XmNdraw-
CellCallback, data on the widget can be edited and
stored back in the application's data structure.
Only if an XmNdrawCellCallback has been assigned to
the XbaeMatrix widget, will the XmNwriteCellCallback
be called.
At the moment, pixmap and mask will be sent to the
XmNwriteCellCallback as NULL.