XbaeMatrix

NAME

SYNOPSIS

DESCRIPTION

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

New Resources

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 2 CSG XmNcellMarginHeight XmCMarginHeight Dimension 3 CSG XmNcellMarginWidth XmCMarginWidth Dimension 3 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) 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 4 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

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

XmNallowColumnResize

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

XmNallowRowResize

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

XmNaltRowCount

Specifies the number of rows to use for each of the XmNevenRowBackground and XmNoddRowBackround colors. This resource is ignored if XmNevenRowBackground and XmNoddRowBackround are not used.

XmNboldLabels

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

XmNbuttonLabels

When set to True, the labels will be drawn with a shadow around them similar to an XmPushButton widget. A ButtonPress event generated on the labels, when XmNbuttonLabels 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 XmNlabelActivateCallback, list. The default value is False.

XmNbuttonLabelBackground

Specifies a Pixel value in which to draw the XmNbuttonLabels.

XmNcalcCursorPosition

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 position member of the XbaeEnterCellCallbackStruct is set to a valid position.

XmNcellBackgrounds

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 XmNcells, 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 XmNcellBackgrounds is NULL, backgrounds will be drawn using the color specified by XmNbackground. This resource is copied. XmNcellBackgrounds may be specified in a resource file but due to the two dimensional nature of the XbaeMatrix widget, it must be done by terminating each line with a \n character. If the XbaeMatrix widget had XmNrows set to 5 and XmNcolumns set to 5, XmNcellBackgrounds would be specified as:

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

XmNcellHighlightThickness

Specifies the XmNhighlightThickness resource of the XmText cell edit widget. This resource is also used to compute the size of each cell. See the description of XmNhighlightThickness in XmText(3X).

XmNcellMarginHeight

Specifies the XmNmarginHeight resource of the XmText widget. This resource is also used to compute the size of each cell. See the description of XmNmarginHeight in XmText(3X).

XmNcellMarginWidth

Specifies the XmNmarginWidth resource of the XmText cell edit widget. This resource is also used to compute the size of each cell. See the description of XmNmarginWidth in XmText(3X).

XmNcellShadowThickness

Specifies the XmNshadowThickness resource of the XmText cell edit widget. This resource is also used to compute the size of each cell. See the description of XmNshadowThickness in XmText(3X).

XmNcellShadowType

Specifies the type of shadow drawn around each cell. Possible values for this resource are XmSHADOW_OUT, XmSHADOW_IN, XmSHADOW_ETCHED_OUT, and XmSHADOW_ETCHED_IN. The default shadow type is XmSHADOW_OUT.

XmNcellShadowTypes

Specifies on a per cell basis, the XmNcellShadowType. Values for the resource are the same as for XmNcellShadowType. This resource is copied.

XmNcellUserData

Points to an array of pointers to individual user defined data areas associated with each cell. The data should be set using XbaeMatrixSetCellUserData() and retrieved using XbaeMatrixGetCellUserData(). This resource cannot be specified in a resource file and is copied.

XmNcells

Points to an array of pointers to rows. Each row is an array of String, one for each column in that row. For example, the cells for a 2x3 Matrix could be set up as follows:

String rows[2][3] =
{
	"00",	"01",	"02",
	"10",	"11",	"12"
};

	String *cells[2];
	cells[0] = &rows[0][0];
	cells[1] = &rows[1][0];

Now cells could be used as the XmNcells resource. If XmNcells is NULL, XbaeMatrix will not generate an internal table of empty Strings. This implies that if XmNcells is NULL, no cells have been set. This resource is copied. See the discussion in XmNcellBackgrounds for how to specify XmNcells in a resource file.

XmNclipWindow

The widget ID of the clip window. The clip window is the widget that contains the non-fixed region of cells. This resource can not be set to a new value.

XmNcolors

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 XmNcells, except each entry is a Pixel instead of a String. The text in a cell will be drawn in the color specified for that cell. If XmNcolors is NULL, text will be drawn using the color specified by XmNforeground. This resource is copied. See the discussion in XmNcellBackgrounds for how to specify XmNcolors in a resource file.

XmNcolumnAlignments

Points to an array of alignments (unsigned char), one for each column. Each element can be one of XmALIGNMENT_BEGINNING, XmALIGNMENT_CENTER or XmALIGNMENT_END. This specifies the alignment of the text or pixmap in each cell of that column. See the description of XmNalignment for XmLabel(3X). If XmNcolumnAlignments is NULL, each column will default to XmALIGNMENT_BEGINNING. This resource is copied.

