XbaeMatrix(3)

'\" t

XbaeMatrix - The Bellcore Application Environment (BAE) XbaeMatrix widget class.

#include

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

looks and acts like a grid of

widgets, it actually contains only one

This means that

widgets with hundreds or thousands of rows have much less overhead than they would if they used an

for each cell.

Clicking on a cell with

will edit the cell. While a cell is being edited,

and

will edit the cell to the right or left respectively. The

and

keys will edit the cell above or below.

and

into the next or previous tab groups.

The

key will cancel any edits made to a cell. The

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

calls the callbacks on the

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,

provides callbacks to assist in data validation. The callbacks on the

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

is called after text is inserted or deleted.

When a cell is edited (by clicking on it or tabbing into it), the

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

callbacks for the new cell are called. These callbacks can be used to specify the editability of the new cell.

The

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

The

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

For large amounts of data, the overhead of assigning data to the widget can be avoided using the

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

inherits behavior and resources from the

and

widget classes.

The class pointer is

The class name is

The following table lists the new resources defined by

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

expand box; c s s s s lb | lb | lb | lb | lb lp7 | lp7 | lp7 | lp7 | lp7 . 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 _

expand box; c s s s s lb | lb | lb | lb | lb lp7 | lp7 | lp7 | lp7 | lp7 . XbaeMatrix Resource Set (continued) _ Name Class Type Default Access = XmNhighlightedCells XmCHighlightedCells HighlightTable * dynamic CSG _ XmNhorizontalScrollBar XmCHorizontalScrollBar Widget NULL G _ XmNhorizontalScrollBarDisplayPolicy XmCMatrixScrollBarDisplayPolicy unsigned char XmDISPLAY_AS_NEEDED CSG _ XmNlabelActivateCallback XmCCallback Callback NULL CSG _ XmNlabelFont XmCFontList FontList dynamic CSG _ XmNleaveCellCallback XmCCallback Callback NULL CSG _ XmNleftColumn XmCLeftColumn int 0 CSG _ XmNmodifyVerifyCallback XmCCallback Callback NULL CSG _ XmNmultiLineCell XmCMultiLineCell Boolean False CSG _ XmNnonFixedDetachedLeft XmCNonFixedDetachedLeft Boolean False CSG _ XmNnonFixedDetachedTop XmCNonFixedDetachedTop Boolean False CSG _ XmNoddRowBackground XmCBackground Pixel dynamic CSG _ XmNprocessDragCallback XmCCallback Callback NULL CSG _ XmNrenderTable XmCRenderTable RenderTable NULL CSG _ XmNresizeCallback XmCCallback Callback NULL CSG _ XmNresizeColumnCallback XmCCallback Callback NULL CSG _ XmNreverseSelect XmCReverseSelect Boolean False CSG _ XmNrowButtonLabels XmCButtonLabels BooleanArray NULL CSG _ XmNrowHeightInPixels XmCRowHeightInPixels Boolean True CSG _ XmNrowHeights XmCColumnWidths WidthArray NULL CSG _ XmNrowLabelAlignment XmCAlignment Alignment XmALIGNMENT_END CSG _ XmNrowLabelColor XmCColor Pixel dynamic CSG _ XmNrowLabelWidth XmCRowLabelWidth Short dynamic CSG _ XmNrowLabels XmCLabels StringArray NULL CSG _ XmNrowShadowTypes XmCShadowTypes unsigned char * NULL CSG _ XmNrowUserData XmCUserDatas XtPointer * NULL CSG _ XmNrows XmCRows int 0 CSG _ XmNscrollBarPlacement XmCScrollBarPlacement unsigned char XmBOTTOM_RIGHT CSG _ XmNselectCellCallback XmCCallback Callback NULL CSG _ XmNselectScrollVisible XmCSelectScrollVisible Boolean True CSG _ XmNselectedBackground XmCColor Pixel dynamic CSG _ XmNselectedCells XmCSelectedCells BooleanTable dynamic CSG _ XmNselectedForeground XmCColor Pixel dynamic CSG _ XmNshadowType XmCShadowType unsigned char XmSHADOW_IN CSG _ XmNshowArrows XmCShowArrows Boolean False CSG _ XmNspace XmCSpace Dimension dynamic CSG _ XmNtextBackground XmCBackground Pixel XmUNSPECIFIED_PIXEL CSG _ XmNtextBackgroundIsCell XmCTextBackgroundIsCell Boolean False CSG _ XmNtextField XmCTextField Widget NULL G _ XmNtextShadowThickness XmCTextShadowThickness Dimension 0 CSG _ XmNtextTranslations XmCTranslations TranslationTable dynamic CSG _ XmNtopRow XmCTopRow int 0 CSG _ XmNtrackcellCallback XmCCallback Callback NULL CSG _ XmNtrailingAttachedBottom XmCTrailingAttachedBottom Boolean False CSG _ XmNtrailingAttachedRight XmCTrailingAttachedRight Boolean False CSG _ XmNtrailingFixedColumns XmCTrailingFixedColumns Dimension 0 CSG _ XmNtrailingFixedRows XmCTrailingFixedRows Dimension 0 CSG _ XmNtraverseCellCallback XmCCallback Callback NULL CSG _ XmNtraverseFixedCells XmCTraverseFixedCells Boolean False CSG _

