Provided by: libxbae-dev_4.60.4-9build2_amd64 
NAME
XbaeMatrix - The Bellcore Application Environment (BAE) XbaeMatrix widget class.
SYNOPSIS
#include <Xbae/Matrix.h>
DESCRIPTION
XbaeMatrix presents an editable array of string data to the user in a scrollable grid-like format similar
to a spreadsheet. Non editable pixmaps can also be displayed on the matrix. The rows and columns of the
Matrix may optionally be labeled. Also, a number of fixed leading or trailing rows or columns may be
specified - these behave similarly to the labels. While XbaeMatrix looks and acts like a grid of XmText
widgets, it actually contains only one XmText. This means that XbaeMatrix widgets with hundreds or
thousands of rows have much less overhead than they would if they used an XmText for each cell.
Clicking on a cell with Button1 will edit the cell. While a cell is being edited, Tab and Shift-Tab will
edit the cell to the right or left respectively. The osfUp and osfDown keys will edit the cell above or
below. Ctrl-Tab and Shift-Ctrl-Tab will traverse out of the Matrix and into the next or previous tab
groups.
The osfCancel key will cancel any edits made to a cell. The osfActivate key will commit any edits made
to a cell and store them in the Matrix. When traversing from another tab group into the Matrix, the
focus will go to whichever cell is currently being edited. If no cells are being edited, then the upper
left most visible non-fixed cell will be edited.
The column sizes may be dynamically resized by pressing the Shift-Button2 combination when over a column
boundary, similar to the behaviour of some popular spreadsheets. After a column has been resized in this
manner, the XbaeMatrix calls the callbacks on the XmNresizeColumnCallback callback list for post
processing.
If the Matrix is resized until it is too small to display all of the cells in a given dimension, then it
will display a ScrollBar for that dimension. The horizontal ScrollBar will scroll the cells and column
labels, but not the row labels, fixed columns or trailing fixed columns. The vertical ScrollBar will
scroll the cells and row labels, but not the column labels, fixed rows or trailing fixed rows.
For the application programmer, XbaeMatrix provides callbacks to assist in data validation. The
callbacks on the XmNmodifyVerifyCallback callback list are called before text is inserted into, or
deleted from, a cell. This callback list can be used to force user input to match a certain pattern
(e.g. a date format). Similarly, the XmNvalueChangedCallback is called after text is inserted or
deleted.
When a cell is edited (by clicking on it or tabbing into it), the XmNleaveCellCallback callbacks are
called for the previous cell being edited, if any. The application can verify the data entered in that
cell and disallow editing of the new cell if the data is invalid. If the data was valid, then the
XmNenterCellCallback callbacks for the new cell are called. These callbacks can be used to specify the
editability of the new cell.
The XmNtraverseCellCallback callbacks are also called when the user attempts to edit a new cell and when
the matrix gains or looses focus. This allows the application to override the default traversal behavior
of XbaeMatrix.
The XmNdefaultActionCallback is provided to allow a double click action in a cell to perform some
function.
Motif's Drag and Drop functionality can be achieved via the XmNprocessDragCallback.
For large amounts of data, the overhead of assigning data to the widget can be avoided using the
XmNdrawCellCallback. This callback also allows user defined pixmaps to be placed in a certain cell.
When using this callback, data for string fields can be written back to the application by using the
XmNwriteCellCallback.
Classes
XbaeMatrix inherits behavior and resources from the Core, Composite, Constraint, and XmManager widget
classes.
The class pointer is xbaeMatrixWidgetClass.
The class name is XbaeMatrix.
New Resources
The following table lists the new resources defined by XbaeMatrix. The codes in the ``Access'' column
indicate whether the given resource can be set at creation time (C), or set by using XtSetValues (S), or
retrieved by using XtGetValues (G).
┌─────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ XbaeMatrix Resource Set │
├────────────────────────────┬─────────────────────────┬────────────────────┬───────────────────┬─────────┤
│ Name │ Class │ Type │ Default │ Access │
├────────────────────────────┼─────────────────────────┼────────────────────┼───────────────────┼─────────┤
│ XmNallowColumnResize │ XmCAllowResize │ Boolean │ True │ CSG │
├────────────────────────────┼─────────────────────────┼────────────────────┼───────────────────┼─────────┤
│ XmNallowRowResize │ XmCAllowResize │ Boolean │ True │ CSG │
├────────────────────────────┼─────────────────────────┼────────────────────┼───────────────────┼─────────┤
│ XmNaltRowCount │ XmCAltRowCount │ int │ 1 │ CSG │
├────────────────────────────┼─────────────────────────┼────────────────────┼───────────────────┼─────────┤
│ XmNboldLabels │ XmCBoldLabels │ Boolean │ False │ CSG │
├────────────────────────────┼─────────────────────────┼────────────────────┼───────────────────┼─────────┤
│ XmNbuttonLabels │ XmCButtonLabels │ Boolean │ False │ CSG │
├────────────────────────────┼─────────────────────────┼────────────────────┼───────────────────┼─────────┤
│ XmNbuttonLabelBackground │ XmCColor │ Pixel │ dynamic │ CSG │
├────────────────────────────┼─────────────────────────┼────────────────────┼───────────────────┼─────────┤
│ XmNcalcCursorPosition │ XmCCalcCursorPosition │ Boolean │ False │ CSG │
├────────────────────────────┼─────────────────────────┼────────────────────┼───────────────────┼─────────┤
│ XmNcellBackgrounds │ XmCColors │ PixelTable │ NULL │ CSG │
├────────────────────────────┼─────────────────────────┼────────────────────┼───────────────────┼─────────┤
│ XmNcellHighlightThickness │ XmCHighlightThickness │ Dimension │ dynamic │ CSG │
├────────────────────────────┼─────────────────────────┼────────────────────┼───────────────────┼─────────┤
│ XmNcellMarginHeight │ XmCMarginHeight │ Dimension │ dynamic │ CSG │
├────────────────────────────┼─────────────────────────┼────────────────────┼───────────────────┼─────────┤
│ XmNcellMarginWidth │ XmCMarginWidth │ Dimension │ dynamic │ CSG │
├────────────────────────────┼─────────────────────────┼────────────────────┼───────────────────┼─────────┤
│ XmNcellShadowThickness │ XmCShadowThickness │ Dimension │ 2 │ CSG │
├────────────────────────────┼─────────────────────────┼────────────────────┼───────────────────┼─────────┤
│ XmNcellShadowType │ XmCShadowType │ unsigned char │ XmSHADOW_OUT │ CSG │
├────────────────────────────┼─────────────────────────┼────────────────────┼───────────────────┼─────────┤
│ XmNcellShadowTypes │ XmCCellShadowTypes │ unsigned char ** │ NULL │ CSG │
├────────────────────────────┼─────────────────────────┼────────────────────┼───────────────────┼─────────┤
│ XmNcellUserData │ XmCCellUserData │ XtPointer ** │ NULL │ CSG │
├────────────────────────────┼─────────────────────────┼────────────────────┼───────────────────┼─────────┤
│ XmNclipWindow │ XmCClipWindow │ Widget │ NULL │ G │
├────────────────────────────┼─────────────────────────┼────────────────────┼───────────────────┼─────────┤
│ XmNcells │ XmCCells │ CellTable │ NULL │ CSG │
├────────────────────────────┼─────────────────────────┼────────────────────┼───────────────────┼─────────┤
│ XmNcolors │ XmCColors │ PixelTable │ NULL │ CSG │
├────────────────────────────┼─────────────────────────┼────────────────────┼───────────────────┼─────────┤
│ XmNcolumnAlignments │ XmCAlignments │ AlignmentArray │ dynamic │ CSG │
├────────────────────────────┼─────────────────────────┼────────────────────┼───────────────────┼─────────┤
│ XmNcolumnButtonLabels │ XmCButtonLabels │ BooleanArray │ NULL │ CSG │
├────────────────────────────┼─────────────────────────┼────────────────────┼───────────────────┼─────────┤
│ XmNcolumnLabelAlignments │ XmCAlignments │ AlignmentArray │ dynamic │ CSG │
├────────────────────────────┼─────────────────────────┼────────────────────┼───────────────────┼─────────┤
│ XmNcolumnLabelColor │ XmCColor │ Pixel │ dynamic │ CSG │
├────────────────────────────┼─────────────────────────┼────────────────────┼───────────────────┼─────────┤
│ XmNcolumnLabels │ XmCLabels │ StringArray │ NULL │ CSG │
├────────────────────────────┼─────────────────────────┼────────────────────┼───────────────────┼─────────┤
│ XmNcolumnMaxLengths │ XmCColumnMaxLengths │ MaxLengthArray │ NULL │ CSG │
├────────────────────────────┼─────────────────────────┼────────────────────┼───────────────────┼─────────┤
│ XmNcolumnShadowTypes │ XmCShadowTypes │ unsigned char * │ NULL │ CSG │
├────────────────────────────┼─────────────────────────┼────────────────────┼───────────────────┼─────────┤
│ XmNcolumnUserData │ XmCUserDatas │ XtPointer * │ NULL │ CSG │
├────────────────────────────┼─────────────────────────┼────────────────────┼───────────────────┼─────────┤
│ XmNcolumnWidthInPixels │ XmCColumnWidthInPixels │ Boolean │ False │ CSG │
├────────────────────────────┼─────────────────────────┼────────────────────┼───────────────────┼─────────┤
│ XmNcolumnWidths │ XmCColumnWidths │ WidthArray │ NULL │ CSG │
├────────────────────────────┼─────────────────────────┼────────────────────┼───────────────────┼─────────┤
│ XmNcolumns │ XmCColumns │ int │ 0 │ CSG │
├────────────────────────────┼─────────────────────────┼────────────────────┼───────────────────┼─────────┤
│ XmNdefaultActionCallback │ XmCCallback │ XtCallbackList │ NULL │ CSG │
├────────────────────────────┼─────────────────────────┼────────────────────┼───────────────────┼─────────┤
│ XmNdoubleClickInterval │ XmCDoubleClickInterval │ int │ dynamic │ CSG │
├────────────────────────────┼─────────────────────────┼────────────────────┼───────────────────┼─────────┤
│ XmNdrawCellCallback │ XmCCallback │ Callback │ NULL │ CSG │
├────────────────────────────┼─────────────────────────┼────────────────────┼───────────────────┼─────────┤
│ XmNenterCellCallback │ XmCCallback │ Callback │ NULL │ CSG │
├────────────────────────────┼─────────────────────────┼────────────────────┼───────────────────┼─────────┤
│ XmNevenRowBackground │ XmCBackground │ Pixel │ dynamic │ CSG │
├────────────────────────────┼─────────────────────────┼────────────────────┼───────────────────┼─────────┤
│ XmNfill │ XmCFill │ Boolean │ False │ CSG │
├────────────────────────────┼─────────────────────────┼────────────────────┼───────────────────┼─────────┤
│ XmNhorzFill │ XmCHorzFill │ Boolean │ False │ CSG │
├────────────────────────────┼─────────────────────────┼────────────────────┼───────────────────┼─────────┤
│ XmNvertFill │ XmCVertFill │ Boolean │ False │ CSG │
├────────────────────────────┼─────────────────────────┼────────────────────┼───────────────────┼─────────┤
│ XmNfixedColumns │ XmCFixedColumns │ Dimension │ 0 │ CSG │
├────────────────────────────┼─────────────────────────┼────────────────────┼───────────────────┼─────────┤
│ XmNfixedRows │ XmCFixedRows │ Dimension │ 0 │ CSG │
├────────────────────────────┼─────────────────────────┼────────────────────┼───────────────────┼─────────┤
│ XmNfontList │ XmCFontList │ FontList │ fixed │ CSG │
├────────────────────────────┼─────────────────────────┼────────────────────┼───────────────────┼─────────┤
│ XmNgridLineColor │ XmCColor │ Pixel │ dynamic │ CSG │
├────────────────────────────┼─────────────────────────┼────────────────────┼───────────────────┼─────────┤
│ XmNgridType │ XmCGridType │ GridType │ XmGRID_CELL_LINE │ CSG │
├────────────────────────────┼─────────────────────────┼────────────────────┼───────────────────┼─────────┤
└────────────────────────────┴─────────────────────────┴────────────────────┴───────────────────┴─────────┘
┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ XbaeMatrix Resource Set (continued) │
├────────────────────────────────────┬──────────────────────────────┬───────────────┬──────────────────┬──────┤
--
Inherited Resources
The following table lists the resources which XbaeMatrix inherits from it's superclasses XmManager,
Compositeand Core. For a complete description of each resource, refer to the man page for that
superclass. The codes in the ``Access'' column indicate whether the given resource can be set at
creation time (C), or set by using XtSetValues (S), or retrieved by using XtGetValues (G).
┌─────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ XmManager Resource Set │
├────────────────────────┬────────────────────────┬─────────────────────┬───────────────────────┬─────────┤
│ Name │ Class │ Type │ Default │ Access │
├────────────────────────┼────────────────────────┼─────────────────────┼───────────────────────┼─────────┤
│ XmNbottomShadowColor │ XmCBottomShadowColor │ Pixel │ dynamic │ CSG │
├────────────────────────┼────────────────────────┼─────────────────────┼───────────────────────┼─────────┤
│ XmNbottomShadowPixmap │ XmCBottomShadowPixmap │ Pixmap │ XmUNSPECIFIED_PIXMAP │ CSG │
├────────────────────────┼────────────────────────┼─────────────────────┼───────────────────────┼─────────┤
│ XmNforeground │ XmCForeground │ Pixel │ dynamic │ CSG │
├────────────────────────┼────────────────────────┼─────────────────────┼───────────────────────┼─────────┤
│ XmNhighlightColor │ XmCHighlightColor │ Pixel │ dynamic │ CSG │
├────────────────────────┼────────────────────────┼─────────────────────┼───────────────────────┼─────────┤
│ XmNhighlightPixmap │ XmCHighlightPixmap │ Pixmap │ dynamic │ CSG │
├────────────────────────┼────────────────────────┼─────────────────────┼───────────────────────┼─────────┤
│ XmNinitialFocus │ XmCInitialFocus │ Widget │ NULL │ CSG │
├────────────────────────┼────────────────────────┼─────────────────────┼───────────────────────┼─────────┤
│ XmNnavigationType │ XmCNavigationType │ XmNavigationType │ XmTAB_GROUP │ CSG │
├────────────────────────┼────────────────────────┼─────────────────────┼───────────────────────┼─────────┤
│ XmNshadowThickness │ XmCShadowThickness │ Dimension │ dynamic │ CSG │
├────────────────────────┼────────────────────────┼─────────────────────┼───────────────────────┼─────────┤
│ XmNstringDirection │ XmCStringDirection │ XmStringDirection │ dynamic │ CG │
├────────────────────────┼────────────────────────┼─────────────────────┼───────────────────────┼─────────┤
│ XmNtopShadowColor │ XmCTopShadowColor │ Pixel │ dynamic │ CSG │
├────────────────────────┼────────────────────────┼─────────────────────┼───────────────────────┼─────────┤
│ XmNtopShadowPixmap │ XmCTopShadowPixmap │ Pixmap │ dynamic │ CSG │
├────────────────────────┼────────────────────────┼─────────────────────┼───────────────────────┼─────────┤
│ XmNtraversalOn │ XmCTraversalOn │ Boolean │ True │ CSG │
├────────────────────────┼────────────────────────┼─────────────────────┼───────────────────────┼─────────┤
│ XmNunitType │ XmCUnitType │ unsigned char │ dynamic │ CSG │
├────────────────────────┼────────────────────────┼─────────────────────┼───────────────────────┼─────────┤
│ XmNuserData │ XmCUserData │ XtPointer │ NULL │ CSG │
└────────────────────────┴────────────────────────┴─────────────────────┴───────────────────────┴─────────┘
┌─────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ Composite Resource Set │
├───────────────────────┬──────────────────────────┬────────────────────┬────────────────┬────────────┤
│ Name │ Class │ Type │ Default │ Access │
├───────────────────────┼──────────────────────────┼────────────────────┼────────────────┼────────────┤
│ XmNchildren │ XmCReadOnly │ WidgetList │ NULL │ G │
├───────────────────────┼──────────────────────────┼────────────────────┼────────────────┼────────────┤
│ XmNinsertPosition │ XmCInsertPosition │ XtOrderProc │ NULL │ CSG │
├───────────────────────┼──────────────────────────┼────────────────────┼────────────────┼────────────┤
│ XmNnumChildren │ XmCReadOnly │ Cardinal │ 0 │ G │
└───────────────────────┴──────────────────────────┴────────────────────┴────────────────┴────────────┘
┌──────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ Core Resource Set │
├───────────────────────────────┬─────────────────────────────┬───────────────┬────────────────────┬───────┤
--
Callback Information
XbaeMatrixAnyCallbackStruct
A callback struct that is suitable for all callbacks that require the reason, event, row and column
to be available. Any callback called may therefore cast the third parameter to the following struct
in XbaeMatrix and can rest assured that evrything in it will be available.
typedef struct
{
XbaeReasonType reason;
int row;
int column;
XEvent *event;
} XbaeMatrixAnyCallbackStruct;
Each of the members are set to the appropriate struct for the callback.
If this idea is a little foreign to you, recommended reading is K&R II page 213.
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 callbacks on the
XmNdefaultActionCallback list. A pointer to the following structure is passed to each callback on
the XmNdefaultActionCallback list:
typedef struct
{
XbaeReasonType reason;
XEvent *event;
int row;
int column;
} XbaeMatrixDefaultActionCallbackStruct;
reason Set to XbaeDefaultActionReason .
event The event that invoked this callback.
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
If an application has an XmNdefaultActionCallback, then the callbacks on the list will be called
when the user clicks twice in a cell within XmNdoubleClickInterval, 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;
XEvent *event;
int row;
int column;
int width;
int height;
XbaeCellType type;
String string;
Pixmap pixmap;
Pixmap mask;
Pixel foreground;
Pixel background;
int depth;
} XbaeMatrixDrawCellCallbackStruct;
reason Set to XbaeDrawCellReason.
event Always set to NULL
row The row number of the cell that needs to be drawn.
column The column number of the cell that needs to be drawn.
width The width of the cell that needs to be drawn.
height The height 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 or XbaeStringFree.
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 necessary when
pixmap has a depth greater than one.
foreground
The foreground color of the cell.
background
The background color of the cell.
depth The depth of the pixmap image (in bits per pixel).
If the application adds this callback, when the XbaeMatrix 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 application 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 the programmer wishes to supply the width, height
and depth there is a marked improvement as a round trip to the X server is avoided. Note that all
geometry parameters must be supplied to ensure successful display of the pixmap.
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 memory usage.
To write the data back to the application, use the XmNwriteCellCallback described below.
XmNenterCellCallback
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;
XEvent *event;
int row;
int column;
int position;
String pattern;
Boolean auto_fill;
Boolean convert_case;
Boolean overwrite_mode;
Boolean select_text;
Boolean map;
Cardinal num_params;
String *params;
Boolean doit;
} XbaeMatrixEnterCellCallbackStruct;
reason Set to XbaeEnterCellReason.
event The event that invoked the callback.
row The row number of the cell about to be edited.
column The column number of the cell about to be edited.
position The location of the cursor in the text field. The default is to place the cursor at the
end of the string in the cell.
pattern A pattern for the XbaeInput widget (see XbaeInput(3)). The default is to not specify a
pattern.
auto_fill Used in conjunction with the setting of the pattern to allow literals in the pattern to be
automatically inserted.
convert_case
If the pattern specifies an upper or lower case letter, the character typed in the
position can automatically be converted to the appropriate case when set to True. The
default is to not convert the case of the typed letter.
overwrite_mode
Normally, the cursor appears as the familiar I caret. By setting overwrite_mode to True,
the text field will go into overwrite mode where keystrokes replace the character
underneath the block cursor.
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 XmText should be mapped onto the cell. Only makes sense if doit
is set to False.
num_params
The number of String parameters passed to the EditCell() action.
params An array containing the num_params String parameters passed to the EditCell() action.
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 XmText cell
editor on the cell. If map is left as True, the XmText 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 XmTextSetSelection. Assuming XmNpendingDelete for the XmText is also True, the
selected text will be deleted as soon as the next text insertion occurs.
XmNlabelActivateCallback
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
XmNlabelActivateCallback list:
typedef struct
{
XbaeReasonType reason;
XEvent *event;
int row;
int column;
Boolean row_label;
String label;
} XbaeMatrixLabelActivateCallbackStruct;
reason Set to XbaeLabelActivateReason.
event The event that invoked this callback.
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.
row_label If the button label that invoked the callback is a row label, then this value is set to
True. If it was a column label then it is set to False.
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;
XEvent *event;
int row, column;
String value;
Boolean doit;
} XbaeMatrixLeaveCellCallbackStruct;
reason Set to XbaeLeaveCellReason.
event The event that invoked this callback.
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 current
contents, then value should be set to point to a larger piece of allocated memory.
doit Indicates whether the edits applied to this cell should actually be stored into
XbaeMatrix. 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 application 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
following structure is passed to each callback on the XmNmodifyVerifyCallback list:
typedef struct
{
XbaeReasonType reason;
XEvent *event;
int row;
int column;
XmTextVerifyCallbackStruct *verify;
const char *prev_text;
} XbaeMatrixModifyVerifyCallbackStruct;
reason Set to XbaeModifyVerifyReason.
event Always set to NULL.
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 XmText(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 XmNprocessDragCallback list. A pointer to the following structure is passed to each callback on
the XmNprocessDragCallback list:
typedef struct
{
XbaeReasonType reason;
XEvent *event;
int row;
int column;
String string;
XbaeCellType type;
Pixmap pixmap;
Pixmap mask;
Cardinal num_params;
String *params;
} XbaeMatrixProcessDragCallbackStruct;
reason Set to XbaeProcessDragReason.
event The XEvent which invoked the ProcessDrag() action.
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 or
XbaeStringFree. This is provided as a convenience to the application.
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 application.
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 application.
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.
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;
XEvent *event;
int row;
int column;
Dimension width;
Dimension height;
} XbaeMatrixResizeCallbackStruct;
reason Set to XbaeResizeReason.
event Always set to NULL
row Set to the number of rows in the matrix (provided for convenience).
column Set to the number of columns in the matrix (provided for convenience).
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,
XmNvisibleColumns and XmNvisibleRows when the widget containing 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;
XEvent *event;
int row;
int column;
int which;
int columns;
short *column_widths;
} XbaeMatrixResizeColumnCallbackStruct;
reason Set to XbaeResizeColumnReason.
event The XEvent that ended the resize. The event will be of type XButtonReleasedEvent.
row The row in which the ResizeColumn() action began.
column The column in which the ResizeColumn() action began (and ended).
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.
The application can use the XmNresizeColumnCallback to perform post processing after a column has
been resized. By adjusting the values contained in column_widths the XbaeMatrix widget will use the
values upon return from the callback. Changing the number of columns in the matrix in the
XmNresizeColumnCallback should be used carefully as it may cause unexpected 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;
XEvent *event;
int row;
int column;
Boolean **selected_cells;
String **cells;
Cardinal num_params;
String *params;
} XbaeMatrixSelectCellCallbackStruct;
reason Set to XbaeSelectCellReason.
event The XEvent which invoked the SelectCell() action.
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 and will be NULL if no cells have yet been selected.
cells The value of the XmNcells resource. This is provided as a convenience to the application
and will be NULL if no cells have been specified or the XmNdrawCellCallback is being used.
num_params
The number of String parameters passed to the SelectCell() action.
params An array containing the num_params String parameters passed to the SelectCell() action.
The application can use the XmNselectCellCallback list to implement it's own selection model. The
XbaeMatrixSelectCellCallbackStruct 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 translation manager, and using String action parameters to distinguish them, the
application can implement various 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.
XmNtrackCellCallback
Callbacks on the XmNtrackCellCallback list are being called by the HandleTracking() action, which is
triggered by pointer motion. One of the purposes of this callback list is to figure out from which
cell to which cell the pointer is being moved. A pointer to the XbaeMatrixTrackCellCallbackStruct
structure is being passed. Its fields are defined as :
typedef struct _XbaeMatrixTrackCellCallbackStruct
{
XbaeReasonType reason;
XEvent *event;
int row, column;
int prev_row, prev_column;
Position pointer_x, pointer_y;
} XbaeMatrixTrackCellCallbackStruct;
reason Set to XbaeSelectCellReason.
event The XEvent which invoked the HandleTracking() action.
row This is the row number that the pointer is currently in.
column This is the column number that the pointer is currently in.
prev_row The row that the pointer was previously in.
prev_column
The column that the pointer was previously in.
pointer_x The x position of the pointer.
pointer_y The y position of the pointer.
XmNtraverseCellCallback
Callbacks on the XmNtraverseCellCallback list are called from the EditCell() action and when
XbaeMatrix receives or looses focus. 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;
XEvent *event;
int row;
int column;
int next_row;
int next_column;
int fixed_rows;
int fixed_columns;
int trailing_fixed_rows;
int trailing_fixed_columns;
int num_rows;
int num_columns;
String param;
XrmQuark qparam;
} XbaeMatrixTraverseCellCallbackStruct;
reason Set to XbaeTraverseCellReason.
event The event that invoked this callback.
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 application.
next_column
The column number of the next cell to be edited, this can be changed by the application.
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.
num_rows The value of the XmNrows resource. This is provided as a convenience for the application
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
application 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
XmNtraverseCellCallback 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 corresponding traversal results are:
Pointer Set next_row and next_column to the cell underneath the mouse pointer.
Left If we are currently editing cell (XmNfixedRows, XmNfixedColumns), then do not move.
Otherwise move one column to the left, if that column is less than XmNfixedColumns , 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.
Otherwise move one column to the right, if that column is greater than or equal to
XmNcolumns , then move down to column XmNfixedColumns 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 special parameters, it calculates the new cell to
be edited accordingly and stores the results in the next_row and next_column fields of the
XbaeMatrixTraverseCellCallbackStruct. If EditCell() 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 XmNtraverseCellCallback 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 corresponding new
calculation. It would do this by binding EditCell() with a new application specific parameter to an
event in a translation table. It is expected that application callbacks will use the XrmQuark
version of the parameter for efficiency reasons (by statically creating the new XrmQuarks and
comparing them against the incoming qparam).
When XbaeMatrix receives the focus it will also call the XmNtraverseCellCallback callbacks before
returning to the current cell or the upper left most visible cell if no cell is currently edited.
The XbaeMatrixTraverseCellCallbackStruct will have param and qparm set to Focus. If there is no
current cell row and column will be set to -1.
When XbaeMatrix looses the focus it will also call the XmNtraverseCellCallback with param and qparm
set to LoosingFocus.
XmNvalueChangedCallback
Callbacks on the XmNvalueChangedCallback list are called while a cell is being edited. The callbacks
are called after text is inserted into or deleted from the TextField edit widget. A pointer to the
following structure is passed to each callback on the XmNvalueChangedCallback list:
typedef struct
{
XbaeReasonType reason;
XEvent *event;
int row;
int column;
} XbaeMatrixValueChangedCallbackStruct;
reason Set to XbaeValueChangedReason.
event The event that triggered this callback.
row The row number of the cell being edited.
column The column number of the cell being edited.
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;
XEvent *event;
int row;
int column;
XbaeCellType type;
String string;
Pixmap pixmap;
Pixmap mask;
} XbaeMatrixWriteCellCallbackStruct;
reason Set to XbaeWriteCellReason.
event Always set to NULL
row The row number of the cell that needs to be written.
column The column 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. (maybe a little meaningless unless you
can edit a pixmap in a cell)
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 XbaeMatrix is editable and has been assigned an
XmNdrawCellCallback, 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.
Translations
XbaeMatrix inherits translations from XmManager. In addition, XbaeMatrix uses the following translation:
:<Btn1Up>: DefaultAction()\n\
:<Btn1Down>: DefaultAction() EditCell(Pointer)\n\
:Shift<Btn2Down>: ResizeColumns()\n\
:<Btn2Down>: ProcessDrag()\n\
:<Btn1Motion>: HandleMotion() HandleTracking()()\n\
:<Motion>: HandleTracking()()\n\
:<Btn4Down>: ScrollRows(-50)()\n<Btn5Down>:
XbaeMatrix installs the following default XmNtextTranslations on the TextField edit widget:
#override\n\
Shift ~Ctrl ~Meta ~Alt <Key>Tab: EditCell(Left)\n\
~Ctrl ~Meta ~Alt <Key>Tab: EditCell(Right)\n\
<Key>osfUp: EditCell(Up)\n\
<Key>osfDown: EditCell(Down)\n\
<Key>osfActivate: CommitEdit(False)\n\
~Shift ~Meta ~Alt <Key>Return: CommitEdit(False)\n\
<Key>osfCancel: CommitEdit(False)\n\
Shift Ctrl ~Meta ~Alt <Key>Tab: TraversePrev()\n\
Ctrl ~Meta ~Alt <Key>Tab: TraverseNext()\n\
<Key>osfPageDown: PageDown()\n\
<Key>osfPageUp: PageUp()\n
Action Routines
CancelEdit()
If the single parameter to CancelEdit() is the String True, then it unmaps the edit TextField,
discarding any changes which were made to the cell being edited. If the parameter is False, then
CancelEdit() restores the edit TextField to the original contents of the cell, discarding any
changes made to the cell being edited. The TextField is not unmapped.
CommitEdit()
CommitEdit() first calls any callbacks on the XmNleaveCellCallback list to determine if the
changes made to the current cell are valid. If they are, it then saves any changes made to the
cell into the cell. If the callbacks on the XmNleaveCellCallback list return that the changes are
not valid, CommitEdit() does nothing.
If the changes are valid, CommitEdit() examines it's one parameter, which must be the string True
or False. If the parameter is True, then the edit TextField is unmapped. If it is False, then the
TextField is not unmapped.
DefaultAction()
DefaultAction() sets up a mechanism for determining whether two successive mouse clicks form a
double click. The DefaultAction() should normally be used in conjunction with other pointer based
events and provides a mechanism for acting on double clicks in a cell.
EditCell()
EditCell() edits a new cell. EditCell() first calculates the new cell to edit based on it's single
parameter. It then calls the callbacks on the XmNtraverseCellCallback list to allow them to
specify a different cell to edit (see the discussion of XmNtraverseCellCallback above).
EditCell() then calls the callbacks on the XmNleaveCellCallback list to determine if the changes
made to the current cell are valid. If they are, it then saves any changes made to the cell into
the cell. If the changes are not valid, EditCell() does nothing further.
If the changes are valid, EditCell() attempts to scroll the new cell to be edited so that it is
fully visible. If the new cell is in a fixed row or column, EditCell() returns and does nothing
further (these cells are not editable). Otherwise, EditCell() calls the callbacks on the
XmNenterCellCallback list to determine if the new cell is editable. It then moves the XmText edit
widget to the new cell, setting it's editability based on the return from the XmNenterCellCallback
callbacks.
ProcessDrag()
ProcessDrag() calls the callbacks on the XmNprocessDragCallback list, passing them a pointer to a
XbaeMatrixProcessDragCallbackStruct.
ResizeColumns()
Allows the user to dynamically resize the column widths, provided that XmNallowColumnResize is
True.
ScrollRows()
ScrollRows() makes the rows of the matrix scroll by the pixel amount specified by it's argument.
ScrollColumns()
ScrollColumns() makes the columns of the matrix scroll by the pixel amount specified by it's
argument.
SelectCell()
SelectCell() calls the callbacks on the XmNselectCellCallback list, passing them a pointer to a
XbaeMatrixSelectCellCallbackStruct. This structure will contain the String parameters passed to
the SelectCell() action, among other things (see the discussion of XmNselectCellCallback above).
TraverseNext()
TraverseNext() will traverse out of the Matrix and into the next tab group.
TraversePrev()
TraversePrev() will traverse out of the Matrix and into the previous tab group.
PageDown()
PageDown() causes the Matrix to scroll down a full page. The text widget is placed on the first
non fixed row of the new page.
PageUp()
PageUp() causes the Matrix to scroll up a full page. The text widget is placed on the first non
fixed row of the new page.
Type Converters
In addition to the standard type converters registered by Xt and Motif, XbaeMatrix registers the
following additional type converters:
CvtStringToStringArray()
Converts a comma separated list of Strings to an array of String pointers, one for each substring.
Commas in the list may be escaped with the character `\'. This converter allows the XmNrowLabels
and XmNcolumnLabels resources to be specified in resource files.
CvtStringToWidthArray()
Converts a comma separated list of numeric Strings to an array of short integers. This converter
allows the XmNcolumnWidths resource to be specified in resource files.
CvtStringToMaxLengthArray()
Converts a comma separated list of numeric Strings to an array of integers. This converter allows
the XmNcolumnMaxLengths resource to be specified in resource files.
CvtStringToAlignmentArray()
Converts a comma separated list of alignments to an array of unsigned chars. This converter allows
the XmNcolumnLabelAlignments and XmNcolumnAlignments resources to be specified in resource files.
CvtStringToGridType()
Converts a single string as discussed in XmNgridType to a grid type value. This converter allows
XmNgridType to be specified in resource files.
CvtStringToMatrixScrollBarDisplayPolicy()
Converts a single string as discussed in XmNhorizontalScrollBarDisplayPolicy and
XmNverticalScrollBarDisplayPolicy to a display policy value. This converter allows
XmNhorizontalScrollBarDisplayPolicy and XmNverticalScrollBarDisplayPolicy to be specified in
resource files.
CvtStringToCellTable()
Converts a comma separated list of Strings with \n delimited rows to a two dimensional array of
String pointers. This converter allows the XmNcells resource to be specified in resource files.
CvtStringToPixelTable()
Converts a comma separated list of color names with \n delimited rows to a two dimensional array
of Pixel values. This converter allows the XmNcellBackgroundsandXmNcolors resources to be
specified in resource files.
CvtStringToBooleanArray()
Converts a comma separated list of string or numeric values to an array of Booleans. The
converter recongnises a comma separated list of values. Each value is parsed such that if the
first character is This converter allows the XmNcolumnButtonLabels and XmNrowButtonLabels
resources to be specified in resource files.
Public Functions
The following external entry points to XbaeMatrix class methods are defined:
XbaeCreateMatrix()
Widget XbaeCreateMatrix()
Widget parent;
String name;
ArgList arglist;
Cardinal argcount;
parent Specifies the parent widget ID.
name Specifies the name of the created widget
arglist Specifies the argument list
argcount Specifies the number of attribute/value pairs in the argument list (arglist)
XbaeCreateMatrix() creates an unmanaged instance of an XbaeMatrix widget and returns the
associated widget ID.
XbaeMatrixAddColumns()
void XbaeMatrixAddColumns()
Widget w;
int position;
String *columns;
String *labels;
short *widths;
int *max_lengths;
unsigned char *alignments;
unsigned char *label_alignments;
Pixel *colors;
int num_columns;
w An XbaeMatrix widget.
position The column position before which to add the new columns. Must be greater than or equal
to zero, and less than or equal to XmNcolumns.
columns Points to an ordinary two dimensional array of String, or NULL. These Strings will be
used to modify the XmNcells resource to populate the new columns. Each row in the array
must have XmNrows elements and represents one of the new columns. columns must have
num_columns rows. If columns is NULL, empty columns will be added.
labels Points to an array of String, or NULL. These Strings will be used as the
XmNcolumnLabels for the new columns. The labels array must have num_columns elements. If
labels is NULL, and XmNcolumnLabels is set, then blank column labels will be used.
widths Points to an array of short or NULL. These values will be used as the XmNcolumnWidths
for the new columns. The widths array must have num_columns elements. if widths is NULL
then a default width will be used for the new columns.
max_lengths
Points to an array of int, or NULL. These values will be used as the
XmNcolumnMaxLengths for the new columns. The max_lengths array must have num_columns
elements. If max_lengths is NULL, then the corresponding value from widths will be used.
alignments
Points to an array of unsigned char, or NULL. These values will be used as the
XmNcolumnAlignments for the new columns. The alignments array must have num_columns
elements. If alignments is NULL, then XmALIGNMENT_BEGINNING will be used.
label_alignments
Points to an array of unsigned char, or NULL. These values will be used as the
XmNcolumnLabelAlignments for the new column labels. The label_alignments array must
have num_columns elements. If label_alignments is NULL, then XmALIGNMENT_BEGINNING will
be used.
colors Points to an array of Pixel, or NULL. These values will be used to set the
corresponding columns in the XmNcolors table for the new columns. The colors array must
have num_columns elements. If colors is NULL, then XmNforeground will be used.
num_columns
The number of columns which are being added to the widget.
XbaeMatrixAddColumns() allows the application developer to dynamically add new columns anywhere in
the Matrix. The columns will be added before the column specified in position. Columns are
numbered starting at zero. To append new columns onto the end of the Matrix, specify position as
the total number of columns. Most of the arguments to XbaeMatrixAddColumns() may be specified as
NULL. Default values will be used by the widget.
If the programmer attempts to add columns using XbaeMatrixAddColumns() when there are no rows, it
will result in a warning message. There must be at least one row in the XbaeMatrix widget to add
columns.
To maintain backward compatibility, the cell backgrounds cannot be set in a call to
XbaeMatrixAddColumns() and must be set (if so desired) in a separate call to XtVaSetValues().
XbaeMatrixAddRows()
void XbaeMatrixAddRows()
Widget w;
int position;
String *rows;
String *labels;
Pixel *colors;
int num_rows;
w An XbaeMatrix widget.
position The row position before which to add the new rows. Must be greater than or equal to
zero, and less than or equal to XmNrows.
rows Points to an ordinary two dimensional array of String, or NULL. These Strings will be
used to modify the XmNcells resource to populate the new rows. Each row in the array
must have XmNcolumns elements and represents one of the new rows. rows must have
num_rows rows. If rows is NULL, empty rows will be added.
labels Points to an array of String, or NULL. These Strings will be used as the XmNrowLabels
for the new rows. The labels array must have num_rows elements. If labels is NULL, and
XmNrowLabels is set, then blank row labels will be used
colors Points to an array of Pixel, or NULL. These values will be used to set the
corresponding rows in the XmNcolors table for the new rows. The colors array must have
num_rows elements. If colors is NULL, then XmNforeground will be used.
num_rows The number of rows which are being added to the widget.
XbaeMatrixAddRows() allows the application developer to dynamically add new rows anywhere in the
Matrix. The rows will be added before the row specified in position. Rows are numbered starting at
zero. To append new rows onto the end of the Matrix, specify position as the total number of rows.
To maintain backward compatibility, the cell backgrounds cannot be set in a call to
XbaeMatrixAddRows() and must be set (if so desired) in a separate call to XtVaSetValues().
XbaeMatrixCancelEdit()
void XbaeMatrixCancelEdit()
Widget w;
Boolean unmap;
w An XbaeMatrix widget.
unmap Specifies whether the TextField cell edit widget should be unmapped after the edit is
canceled.
XbaeMatrixCancelEdit() allows the application developer to programmatically cancel a cell edit in
progress, discarding any changes made by the user. This function unmaps the TextField edit widget
if the unmap flag is True. If unmap is False, the contents of the TextField are restored to their
original value, and the TextField is not unmapped.
XbaeMatrixCommitEdit()
Boolean XbaeMatrixCommitEdit()
Widget w;
Boolean unmap;
w An XbaeMatrix widget.
unmap Specifies whether the TextField cell edit widget should be unmapped after an edit is
successfully committed.
XbaeMatrixCommitEdit() can be used by the application developer to programmatically commit an
edit, saving any changes made by the user. This will cause the callbacks on the
XmNleaveCellCallback list to be called to verify that the changes the user made are valid. If the
changes are valid, then they are saved into the cell and if the unmap flag is True, the TextField
widget will be unmapped.
XbaeMatrixDeleteColumns()
void XbaeMatrixDeleteColumns()
Widget w;
int position;
int num_columns;
w An XbaeMatrix widget.
position The column position at which to begin deleting columns. Must be greater than or equal to
zero, and (position + num_columns) must be less than or equal to XmNcolumns.
num_columns
The number of columns to delete from the widget.
XbaeMatrixDeleteColumns() allows the application developer to dynamically delete columns from
anywhere in the Matrix. Columns will be deleted starting at the column specified by position.
XbaeMatrixDeleteRows()
void XbaeMatrixDeleteRows()
Widget w;
int position;
int num_rows;
w An XbaeMatrix widget.
position The row position at which to begin deleting rows. Must be greater than or equal to zero,
and (position + num_rows) must be less than or equal to XmNrows.
num_rows The number of rows to delete from the widget.
XbaeMatrixDeleteRows() allows the application developer to dynamically delete rows from anywhere
in the Matrix. Rows will be deleted starting at the row specified by position.
XbaeMatrixDeselectAll()
void XbaeMatrixDeselectAll()
Widget w;
w An XbaeMatrix widget.
XbaeMatrixDeselectAll() allows the application developer to programmatically deselect all cells.
XbaeMatrixDeselectAll() redraws the cells in normal video. All Booleans in the XmNselectedCells
array will be set to False.
XbaeMatrixDeselectCell()
void XbaeMatrixDeselectCell()
Widget w;
int row;
int column;
w An XbaeMatrix widget.
row The row of the cell to deselect.
column The column of the cell to deselect.
XbaeMatrixDeselectCell() allows the application developer to programmatically deselect a cell.
XbaeMatrixDeselectCell() redraws the cell in normal video. The corresponding Boolean in the
XmNselectedCells array will be set to False.
XbaeMatrixDeselectColumn()
void XbaeMatrixDeselectColumn()
Widget w;
int column;
w An XbaeMatrix widget.
column The column to deselect.
XbaeMatrixDeselectColumn() allows the application developer to programmatically deselect a column.
XbaeMatrixDeselectColumn() draws the column in normal video. The corresponding Booleans in the
XmNselectedCells array will be set to False.
XbaeMatrixDeselectRow()
void XbaeMatrixDeselectRow()
Widget w;
int row;
w An XbaeMatrix widget.
row The row to deselect.
XbaeMatrixDeselectRow() allows the application developer to programmatically deselect a row.
XbaeMatrixDeselectRow() draws the row in reverse video (or selectedForeground / selectedBackground
if set). The corresponding Booleans in the XmNselectedCells array will be set to False.
XbaeMatrixDisableRedisplay()
int XbaeMatrixDisableRedisplay()
Widget w;
w An XbaeMatrix widget.
XbaeMatrixDisableRedisplay() and XbaeMatrixEnableRedisplay() allow an application to make multiple
changes to a matrix without immediate visual updates. When multiple changes are made with
redisplay enabled, visual flashing often occurs. These routines help eliminate this problem.
XbaeMatrixEditCell()
void XbaeMatrixEditCell()
Widget w;
int row;
int column;
w An XbaeMatrix widget.
row The row of the cell to be edited.
column The column of the cell to be edited.
XbaeMatrixEditCell()
allows the application developer to programmatically force a specific cell to be edited. This
function will first attempt to commit the edit in the current cell. If the XmNleaveCellCallback
callbacks disallow this commit, then XbaeMatrixEditCell() will return. Otherwise the specified
cell is scrolled until it is visible. If the specified cell is in a fixed row or column, it cannot
be edited and XbaeMatrixEditCell() will return. Next, the callbacks on the XmNenterCellCallback
callback list are called for the specified cell to determine it's editability. Then the TextField
edit widget is mapped on top of the specified cell.
XbaeMatrixEnableRedisplay()
int XbaeMatrixEnableRedisplay()
Widget w;
Boolean redisplay;
w An XbaeMatrix widget.
redisplay Force the matrix to redisplay if True and no other calls to XbaeMatrixDisableRedisplay()
have been made.
XbaeMatrixDisableRedisplay() and XbaeMatrixEnableRedisplay() allow an application to make multiple
changes to a matrix without immediate visual updates. When multiple changes are made with
redisplay enabled, visual flashing often occurs. These routines help eliminate this problem.
XbaeMatrixEventToXY()
Boolean XbaeMatrixEventToXY()
Widget w;
XEvent *event;
int *x;
int *y;
w An XbaeMatrix widget.
event An X event structure pointer, usually from an XEventHandler function.
x The translated x coordinate.
y The translated y coordinate.
XbaeMatrixEventToXY enables the programmer to determine the x and y values of a given event with
respect to the XbaeMatrix widget. The returned values are also adjusted to allow for the XbaeClip
widget.
XbaeMatrixFirstSelectedCell()
void XbaeMatrixFirstSelectedCell()
Widget w;
int *row;
int *column;
w An XbaeMatrix widget.
row The first selected row.
column The first selected column.
XbaeMatrixFirstSelectedCell() allows the application developer to find out which cell is the first
selected. The function traverses the XbaeMatrix widget in a left to right, top to bottom manner
to determine this value. If no cell is selected, row and column are set to -1.
XbaeMatrixFirstSelectedColumn()
int XbaeMatrixFirstSelectedColumn()
Widget w;
w An XbaeMatrix widget.
XbaeMatrixFirstSelectedColumn() returns the column number of the first selected column in the
XbaeMatrix widget. The function traverses the matrix from column 0. A column must be entirely
selected for the column to be considered selected. If no column is selected then -1 is returned.
XbaeMatrixFirstSelectedRow()
int XbaeMatrixFirstSelectedRow()
Widget w;
w An XbaeMatrix widget.
XbaeMatrixFirstSelectedRow() returns the row number of the first selected row in the XbaeMatrix
widget. The function traverses the matrix from row 0. A row must be entirely selected for the
row to be considered selected. If no row is selected then -1 is returned.
XbaeMatrixGetCell()
String XbaeMatrixGetCell()
Widget w;
int row;
int column;
w An XbaeMatrix widget.
row The row of the cell whose value should be retrieved.
column The column of the cell whose value should be retrieved.
XbaeMatrixGetCell() returns the String value stored in the specified cell. This String should not
be freed. To examine many cells, it is more efficient to do an XtGetValues() on XmNcells and
examine the values in that array.
XbaeMatrixGetCellBackground()
Pixel XbaeMatrixGetCellBackground()
Widget w;
int row;
int column;
w A XbaeMatrix widget.
row The row of the cell whose background color should be retrieved.
column The column of the cell whose background color should be retrieved.
XbaeMatrixGetCellColor()
Pixel XbaeMatrixGetCellColor()
Widget w;
int row;
int column;
w A XbaeMatrix widget.
row The row of the cell whose foreground color should be retrieved.
column The column of the cell whose foreground color should be retrieved.
XbaeMatrixGetCellPixmap()
int XbaeMatrixGetCellPixmap()
Widget w;
int row;
int column;
Pixmap *pixmap;
Pixmap *mask;
w A XbaeMatrix widget.
row The row of the cell whose pixmap and mask should be retrieved.
column The column of the cell whose pixmap and mask should be retrieved.
pixmap A pointer to a Pixmap variable, in which the function will store the cell's pixmap.
mask A pointer to a Pixmap variable, in which the function will store the cell's pixmap mask.
XbaeMatrixGetCellTag()
XmStringTag XbaeMatrixGetCellTag()
Widget w;
int row;
int column;
w A XbaeMatrix widget.
row The row of the cell whose tag should be retrieved.
column The column of the cell tag should be retrieved.
XbaeMatrixGetCellTag returns the font tag of the indicated cell. The application should not modify
or free the returned value.
XbaeMatrixGetCellUserData()
XtPointer XbaeMatrixGetCellUserData()
Widget w;
int row;
int column;
w An XbaeMatrix widget.
row The row of the cell whose data should be retrieved.
column The column of the cell whose data should be retrieved.
XbaeMatrixGetCellUserData() returns a pointer to the data assigned to the cell in the given
coordinates. The data should be set using XbaeMatrixSetCellUserData(). If no data is found to be
associated with the particular cell, NULL is returned.
XbaeMatrixGetColumnWidth()
int XbaeMatrixGetColumnWidth()
Widget w;
int column;
w An XbaeMatrix widget.
column The column whose width we're querying.
XbaeMatrixGetColumnWidth() is a convenient way to query a column width.
XbaeMatrixGetColumnLabel()
String XbaeMatrixGetColumnLabel()
Widget w;
int column;
w An XbaeMatrix widget.
column The column of the label that should be retrieved.
XbaeMatrixGetColumnLabel() returns a pointer to the label of the given column. If no column
labels exist or the given column is not a valid column NULL is returned. If no data is found to
be associated with the particular column, NULL is returned.
XbaeMatrixGetColumnUserData()
XtPointer XbaeMatrixGetColumnUserData()
Widget w;
int column;
w An XbaeMatrix widget.
column The column of the cell whose data should be retrieved.
XbaeMatrixGetColumnUserData() returns a pointer to the data assigned to the given column. The
data should be set using XbaeMatrixSetColumnUserData(). If no data is found to be associated with
the particular column, NULL is returned.
XbaeMatrixGetCurrentCell()
void XbaeMatrixGetCurrentCell()
Widget w;
int *row;
int *column;
w An XbaeMatrix widget.
row The row of the cell the ``cursor'' or TextField is in.
column The column of the cell the ``cursor'' or TextField is in.
XbaeMatrixGetCurrentCell() allows the application developer to determine what cell is being edited
or has focus.
XbaeMatrixGetEventRowColumn()
int XbaeMatrixGetEventRowColumn()
Widget w;
XEvent *event;
int *row;
int *column;
w An XbaeMatrix widget.
event An X event structure pointer. This is usually from an XEventHandler function. It can
be either a button or a key event.
row The row of the cell the ``cursor'' or TextField is in.
column The column of the cell the ``cursor'' or TextField is in.
XbaeMatrixGetEventRowColumn() allows the application developer to determine what cell corresponds
to an (x, y) in an event. If the (x, y) of the event is a legal cell, row and column are set and
True is returned. However, if the (x, y) is not over a cell, False is returned, and row and
column will have undefined values.
XbaeMatrixGetNumSelected()
int XbaeMatrixGetNumSelected()
Widget w;
w An XbaeMatrix widget.
XbaeMatrixGetNumSelected() returns the number of cells that are currently selected in the given
matrix. The widget maintains an internal variable as cells are selected and deselected so a
complete traversal of the widget is avoided.
XbaeMatrixGetRowHeight()
int XbaeMatrixGetRowHeight()
Widget w;
int row;
w An XbaeMatrix widget.
row The row whose height we query.
XbaeMatrixGetRowHeight() is a convenient way to query a row height.
XbaeMatrixGetRowLabel()
String XbaeMatrixGetRowLabel()
Widget w;
int row;
w An XbaeMatrix widget.
row The row of the label that should be retrieved.
XbaeMatrixGetRowLabel() returns a pointer to the label of the given row. If no row labels exist
or the given row is not a valid row NULL is returned.
XbaeMatrixGetRowUserData()
XtPointer XbaeMatrixGetRowUserData()
Widget w;
int row;
w An XbaeMatrix widget.
row The row of the cell whose data should be retrieved.
XbaeMatrixGetRowUserData() returns a pointer to the data assigned to the given row. The data
should be set using XbaeMatrixSetRowUserData(). If no data is found to be associated with the
particular row, NULL is returned.
XbaeMatrixGetXmColumnLabel()
XmString XbaeMatrixGetXmColumnLabel()
Widget w;
int column;
w An XbaeMatrix widget.
column The column of the xmLabel that should be retrieved.
XbaeMatrixGetXmColumnLabel() returns a pointer to the xmLabel of the given column. If no
xmColumnLabels exist or the given column is not a valid column NULL is returned. If no data is
found to be associated with the particular column, NULL is returned.
XbaeMatrixGetXmRowLabel()
XmString XbaeMatrixGetXmRowLabel()
Widget w;
int row;
w An XbaeMatrix widget.
row The row of the xmLabel that should be retrieved.
XbaeMatrixGetXmRowLabel() returns a pointer to the xmLabel of the given row. If no xmRowLabels
exist or the given row is not a valid row NULL is returned. If no data is found to be associated
with the particular row, NULL is returned.
XbaeMatrixHighlightCell()
void XbaeMatrixHighlightCell()
Widget w;
int row;
int column;
w An XbaeMatrix widget.
row The row of the cell to highlight.
column The column of the cell to highlight.
XbaeMatrixHighlightCell() allows the application developer to programmatically highlight a cell.
XbaeMatrixHighlightCell() draws the highlight around the cell. The corresponding unsigned char in
the XmNhighlightedCells array will be have its HighlightCell bit set.
XbaeMatrixHighlightColumn()
void XbaeMatrixHighlightColumn()
Widget w;
int column;
w An XbaeMatrix widget.
column The column to highlight.
XbaeMatrixHighlightColumn() allows the application developer to programmatically highlight a
column. XbaeMatrixHighlightColumn() draws the highlight around the column if XmNgridType is
XmGRID_COLUMN_SHADOW or from around each cell in the column otherwise. The corresponding unsigned
chars in the XmNhighlightedCells array will be have its HighlightColumn or HighlightOther bit set,
depending on whether XmNgridType is set to XmGRID_COLUMN_SHADOW or not.
XbaeMatrixHighlightRow()
void XbaeMatrixHighlightRow()
Widget w;
int row;
w An XbaeMatrix widget.
row The row to highlight.
XbaeMatrixHighlightRow() allows the application developer to programmatically highlight a row.
XbaeMatrixHighlightRow() draws the highlight around the row if XmNgridType is XmGRID_ROW_SHADOW or
from around each cell in the row otherwise. The corresponding unsigned chars in the
XmNhighlightedCells array will be have its HighlightRow or HighlightOther bit set, depending on
whether XmNgridType is set to XmGRID_ROW_SHADOW or not.
XbaeMatrixIsCellSelected()
Boolean XbaeMatrixIsCellSelected()
Widget w;
int row;
int column;
w An XbaeMatrix widget.
row The row of the cell to check.
column The column of the cell to check.
XbaeMatrixIsCellSelected() allows the application developer to determine whether or not a
particular cell is selected. The function returns True if the cell is selected and False
otherwise.
XbaeMatrixIsCellVisible()
Boolean XbaeMatrixIsCellVisible()
Widget w;
int row;
int column;
w An XbaeMatrix widget.
row The row of the cell to check.
column The column of the cell to check.
XbaeMatrixIsCellVisible() allows the application developer to determine whether or not a
particular cell is in the visible area of the XbaeMatrix widget. The function returns True if the
cell is visible and False otherwise.
XbaeMatrixIsColumnSelected()
Boolean XbaeMatrixIsColumnSelected()
Widget w;
int column;
w An XbaeMatrix widget.
column The column of the matrix to check.
XbaeMatrixIsColumnSelected() allows the application developer to determine whether or not a
particular column is selected. The function returns True if the column is selected and False
otherwise. A column must be selected in its entirety for XbaeMatrixIsColumnSelected() to return
True.
XbaeMatrixIsColumnVisible()
Boolean XbaeMatrixIsColumnVisible()
Widget w;
int column;
w An XbaeMatrix widget.
column The column of the matrix to check.
XbaeMatrixIsColumnVisible() allows the application developer to determine whether or not a
particular column is in the visible area of the XbaeMatrix widget. The function returns True if
the column is visible and False otherwise.
XbaeMatrixIsRowSelected()
Boolean XbaeMatrixIsRowSelected()
Widget w;
int row;
w An XbaeMatrix widget.
row The row of the matrix to check.
XbaeMatrixIsRowSelected() allows the application developer to determine whether or not a
particular row is selected. The function returns True if the row is selected and False otherwise.
A row must be selected in its entirety for XbaeMatrixIsRowSelected() to return True.
XbaeMatrixIsRowVisible()
Boolean XbaeMatrixIsRowVisible()
Widget w;
int row;
w An XbaeMatrix widget.
row The row of the matrix to check.
XbaeMatrixIsRowVisible() allows the application developer to determine whether or not a particular
row is in the visible area of the XbaeMatrix widget. The function returns True if the row is
visible and False otherwise.
XbaeMatrixMakeCellVisible()
int XbaeMatrixMakeCellVisible()
Widget w;
int row;
int column;
w An XbaeMatrix widget.
row The row to scroll into the visible area of the matrix.
column The column to scroll into the visible area of the matrix.
XbaeMatrixMakeCellVisible() allows a cell to be programmatically scrolled into the visible area of
the XbaeMatrix widget. By calling this function, the XmNselectScrollVisible resource is ignored.
For a more accurate cell location after scrolling, the programmer should use the
XmNleftColumnandXmNtopRow resources.
XbaeMatrixNumRows()
int XbaeMatrixNumRows()
Widget w;
w An XbaeMatrix widget.
XbaeMatrixNumRows() returns the number of rows in the given matrix.
XbaeMatrixNumColumns()
int XbaeMatrixNumColumns()
Widget w;
w An XbaeMatrix widget.
XbaeMatrixNumColumns() returns the number of columns in the given matrix.
XbaeMatrixNumRows()
int XbaeMatrixNumRows()
Widget w;
w An XbaeMatrix widget.
XbaeMatrixNumRows() returns the number of rows in the given matrix.
XbaeMatrixRefresh()
void XbaeMatrixRefresh()
Widget w;
w An XbaeMatrix widget.
XbaeMatrixRefresh() allows the application developer to force the widget to redraw itself. This
might be used when the programmer knows the widget's values have changed, but the widget has not
detected the change. For example, the quickest way to swap the values of 2 rows would be to do an
XtGetValues on XmNcells, swap the values of the 2 rows, and then do an XtSetValues on XmNcells
with the same StringTable variable. Because of the way the Intrinsics work, the widget will not
see this change and will display the old values until a redraw is preformed because of a resize or
scroll event (assuming no other change in the XtSetValues caused a redraw). Calling
XbaeMatrixRefresh() will cause the correct values to be drawn and overcome this limitation in the
Intrinsics. While this function should rarely be needed, it is provided ``just in case''.
XbaeMatrixRefreshCell()
void XbaeMatrixRefreshCell()
Widget w;
int row;
int column;
w An XbaeMatrix widget.
row The row of the cell to redraw.
column The column of the cell to redraw.
XbaeMatrixRefreshCell() allows the application developer to redraw a specific cell of the matrix.
This function is particularly useful when used with the XbaeMatrixDrawCellCallback as it allows
updates of the data without an explicit expose event.
XbaeMatrixRefreshColumn()
void XbaeMatrixRefreshColumn()
Widget w;
int column;
w An XbaeMatrix widget.
column The column of the matrix to redraw.
XbaeMatrixRefreshColumn() allows the application developer to efficiently redraw a specific column
of the matrix.
XbaeMatrixRefreshRow()
void XbaeMatrixRefreshRow()
Widget w;
int row;
w An XbaeMatrix widget.
row The row of the matrix to redraw.
XbaeMatrixRefreshRow() allows the application developer to efficiently redraw a specific row
of the matrix.
XbaeMatrixRowColToXY()
int XbaeMatrixRowColToXY()
Widget w;
int row;
int column;
int *x;
int *y;
w An XbaeMatrix widget.
row The row the of the cell in question.
column The column the of the cell in question.
x The x coordinate returned that represents the left coordinates of the given cell.
y The y coordinate returned that represents the upper coordinates of the given cell.
XbaeMatrixRowColToXY() allows the application developer to determine the coordinates of the upper
left corner of a given cell. If the given widget is not an XbaeMatrix widget, False will be
returned and the values of x and y will be undefined. This function is useful for drag and drop
calculations.
XbaeMatrixSelectAll()
void XbaeMatrixSelectAll()
Widget w;
w An XbaeMatrix widget.
XbaeMatrixSelectAll() allows the application developer to programmatically select all cells.
XbaeMatrixSelectAll() redraws the cells in reverse video. All Booleans in the XmNselectedCells
array will be set to True.
XbaeMatrixSelectCell()
void XbaeMatrixSelectCell()
Widget w;
int row;
int column;
w An XbaeMatrix widget.
row The row of the cell to select.
column The column of the cell to select.
XbaeMatrixSelectCell() allows the application developer to programmatically select a cell.
XbaeMatrixSelectCell() first scrolls the specified cell until it is visible, and then draws the
cell in reverse video (or selectedForeground / selectedBackground if set).
The corresponding Boolean in the XmNselectedCells array will be set to True.
XbaeMatrixSelectColumn()
void XbaeMatrixSelectColumn()
Widget w;
int column;
w An XbaeMatrix widget.
column The column to select.
XbaeMatrixSelectColumn() allows the application developer to programmatically select a column.
XbaeMatrixSelectColumn() first scrolls the specified column until it is visible, and then draws
the column in reverse video (or selectedForeground / selectedBackground if set). The
corresponding Booleans in the XmNselectedCells array will be set to True.
XbaeMatrixSelectRow()
void XbaeMatrixSelectRow()
Widget w;
int row;
w An XbaeMatrix widget.
row The row to select.
XbaeMatrixSelectRow() allows the application developer to programmatically select a row.
XbaeMatrixSelectRow() first scrolls the specified row until it is visible, and then draws the row
in reverse video (or selectedForeground / selectedBackground if set). The corresponding Booleans
in the XmNselectedCells array will be set to True.
XbaeMatrixSetCell()
void XbaeMatrixSetCell()
Widget w;
int row;
int column;
const String value;
w An XbaeMatrix widget.
row The row of the cell whose value should be set.
column The column of the cell whose value should be set.
value The new value to set this cell to.
XbaeMatrixSetCell() allows the application developer to programmatically set the value of the
specified cell. To set the values of many cells, it may be more efficient to do an XtSetValues()
on the XmNcells resource.
XbaeMatrixSetCellBackground()
void XbaeMatrixSetCellBackground()
Widget w;
int row;
int column;
Pixel color;
w An XbaeMatrix widget.
row The row of the cell whose backgroundshould be set.
column The column of the cell whose background should be set.
color The new color to which to set this cell's background.
XbaeMatrixSetCellBackground() is a convenient way to specify and modify the XmNcellBackgrounds
resource when changing the background of a single cell. If XmNcellBackgrounds is NULL, then
XbaeMatrixSetCellBackground() will create a Pixel table initialized to XmNforeground except for
the cell specified in it's arguments. If XmNcellBackgrounds is not NULL, then
XbaeMatrixSetCellBackground() will changed the specified cell in that resource to the specified
color.
XbaeMatrixSetCellColor()
void XbaeMatrixSetCellColor()
Widget w;
int row;
int column;
Pixel color;
w An XbaeMatrix widget.
row The row of the cell whose color should be set.
column The column of the cell whose color should be set.
color The new color to which to set this cell.
XbaeMatrixSetCellColor() is a convenient way to specify and modify the XmNcolors resource when
changing the color of a single cell. If XmNcolors is NULL, then XbaeMatrixSetCellColor() will
create a Pixel table initialized to XmNforeground except for the cell specified in it's arguments.
If XmNcolors is not NULL, then XbaeMatrixSetCellColor() will changed the specified cell in that
resource to the specified color.
XbaeMatrixSetCellPixmap()
void XbaeMatrixSetCellPixmap()
Widget w;
int row;
int column;
Pixmap pixmap;
Pixmap mask;
w A XbaeMatrix widget.
row The row of the cell whose pixmap and mask should be set.
column The column of the cell whose pixmap and mask should be set.
pixmap the function will store the contents of this Pixmap variable
mask the function will store the contents of this variable as the pixmap mask
XbaeMatrixSetCellPixmap will set the pixmap and the associated mask of the indicated cell. If the
row or column are out of bounds, or the widget is not an XbaeMatrix widget, then nothing is
changed; this erroneous condition is silently ignored.
XbaeMatrixSetCellShadow()
void XbaeMatrixSetCellShadow()
Widget w;
int row;
int column;
unsigned char shadow_type;
w An XbaeMatrix widget.
row The row of the cell whose shadow should be set.
column The column of the cell whose shadow should be set.
shadow_type
The value to which to set the cells shadow
XbaeMatrixSetShadow() allows the application developer to programmatically set the shadow of a
specified cell.
XbaeMatrixSetCellTag()
void XbaeMatrixSetCellTag()
Widget w;
int row;
int column;
XmStringTag tag;
w An XbaeMatrix widget.
row The row of the cell whose tag should be set.
column The column of the cell whose tag should be set.
tag The value to which to set the cells tag
XbaeMatrixSetTag() allows the application developer to programmatically set the font tag of a
specified cell. This value is copied (quarkified).
XbaeMatrixSetCellUserData()
void XbaeMatrixSetCellUserData()
Widget w;
int row;
int column;
XtPointer data;
w An XbaeMatrix widget.
row The row of the cell whose value should be set.
column The column of the cell whose value should be set.
data A pointer to a user defined data area.
XbaeMatrixSetCellUserData() allows the application developer to programmatically set the user data
of a specified cell. To set the data value of many cells, it may be more efficient to do an
XtSetValues() on the XmNcellUserData resource. This resource is copied.
XbaeMatrixSetCellWidget()
void XbaeMatrixSetCellWidget(w, row, column, widget)
Widget w;
int row;
int column;
Widget widget;
XbaeMatrixSetCellWidget() is a function to attach a widget to a matrix cell. The cell is selected
by specifying its row and column , widget is the cell widget to be associated with that cell.
XbaeMatrix will manage the cell widget's position and size so it is displayed inside the cell at
all times, including when scrolling.
Using a NULL widget removes the link between a widget and its cell. Only one widget can be in a
cell, a widget should also be in only one cell at a time.
XbaeMatrixSetCellWidget()
void XbaeMatrixSetCellWidget(w, row, column, widget)
Widget w;
int row;
int column;
Widget widget;
XbaeMatrixSetCellWidget() is a function to attach a widget to a matrix cell. The cell is selected
by specifying its row and column , widget is the cell widget to be associated with that cell.
XbaeMatrix will manage the cell widget's position and size so it is displayed inside the cell at
all times, including when scrolling.
Using a NULL widget removes the link between a widget and its cell. Only one widget can be in a
cell, a widget should also be in only one cell at a time.
XbaeMatrixSetColumnBackgrounds()
void XbaeMatrixSetColumnBackgrounds()
Widget w;
int position;
Pixel *colors;
int num_colors;
w An XbaeMatrix widget.
position The column position at which to begin applying the new backgrounds. Must be greater than
or equal to zero, and (position + num_colors) must be less than or equal to XmNcolumns.
colors Points to an array of Pixel. These specify the backgrounds for the cells in the
specified columns. The colors array must have num_colors elements.
num_colors
The number of colors in the colors array.
XbaeMatrixSetColumnBackgrounds() is a convenient way to specify and modify the XmNcellBackgrounds
resource when setting the background of an entire column or columns. If XmNcellBackgrounds is
NULL, then XbaeMatrixSetColumnBackgrounds() will create a Pixel table initialized to XmNforeground
except for the columns specified in it's arguments. If XmNcellBackgrounds is not NULL, then
XbaeMatrixSetColumnBackgrounds() will changed the specified columns in that resource to the
specified colors.
XbaeMatrixSetColumnColors()
void XbaeMatrixSetColumnColors()
Widget w;
int position;
Pixel *colors;
int num_colors;
w An XbaeMatrix widget.
position The column position at which to begin applying the new colors. Must be greater than or
equal to zero, and (position + num_colors) must be less than or equal to XmNcolumns.
colors Points to an array of Pixel. These specify the colors for the cells in the specified
columns. The colors array must have num_colors elements.
num_colors
The number of colors in the colors array.
XbaeMatrixSetColumnColors() is a convenient way to specify and modify the XmNcolors resource when
setting the color of an entire column or columns. If XmNcolors is NULL, then
XbaeMatrixSetColumnColors() will create a Pixel table initialized to XmNforeground except for the
columns specified in it's arguments. If XmNcolors is not NULL, then XbaeMatrixSetColumnColors()
will changed the specified columns in that resource to the specified colors.
XbaeMatrixSetColumnWidth()
void XbaeMatrixSetColumnWidth()
Widget w;
int column;
int width;
w An XbaeMatrix widget.
column The column whose width we'll be changing.
width The new width of this column. A column width can be 0 to hide a column.
XbaeMatrixSetColumnWidth() is a convenient way to change the width of a column without the need to
allocate an array with column width numbers. Passing -1 as the new width will reset the column
width to the default value.
XbaeMatrixSetColumnLabel()
void XbaeMatrixSetColumnLabel()
Widget w;
int column;
String value;
w An XbaeMatrix widget.
column The column of the label is to be set.
value The new value of the label.
XbaeMatrixSetColumnLabel() allows the application developer to programmatically change the label
of a specified column.
XbaeMatrixSetColumnShadow()
void XbaeMatrixSetColumnShadow()
Widget w;
int column;
unsidned char shadow_type;
w An XbaeMatrix widget.
column The column for which the shadow to be set.
shadow_type
The new value of the shadow.
XbaeMatrixSetColumnShadow() allows the application developer to programmatically change the shadow
of a specified column.
XbaeMatrixSetColumnUserData()
void XbaeMatrixSetColumnUserData()
Widget w;
int column;
XtPointer data;
w An XbaeMatrix widget.
column The column whose value should be set.
data A pointer to a user defined data area.
XbaeMatrixSetColumnUserData() allows the application developer to programmatically associate user
data for the specified column.
XbaeMatrixSetRowBackgrounds()
void XbaeMatrixSetRowBackgrounds()
Widget w;
int position;
Pixel *colors;
int num_colors;
w An XbaeMatrix widget.
position The row position at which to begin applying the new colors. Must be greater than or
equal to zero, and (position + num_colors) must be less than or equal to XmNrows.
colors Points to an array of Pixel. These specify the backgrounds for the cells in the
specified rows. The colors array must have num_colors elements.
num_colors
The number of colors in the colors array.
XbaeMatrixSetRowBackgrounds() is a convenient way to specify and modify the XmNcellBackgrounds
resource when setting the background of an entire row or rows. If XmNcellBackgrounds is NULL, then
XbaeMatrixSetRowBackgrounds() will create a Pixel table initialized to XmNforeground except for
the rows specified in it's arguments. If XmNcellBackgrounds is not NULL, then
XbaeMatrixSetRowBackgrounds() will changed the specified rows in that resource to the specified
colors.
XbaeMatrixSetRowColors()
void XbaeMatrixSetRowColors()
Widget w;
int position;
Pixel *colors;
int num_colors;
w An XbaeMatrix widget.
position The row position at which to begin applying the new colors. Must be greater than or
equal to zero, and (position + num_colors) must be less than or equal to XmNrows.
colors Points to an array of Pixel. These specify the colors for the cells in the specified
rows. The colors array must have num_colors elements.
num_colors
The number of colors in the colors array.
XbaeMatrixSetRowColors() is a convenient way to specify and modify the XmNcolors resource when
setting the color of an entire row or rows. If XmNcolors is NULL, then XbaeMatrixSetRowColors()
will create a Pixel table initialized to XmNforeground except for the rows specified in it's
arguments. If XmNcolors is not NULL, then XbaeMatrixSetRowColors() will changed the specified rows
in that resource to the specified colors.
XbaeMatrixSetRowHeight()
void XbaeMatrixSetRowHeight()
Widget w;
int row;
int height;
w An XbaeMatrix widget.
row The row whose height we'll be changing.
height The new height of this row. A row height can be 0 to hide a row.
XbaeMatrixSetRowHeight() is a convenient way to change the height of a row without the need to
allocate an array with row height numbers. Passing -1 as the new height will reset the row's
height to the default value.
XbaeMatrixSetRowLabel()
void XbaeMatrixSetRowLabel()
Widget w;
int row;
String value;
w An XbaeMatrix widget.
row The row of the label is to be set.
value The new value of the label.
XbaeMatrixSetRowLabel() allows the application developer to programmatically change the label of
the specified row.
XbaeMatrixSetRowShadow()
void XbaeMatrixSetRowShadow()
Widget w;
int column;
unsigned char shadow_type;
w An XbaeMatrix widget.
row The row whose shadow should be set.
shadow_type
The value of the new shadow.
XbaeMatrixSetRowShadow() allows the application developer to programmatically change the shadow
for the specified row.
XbaeMatrixSetRowUserData()
void XbaeMatrixSetRowUserData()
Widget w;
int column;
XtPointer data;
w An XbaeMatrix widget.
row The row whose value should be set.
data A pointer to a user defined data area.
XbaeMatrixSetRowUserData() allows the application developer to programmatically associate user
data for the specified row.
XbaeMatrixSetXmColumnLabel()
void XbaeMatrixSetXmColumnLabel()
Widget w;
int column;
XmString value;
w An XbaeMatrix widget.
column The column of the xmLabel is to be set.
value The new value of the xmLabel.
XbaeMatrixSetXmColumnLabel() allows the application developer to programmatically change the
xmLabel of a specified column.
XbaeMatrixSetXmRowLabel()
void XbaeMatrixSetXmRowLabel()
Widget w;
int row;
XmString value;
w An XbaeMatrix widget.
row The row of the xmLabel is to be set.
value The new value of the xmLabel.
XbaeMatrixSetXmRowLabel() allows the application developer to programmatically change the xmLabel
of a specified row.
XbaeMatrixSortColumns()
void XbaeMatrixSortColumns()
Widget w;
int (*proc)(Widget, int, int, void *);
void *user_data;
w An XbaeMatrix widget.
proc a pointer to a function that can compare columns.
user_data a pointer the application can use for its own needs.
XbaeMatrixSortColumns allows you to sort the columns in the XbaeMatrix widget according to
criteria determined by the proc function. The proc function should have the above signature and
functionality as demanded by the qsort(3) function. It will be called with a the matrix being
sorted, the indices of two columns to compare and the user_data pointer XbaeMatrixSortColumns was
called with. It should return -1, 0, or 1 as appropriate. It is guaranteed that the matrix does
not change while sorting and the necessary reordering will only take place after the last call to
proc has been made.
XbaeMatrixSortRows()
void XbaeMatrixSortRows()
Widget w;
int (*proc)(Widget, int, int, void *);
void *user_data;
w An XbaeMatrix widget.
proc a pointer to a function that can compare rows.
user_data a pointer the application can use for its own needs.
XbaeMatrixSortRows allows you to sort the rows in the XbaeMatrix widget according to criteria
determined by the proc function. The proc function should have the above signature and
functionality as demanded by the qsort(3) function. It will be called with the matrix being
sorted, the indices of two rows to compare and the user_data pointer XbaeMatrixSortRows was called
with. It should return -1, 0, or 1 as appropriate. It is guaranteed that the matrix does not
change while sorting and the necessary reordering will only take place after the last call to proc
has been made.
XbaeMatrixUnhighlightAll()
void XbaeMatrixUnhighlightAll()
Widget w;
w An XbaeMatrix widget.
XbaeMatrixUnhighlightAll() allows the application developer to programmatically unhighlight all
cells. XbaeMatrixUnhighlightAll() erases the highlight from all cells. All unsigned chars in the
XmNhighlightedCells array will be set to HighlightNone.
XbaeMatrixUnhighlightCell()
void XbaeMatrixUnhighlightCell()
Widget w;
int row;
int column;
w An XbaeMatrix widget.
row The row of the cell to unhighlight.
column The column of the cell to unhighlight.
XbaeMatrixUnhighlightCell() allows the application developer to programmatically unhighlight a
cell. XbaeMatrixUnhighlightCell() erases the highlight from the cell. The corresponding unsigned
char in the XmNhighlightedCells array will be have its HighlightCell bit cleared.
XbaeMatrixUnhighlightColumn()
void XbaeMatrixUnhighlightColumn()
Widget w;
int column;
w An XbaeMatrix widget.
column The column to unhighlight.
XbaeMatrixUnhighlightColumn() allows the application developer to programmatically unhighlight a
column. XbaeMatrixUnhighlightColumn() erases the highlight from around the column if XmNgridType
is XmGRID_COLUMN_SHADOW or from around each cell in the column otherwise. The corresponding
unsigned chars in the XmNhighlightedCells array will be have its HighlightColumn or HighlightOther
bit cleared, depending on whether XmNgridType is set to XmGRID_COLUMN_SHADOW or not.
XbaeMatrixUnhighlightRow()
void XbaeMatrixUnhighlightRow()
Widget w;
int row;
w An XbaeMatrix widget.
row The row to unhighlight.
XbaeMatrixUnhighlightRow() allows the application developer to programmatically unhighlight a row.
XbaeMatrixUnhighlightRow() erases the highlight from around the row if XmNgridType is
XmGRID_ROW_SHADOW or from around each cell in the row otherwise. The corresponding unsigned chars
in the XmNhighlightedCells array will be have its HighlightRow or HighlightOther bit cleared,
depending on whether XmNgridType is set to XmGRID_ROW_SHADOW or not.
XbaeMatrixVisibleCells()
int XbaeMatrixVisibleCells()
Widget w;
int *top_row;
int *bottom_row;
int *left_column;
int *right_column;
w An XbaeMatrix widget.
top_row The first row that is currently visible in the matrix.
bottom_row
The last row that is currently visible in the matrix.
left_column
The leftmost column that is currently visible in the matrix.
right_column
The rightmost column that is currently visible in the matrix.
XbaeMatrixVisibleCells() allows the the application developer to obtain the currently visible
portion of the XbaeMatrix w.
XbaeMatrixVisibleColumns()
int XbaeMatrixVisibleColumns()
Widget w;
w An XbaeMatrix widget.
XbaeMatrixVisibleColumns() allows the the application developer to programmatically check how many
columns are currently displayed in the XbaeMatrix w. A partially visible column will be declared
an entire column.
XbaeMatrixVisibleRows()
int XbaeMatrixVisibleRows()
Widget w;
w An XbaeMatrix widget.
XbaeMatrixVisibleRows() allows the the application developer to programmatically check how many
rows are currently displayed in the XbaeMatrix w. A partially visible row will be declared an
entire row.
XbaeGetVersionNum()
int XbaeGetVersionNum()
XbaeGetVersionNum() is a function that returns the numeric representation of the version of the
Xbae library that your program is working with. This is the run-time version of the Xbae widgets,
where XbaeVersion is a macro that represents the compile-time version.
The numeric representation is a simple calculation based on the major, minor, and pico numbers
representing an Xbae widget release. E.g. version 4.8.1 would be represented as 40801.
Releases prior to 4.8.0 didn't have this functionality.
XbaeGetVersionText()
char * XbaeGetVersionText()
XbaeGetVersionText() is a function that returns the textual representation of the version of the
Xbae library that your program is working with. This is the run-time version of the Xbae widgets,
where XbaeVersionTxt is a macro that represents the compile-time version.
Additional Behavior
Using XtSetValues to set the Matrix's XmNwidth resource to 0 will cause it to recompute it's horizontal
size. It will request a new size which results in XmNvisibleColumns columns being displayed. If
XmNvisibleColumns is 0, then it will request a new size such that it does not need a horizontal ScrollBar
(full horizontal size).
Using XtSetValues to set the Matrix's XmNheight resource to 0 will cause it to recompute it's vertical
size. It will request a new size which results in XmNvisibleRows rows being displayed. If XmNvisibleRows
is 0, then it will request a new size such that it does not need a vertical ScrollBar (full vertical
size).
An XtSetValues on XmNvisibleRows will cause the Matrix to request a new size which results in
XmNvisibleRows non-fixed rows being displayed, only if the new value is different than the old one.
An XtSetValues on XmNvisibleColumns will cause the Matrix to request a new size which results in the
first XmNvisibleColumns non-fixed columns being displayed, only if the new value is different than the
old one.
An XtSetValues on any other resource will not result in a request for a new size. Setting other resources
in conjunction with setting XmNwidth and/or XmNheight to 0 allows for more control of the Matrix's
geometry.
An XtSetValues setting XmNrowLabelWidth to 0 will cause XmNrowLabelWidth to be set to the width of the
longest row label.
Virtual Bindings
The bindings for virtual keys are vendor specific. For information about bindings for virtual buttons and
keys, see VirtualBindings(3X).
AUTHOR
Andrew Wason (aw@bae.bellcore.com) of Bellcore, Piscataway NJ, wrote the original version of the Xbae
widgets. His final release of the widgets was version 3.8.
Kevin Brannen (kbrannen@metronet.com) took over maintainership following Andrew Wason's departure and
released version 4.0.
Andrew Lister (lister@db.com) maintained from 1995 to 1999.
SPECIAL THANKS
Andrew Wason for the original idea and source code.
Jay Schmidgall for his contributions.
Nick Banyard for providing the multibyte extensions.
Callum Gibson for the pattern parsing in the XbaeInput widget.
Sascha Goebel for debugging the scroll-per-pixel code.
Tobias Oed for lots of code cleanup and debugging.
The people from Arcad Systemhaus for code submission for XbaeMatrixSort and a couple of related
functionalities, and easier pixmap support.
RELEASE
This document describes XbaeMatrix, version 4.60.4.
SEE ALSO
Core(3X), Composite(3X), XmManager(3X), XmScrollBar(3X), XbaeInput(3X), XmText(3X)
Notice of Limitation
Bellcore, previous and current maintainers of the Xbae widgets (collectively 'authors') provide this
information solely to professionals who have the appropriate degree of experience to understand and
interpret its contents in accordance with generally accepted engineering or other professional standards
and applicable regulations. No recommendations as to products or vendors is made or should be implied.
While the information contained herein has been prepared from sources deemed to be reliable, the authors
reserve the right to revise the information without notice, but has no obligation to do so. Unless the
recipient has been expressly granted a license by Bellcore under separate applicable written agreement
with Bellcore, no license, expressed or implied, is granted under any patents, copyrights or other
intellectual property rights. Use of the information is at your discretion and shall not be deemed an
inducement by Bellcore to infringe any existing or later-issued patent, copyrights or other intellectual
property right.
THE AUTHORS MAKE NO REPRESENTATIONS AND EXTENDS NO WARRANTIES, EXPRESS OR IMPLIED, WITH RESPECT TO THE
INFORMATION, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR ANY
PARTICULAR PURPOSE, AND THE WARRANTY AGAINST INFRINGEMENT OF PATENTS OR OTHER INTELLECTUAL PROPERTY
RIGHTS. THE INFORMATION IS PROVIDED ``AS IS'', AND IN NO EVENT SHALL THE AUTHORS OR ANY OF ITS AFFILIATES
BE LIABLE FOR ANY DAMAGES, INCLUDING ANY LOST PROFITS OR OTHER INCIDENTAL OR CONSEQUENTIAL DAMAGES
RELATING TO THE INFORMATION.
Copyright 1991, 1992 Bellcore.
Copyright 1995-99 Andrew Lister All Rights Reserved.
Copyright 1999-2002 LessTif Developers
The above no warranty extends to all additions and contributions. No contributor shall be held liable;
this work is provided ``as is''. If this is a problem for you, then don't use this software.
4.60.4 2024-04-01 XbaeMatrix(3)