XmNcolumnButtonLabels

An array of Booleans that tells the XbaeMatrix which column labels should be drawn as a button. Each Boolean can be specified as a Boolean string or integer. In order to use this resource, XmNbuttonLabels should be set to False.

XmNcolumnLabelAlignments

Points to an array of alignments (unsigned char), one for each column label. Each element can be one of XmALIGNMENT_BEGINNING, XmALIGNMENT_CENTER or XmALIGNMENT_END. This specifies the alignment of the text of each column label. See the description of XmNalignment for XmLabel(3X). If XmNcolumnLabelAlignments is NULL, each column label will default to XmALIGNMENT_BEGINNING. This resource is copied.

XmNcolumnLabelColor

Specifies a Pixel value in which to draw the XmNcolumnLabels.

XmNcolumnLabels

Points to an array of Strings to be drawn above each column. Each String may have embedded newline characters, in which case the label will be drawn on multiple lines. If there is a XmNxmColumnLabels defined for this coluumn it will be displayed in place of the XmNcolumnLabels. If XmNcolumnLabels and XmNxmColumnLabels are NULL, no labels will be drawn. This resource is copied.

XmNcolumnMaxLengths

Points to an array of int, one for each column. These specify the maximum length of a String which can be entered in the cells in that column. See the description of the XmText(3X) XmNmaxLength resource. If XmNcolumnMaxLengths is NULL or an element of the array is equal to 0, then the corresponding width from XmNcolumnWidths is used. This resource is copied.

XmNcolumnShadowTypes

Specifies on a per column basis, the XmNcellShadowType. Values for the resource are the same as for XmNcellShadowType. This resource is copied.

XmNcolumnUserData

Points to a user defined data area associated with a particular column. The data should be set using XbaeMatrixSetColumnUserData() and retrieved using XbaeMatrixGetColumnUserData(). This resource cannot be specified in a resource file.

XmNcolumnWidthInPixels

Specifies wether the elements of XmNcolumnWidths are measured in pixels or characters.

XmNcolumnWidths

Points to an array of short, one for each column. These specify the visible width of the cells in each column. See the description of the XmText(3X) XmNcolumns resource. This resource is copied.

XmNcolumns

Specifies the total number of columns of cells. XmNcolumns must be at least one. If the number of columns is changed via XtSetValues, then XmNcolumnMaxLengths must change or be NULL, XmNcolumnLabels must change or be NULL, XmNcolumnAlignments must change or be NULL and XmNcolumnLabelAlignments must change or be NULL. The preferred way to dynamically change the number of columns is to use XbaeMatrixAddColumns() or XbaeMatrixDeleteColumns().

XmNdefaultActionCallback

Specifies a list of callbacks to be called when a double click occurs in a cell. A pointer to an XbaeMatrixDefaultActionCallbackStruct is passed to the callbacks. Events are reported to the cell in which the double click occurs regardless of whether or not a callback exists. This callback is called by the DefaultAction() action and is NULL by default. The XmNdefaultActionCallback is ideal for popping up a dialog or other window when a double click occurs.

XmNdoubleClickInterval

Specifies the amount of time between mouse clicks before it is considered a double click. A double click is defined to be the time between the realease of the mouse button and subsequent press in the same cell. The default value is inherited from the display.

XmNdrawCellCallback

Specifies a list of callbacks to be called when a cell needs to be drawn. A pointer to an XbaeMatrixDrawCellCallbackStruct is passed to the callbacks. The application can specify what to put in a cell by modifying the callback struct's data fields. When the application callback returns to the widget code, the type field will determine what the widget draws on the screen. If the value is XbaeString, then the regular string drawing function for the widget will be called with the value the applicaton assigned to the string field in the struct. If the value is XbaeStringFree the widget also calls XtFree on the string when it is not needed anymore. Else, if the value is XbaePixmap, the widget will do an XCopyPlane(), in the case of a single plane bitmap, or XCopyArea(), in the case of a color pixmap. The width and height of cell is passed in the struct so the application can know how big to make the pixmap. In no case will a copy of the string or the pixmap value be made. The widget also uses the XmNcolumnAlignments resource to determine the horizontal alignment of the Pixmap. To have an editable array of data when the XmNdrawCellCallback is used and the cell is of type XbaeString or XbaeStringFree, use the XmNwriteCellCallback.

XmNenterCellCallback