expand box; c s s s s lb | lb | lb | lb | lb lp7 | lp7 | lp7 | lp7 | lp7 . XbaeMatrix Resource Set (continued) _ Name Class Type Default Access = XmNuseXbaeInput XmCUseXbaeInput Boolean False CSG _ XmNvalueChangedCallback XmCCallback Callback NULL CSG _ XmNverticalScrollBar XmCVerticalScrollBar Widget NULL G _ XmNverticalScrollBarDisplayPolicy XmCMatrixScrollBarDisplayPolicy unsigned char XmDISPLAY_AS_NEEDED CSG _ XmNvisibleColumns XmCVisibleColumns Dimension 0 CSG _ XmNvisibleRows XmCVisibleRows Dimension 0 CSG _ XmNwrapType XmCWrapType Boolean XbaeWrapNone CSG _ XmNwriteCellCallback XmCCallback Callback NULL CSG _ XmNxmColumnLabels XmCXmLabels XmString * NULL CSG _ XmNxmRowLabels XmCXmLabels XmString * NULL CSG _

This resource cannot be specified in a resource file

If True, allows the columns to be dynamically resized via the ResizeColumns(\|) action. The default value is to allow column resizing.

If True, allows the rows to be dynamically resized via the ResizeRows(\|) action. The default value is to allow row resizing.

Specifies the number of rows to use for each of the

and

colors. This resource is ignored if

and

are not used.

Overstrikes the row and column labels to create a bold font appearance when True.

When set to True, the labels will be drawn with a shadow around them similar to an

widget. A ButtonPress event generated on the labels, when

is True will cause the label to reverse the shadow and take on a pushed in appearance. A ButtonRelease event on the same label will invoke callbacks on the

list. The default value is False.

Specifies a Pixel value in which to draw the

If set to True, the insertion position on the text field is calculated with respect to where the pointer was clicked in the cell. The default value is False. The insertion position will be overridden if the

member of the

is set to a valid position.

Points to an array of pointers to rows. Each row is an array of Pixel values, one for each column in that row. This data structure is the same as that for

except each entry is a Pixel instead of a String. The background of a cell will be drawn in the color specified for that cell. If

is

backgrounds will be drawn using the color specified by

This resource is copied.

two dimensional nature of the

widget, it must be done by terminating each line with a \\n character. If the

set to 5 and

set to 5,

would be specified as:

\fC

l l . *mw.cellBackgrounds: blue, white, blue, white, blue\\n\\ white, blue, white, blue, white\\n\\ blue, white, blue, white, blue\\n\\ white, blue, white, blue, white\\n\\ blue, white, blue, white, blue\\n

Care must be taken when specifying these values in a resource file as an incorrect format can produce undesirable results.

Specifies the

resource of the

cell edit widget. This resource is also used to compute the size of each cell. See the description of

in

Specifies the

resource of the

widget. This resource is also used to compute the size of each cell. See the description of

in

Specifies the

resource of the

cell edit widget. This resource is also used to compute the size of each cell. See the description of

in

Specifies the

resource of the

cell edit widget. This resource is also used to compute the size of each cell. See the description of

in

Specifies the type of shadow drawn around each cell. Possible values for this resource are

and

The default shadow type is

Specifies on a per cell basis, the

Values for the resource are the same as for

This resource is copied.