Specifies a list of callbacks to be called immediately before a cell is to be edited. This callback list is called by the EditCell() action. A pointer to an XbaeMatrixEnterCellCallbackStruct is passed to the callbacks. The application can specify the editability of specific cells using this callback list as well as specifying configuration options for the XmText.

XmNevenRowBackground

Specifies a background cell Pixel value to use on even rows. This allows the matrix to look like computer paper. For wider bands of color, increase the size of XmNaltRowCount.

XmNfill

If True, controls whether the matrix should fill all of its available space when additional space if available, or if it should simply size itself as large as necessary, regardless of any additonal available space.

XmNhorzFill

If True, controls whether the matrix should highlight available space on the right of the selected cell(s) when the selected cell(s) are in the last column of the matrix.

XmNvertFill

If True, controls whether the matrix should highlight available space below the selected cell(s) when the selected cell(s) are in the last row of the Matrix.

XmNfixedColumns

Specifies the number of leading columns (starting from the left column) which should not be horizontally scrollable. XmNfixedColumns must be less than XmNcolumns-XmNtrailingFixedColumns. Cells in fixed columns are not editable unless XmNtraverseFixedCells is set to True.

XmNfixedRows

Specifies the number of leading rows (starting from the top row) which should not be vertically scrollable. XmNfixedRows must be less than XmNrows-XmNtrailingFixedRows. Cells in fixed rows are not editable unless XmNtraverseFixedCells is set to True.

XmNfontList

If the value of XmNrenderTable is NULL this resource specifies the font list to be used for the text displayed in the cells and the XmText cell edit widget. See XmFontListCreate(3X) to create a font list. This resource is copied. The preferred way of specifying a font for the table is in a resource file.

When drawing a cell, the matrix uses the first entry with the tag XmFONTLIST_DEFAULT_TAG if no tag has been set on the cell using XbaeMatrixSetCellTag. If a tag has been set on the cell the first entry with a matching tag is used.

XmNgridLineColor

Specifies the color in which the grid line should be drawn if XmNgridType is set to XmGRID_CELL_LINE, XmGRID_ROW_LINE or XmGRID_COLUMN_LINE. The default is that of XmNforeground.

XmNgridType

Sets the way the matrix grid is drawn. The grid types available include XmGRID_NONE, XmGRID_CELL_LINE, XmGRID_CELL_SHADOW, XmGRID_ROW_LINE, XmGRID_ROW_SHADOW, XmGRID_COLUMN_LINE and XmGRID_COLUMN_SHADOW. All of the grid types vary the way the shadow or line is drawn around the cell. XmGRID_ROW_LINE, XmGRID_ROW_SHADOW, XmGRID_COLUMN_LINE, and XmGRID_COLUMN_SHADOW only draw a border around the rows and columns, giving a more tabular rather than spreadsheet appearance. The default is XmGRID_CELL_LINE which draws a solid line around the cells.

XmNhighlightedCells

Points to an array of pointers to rows. Each row is an array of unsigned char values, one for each column in that row. This data structure is the same as that for XmNcells, except each entry is an unsigned char instead of a String. Each entry in the array will have a value that is either HighlightNone, HighlightCell, HighlightRow, HighlightColumn, HighlightOther or the bitwise OR of those values, depending on the value of XmNgridType and which call was used to highlight the cell. A cell will be drawn as highlighted if the corresponding unsigned char does not have the value HighlightNone. If XmNhighlightedCells is NULL, XbaeMatrix then no cells have been highlighted. This resource is copied, and cannot be specified in a resource file.

XmNhorizontalScrollBar

The widget ID of the horizontal XmScrollBar. This resource exists only for those applications that need to tie another scrollbar to the matrix's for synchronized scrolling. This resource can not be set to a new value.

XmNhorizontalScrollBarDisplayPolicy

Determines when to display a horizontal scrollbar in the matrix. Possible values are XmDISPLAY_NONE, which makes the matrix never display the scrollbar, XmDISPLAY_AS_NEEDED, which makes the matrix display the scrollbar when the list is too large, and XmDISPLAY_STATIC, which makes the matrix always display the scrollbar.

XmNlabelFont

If the value of XmNrenderTable is NULL this resource specifies the font list to be used for the text displayed in row and column labels. If XmNlabelFont is not specified, the value of XmNfontList is used for the label fonts. See XmFontListCreate(3X) to create a font list. This resource is copied. The preferred way of specifying a font for the labels is in a resource file.

When drawing a label, the matrix uses the first entry with the tag XmFONTLIST_DEFAULT_TAG.

XmNlabelActivateCallback

Specifies a list of callbacks to be called after a button label has been pressed. A pointer to an XbaeMatrixLabelActivateCallbackStruct is passed to the callbacks on this list.

XmNleaveCellCallback

Specifies a list of callbacks to be called immediately after a cell has been edited. This callback list is called by the EditCell() and CommitEdit() actions. A pointer to an XbaeMatrixLeaveCellCallbackStruct is passed to the callbacks. The application can perform cell specific data checks using this callback list.

XmNleftColumn

Allows the programmer to specify the first non fixed column to appear on the leftmost side of the matrix. This resource compliments the XmNtopRow resource. See the discussion of XmNtopRow for more details.

XmNmodifyVerifyCallback

Specifies a list of callbacks to be called before text is deleted from or inserted into the XmText cell edit widget. A pointer to an XbaeMatrixModifyVerifyCallbackStruct is passed to the callbacks. See the description of the XmText(3X) XmNmodifyVerifyCallback resource.

XmNmultiLineCell

is a boolean (default False) which specifies whether the matrix displays more than one line of text in a cell, when appropriate.

XmNnonFixedDetachedLeft

Indicated that empty space should be displayed after the fixed rows. This resource only has effect when XmNfill is true and XmNfixedRows is greater than zero.

XmNnonFixedDetachedTop

Indicated that empty space should be displayed after the fixed columns. This resource only has effect when XmNfill is true and XmNfixedColumns is greater than zero.

XmNoddRowBackground

Specifies a background cell color to use on odd rows. This allows the matrix to look like computer paper. For wider bands of color, increase the size of XmNaltRowCount.

XmNprocessDragCallback

Specifies a list of callbacks to be called from the ProcessDrag() action A pointer to an XbaeMatrixProcessDragCallbackStruct will be passed to the callbacks. The application can use this callback list to perform particular processing during a drag.

XmNrenderTable

Specifies the render table used to derive a font set or a font to draw the text displayed in the cells, the XmText cell edit widget and the labels.

When drawing a cell, the matrix uses the first entry with the tag _MOTIF_DEFAULT_LOCALE if no tag has been set on the cell using XbaeMatrixSetCellTag. If a tag has been set on the cell the first entry with a matching tag is used.

When drawing a label, the matrix uses the first entry with the tag "labels". If there is no such entry the first entry with the tag _MOTIF_DEFAULT_LOCALE is used.

XmNresizeCallback

Specifies a list of callbacks to be called when the matrix is resized.

XmNresizeColumnCallback

Specifies a list of callbacks to be called when a column is dynamically resized by the user.

XmNreverseSelect

Overrides the default XmNselectedForeground and XmNselectedBackground and draws a selected cell in the colours specified by XmNcellBackgrounds and XmNcolors for the particular cell. If these values are not set then the default colours will be used.

XmNrowButtonLabels

An array of Booleans that tells the XbaeMatrix which row labels should be drawn as a button. Each Boolean can be specified as a Boolean string or integer. In order to use this resource, XmNbuttonLabels should be set to False.

XmNrowLabelAlignment

Specifies the alignment of the row labels. It can be one of XmALIGNMENT_BEGINNING, XmALIGNMENT_CENTER or XmALIGNMENT_END. See the description of XmNalignment for XmLabel(3X). XmNrowLabelAlignment defaults to XmALIGNMENT_END.

XmNrowLabelColor

Specifies a Pixel value in which to draw the XmNrowLabels.

XmNrowLabelWidth

Specifies the width of the row labels. XmNrowLabelWidth defaults to the width of the longest row label.

XmNrowLabels

Points to an array of Strings to be drawn to the left of each row. Each String may have embedded newline characters, in which case the label will be drawn on multiple lines. If there is a XmNxmRowLabels defined for this row it will be displayed in place of the XmNrowLabels. If XmNrowLabels and XmNxmRowLabels are NULL, no labels will be drawn. This resource is copied.

XmNrowHeightInPixels

Specifies wether the elements of XmNrowHeights are measured in pixels or lines.

XmNrowHeights

Points to an array of short, one for each row. These specify the visible height of the cells in each row. This resource is copied.

XmNrowShadowTypes

Specifies on a per row basis, the XmNcellShadowType. Values for the resource are the same as for XmNcellShadowType. This resource is copied.

XmNrowUserData

Points to a user defined data area associated with a particular row. The data should be set using XbaeMatrixSetRowUserData() and retrieved using XbaeMatrixGetRowUserData(). This resource cannot be specified in a resource file.

XmNrows

Specifies the total number of rows of cells. XmNrows must be at least one. If the number of rows is changed via XtSetValues, then XmNrowLabels must change or be NULL. The preferred way to dynamically change the number of rows is to use XbaeMatrixAddRows() or XbaeMatrixDeleteRows().

XmNscrollBarPlacement

Determines where the scrollbars will be drawn. See the discussion of XmNscrollBarPlacement in XmScrolledWindow(3) for a complete discussion on this resource.

XmNselectCellCallback

Specifies a list of callbacks to be called from the SelectCell() action. A pointer to an XbaeMatrixSelectCellCallbackStruct will be passed to the callbacks. The application can use this callback list to perform selection/deselection of cells using the provided widget methods.

XmNselectScrollVisible

Specifies whether the matrix will scroll to make the selected cell visible. This flag is only checked when cells are selected programmatically, as when the user selects a cell with the mouse, it will already be visible.

XmNselectedBackground

Allows the background of selected cells in XmNselectedCells to be specified.

XmNselectedCells

Points to an array of pointers to rows. Each row is an array of Boolean values, one for each column in that row. This data structure is the same as that for XmNcells, except each entry is a Boolean instead of a String. A cell will be drawn as selected if the corresponding Boolean is True. If XmNselectedCells is NULL, then no cells have been selected. This resource is copied. It cannot be specified in a resource file.

XmNselectedForeground

Allows the foreground of selected cells in XmNselectedCells to be specified.

XmNshadowType

Specifies the type of shadow drawn around the border of the matrix. Possible values for this resource are XmSHADOW_OUT, XmSHADOW_IN, XmSHADOW_ETCHED_OUT, and XmSHADOW_ETCHED_IN. The default shadow type is XmSHADOW_OUT.

XmNshowArrows

Specifies whether arrows should be drawn when data in a cell has been obscured due to the value of XmNcolumnWidths.

XmNspace

Specifies the distance that separates the ScrollBars from the cell grid. The default value is 4 pixels.

XmNtextBackground

Specifies the background of the XmText cell edit widget. This can be used to make the XmText stand out against a uniformly colored matrix.

XmNtextBackgroundIsCell

Specifies if the background of the XmText cell edit widget defaults to the core background of the matrix or the background of the cell being edited when XmNtextBackground has the value XmUNSPECIFIED_PIXEL.

XmNtextField

The widget ID of the XmText. This resource cannot be set to a new value.

XmNtextShadowThickness

Specifies the XmNshadowThickness of the XmText. Interesting effects can be achieved by setting the XmNcellHighlightThickness to 0 and replacing the highlight with an indented shadow.

XmNtextTranslations

Specifies the XmNtranslations resource of the XmText cell edit widget. See the description of XmNtranslations in XmText(3X).

XmNtopRow

Specifies the row which should be displayed at the top of the non-fixed rows. XmNtopRow is specified relative to the first non-fixed row, so (XmNfixedRows + XmNtopRow) is the actual row number which will be moved to the top. If (XmNtopRow > (XmNrows - (<number of rows visible> + XmNfixedRows), then the actual row which will be moved to the top is (XmNrows - (<number of rows visible> + XmNfixedRows).

XmNtrackCellCallback

specifies a list of callbacks to be called when the mouse pointer is being moved.

XmNtrailingAttachedBottom

Indicated that any trailing fixed rows should be attached to the bottom of the matrix. This resource only has effect when XmNfill is true and XmNtrailingFixedRows is greater than zero.

XmNtrailingAttachedRight

Indicated that any trailing fixed columns should be attached to the right of the matrix. This resource only has effect when XmNfill is true and XmNtrailingFixedColumns is greater than zero.

XmNtrailingFixedColumns

Specifies the number of trailing columns (starting from the right column) which should not be horizontally scrollable. XmNtrailingFixedColumns must be less than XmNcolumns-XmNfixedColumns. Cells in trailing fixed columns are not editable unless XmNtraverseFixedCells is set to True.

XmNtrailingFixedRows

Specifies the number of trailing rows (starting from the bottom row) which should not be vertically scrollable. XmNtrailingFixedRows must be less than XmNrows-XmNfixedRows. Cells in trailing fixed rows are not editable unless XmNtraverseFixedCells is set to True.

XmNtraverseCellCallback

Specifies a list of callbacks to be called before a new cell is edited. These callbacks are called by the EditCell() action and when XbaeMatrix receives or looses focus. A pointer to an XbaeMatrixTraverseCellCallbackStruct is passed to the callbacks. The application can specify the next cell which should be edited via this callback list, thereby performing custom traversal.

XmNtraverseFixedCells

If True, this resource allows fixed cells and columns to be edited. The default is to not allow fixed rows or columns to be edited.

XmNuseXbaeInput

This boolean value determines whether to use XbaeInput or XmTextField as the widget used for editing cells. Default is not to use XbaeInput.

XmNvalueChangedCallback

Specifies a list of callbacks to be called after text is deleted from or inserted into the XmText cell edit widget. A pointer to an XbaeMatrixValueChangedCallbackStruct is passed to the callbacks. See the description of the XmText(3X) XmNvalueChangedCallback resource.

XmNverticalScrollBar

The widget ID of the vertical XmScrollBar. This resource exists only for those applications that need to tie another scrollbar to the matrix's for synchronized scrolling. This resource can not be set to a new value.

XmNverticalScrollBarDisplayPolicy

Determines when to display a horizontal scrollbar in the matrix. Possible values and their effects are listed under XmNhorizontalScrollBarDisplayPolicy.

XmNvisibleColumns

Specifies the number of non-fixed columns which should be visible. The widget will request a size which will allow XmNvisibleColumns columns to be displayed. The programmer should take into allowance any XmNfixedColumns that are specified. This feature becomes even more apparent if the number of XmNfixedColumns changes at runtime as the value may need to be adjusted to avoid a warning.

XmNvisibleRows

Specifies the number of rows which should be visible at any one time. The widget will request a size which will allow XmNvisibleRows rows to be displayed.

XmNwrapType

When XmNmultiLineCell is true this resource specifies how to break the lines. When set to XbaeWrapNone, lines are broken on newlines only. When set to XbaeWrapContinuous, long lines are further broken up so they fit in their cell. When set to XbaeWrapWord the breaking of long lines occures preferably on spaces.

XmNwriteCellCallback

Specifies a list of callbacks to be called when a cell value changes and an XmNdrawCellCallback is defined. A pointer to an XbaeMatrixWriteCellCallbackStruct is passed to the callbacks. The XmNwriteCellCallback allows data to be written back into the application's data structure and must be defined for an editable XbaeMatrix with an XmNdrawCellCallback.

XmNxmRowLabels

Points to an array of XmStrings to be drawn to the left of each row. If XmNxmRowLabels is NULL, XmNrowLabels will be used. This resource is copied.

XmNxmColumnLabels

Points to an array of XmStrings to be drawn above each column. If XmNxmColumnLabels is NULL, XmNcolumnLabels will be used. This resource is copied.

Inherited Resources

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 0 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 Name Class Type Default Access XmNaccelerators XmCAccelerators XtAccelerators NULL CSG XmNancestorSensitive XmCSensitive Boolean dynamic G XmNbackground XmCBackground Pixel dynamic CSG XmNbackgroundPixmap XmCPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG XmNborderColor XmCBorderColor Pixel XtDefaultForeground CSG XmNborderPixmap XmCPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG XmNborderWidth XmCBorderWidth Dimension 1 CSG XmNcolormap XmCColormap Colormap dynamic CG XmNdepth XmCDepth int dynamic CG XmNdestroyCallback XmCCallback XtCallbackList NULL C XmNheight XmCHeight Dimension dynamic CSG XmNinitialResourcesPersistent XmCInitialResourcesPersistent Boolean True C XmNmappedWhenManaged XmCMappedWhenManaged Boolean True CSG XmNscreen XmCScreen Screen dynamic CG XmNsensitive XmCSensitive Boolean True CSG XmNtranslations XmCTranslations XtTranslations dynamic CSG XmNwidth XmCWidth Dimension dynamic CSG XmNx XmCPosition Position 0 CSG XmNy XmCPosition Position 0 CSG

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 colums 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 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 compatability, the cell backgrounds cannot be set in a call to XbaeMatrixAddColumns() and must be set (if so desired) in a separate call to XtVaSetValues().

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 compatability, 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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

int XbaeMatrixNumRows()
	Widget	w;

w

An XbaeMatrix widget.

XbaeMatrixNumRows() returns the number of rows in the given matrix.

int XbaeMatrixNumColumns()
	Widget	w;

w

An XbaeMatrix widget.

XbaeMatrixNumColumns() returns the number of columns in the given matrix.

int XbaeMatrixNumRows()
	Widget	w;

w

An XbaeMatrix widget.

XbaeMatrixNumRows() returns the number of rows in the given matrix.

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

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

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.

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.

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.

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.

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.

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.

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.