Provided by: libxbae-dev_4.60.4-9build2_amd64 bug

NAME

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

SYNOPSIS

       #include <Xbae/Matrix.h>

DESCRIPTION

       XbaeMatrix presents an editable array of string data to the user in a scrollable grid-like
       format similar to a spreadsheet.  Non editable  pixmaps  can  also  be  displayed  on  the
       matrix.   The rows and columns of the Matrix may optionally be labeled.  Also, a number of
       fixed leading or trailing rows or columns may be specified - these behave similarly to the
       labels.   While  XbaeMatrix  looks  and  acts  like  a grid of XmText widgets, it actually
       contains only one XmText.  This means that XbaeMatrix widgets with hundreds  or  thousands
       of rows have much less overhead than they would if they used an XmText for each cell.

       Clicking on a cell with Button1 will edit the cell.  While a cell is being edited, Tab and
       Shift-Tab will edit the cell to the right or left respectively.   The  osfUp  and  osfDown
       keys  will edit the cell above or below.  Ctrl-Tab and Shift-Ctrl-Tab will traverse out of
       the Matrix and into the next or previous tab groups.

       The osfCancel key will cancel any edits made to a cell.  The osfActivate key  will  commit
       any  edits  made to a cell and store them in the Matrix.  When traversing from another tab
       group into the Matrix, the focus will go to whichever cell is currently being edited.   If
       no cells are being edited, then the upper left most visible non-fixed cell will be edited.

       The column sizes may be dynamically resized by pressing the Shift-Button2 combination when
       over a column boundary, similar to the behaviour of some popular  spreadsheets.   After  a
       column  has  been  resized  in  this  manner,  the  XbaeMatrix  calls the callbacks on the
       XmNresizeColumnCallback callback list for post processing.

       If the Matrix is resized until it is too small to display all of  the  cells  in  a  given
       dimension,  then it will display a ScrollBar for that dimension.  The horizontal ScrollBar
       will scroll the cells and column labels, but not the row labels, fixed columns or trailing
       fixed  columns.   The vertical ScrollBar will scroll the cells and row labels, but not the
       column labels, fixed rows or trailing fixed rows.

       For  the  application  programmer,  XbaeMatrix  provides  callbacks  to  assist  in   data
       validation.   The callbacks on the XmNmodifyVerifyCallback callback list are called before
       text is inserted into, or deleted from, a cell.  This callback list can be used  to  force
       user   input   to   match  a  certain  pattern  (e.g.  a  date  format).   Similarly,  the
       XmNvalueChangedCallback is called after text is inserted or deleted.

       When a cell is edited (by clicking on it or tabbing  into  it),  the  XmNleaveCellCallback
       callbacks  are  called  for  the  previous cell being edited, if any.  The application can
       verify the data entered in that cell and disallow editing of the new cell if the  data  is
       invalid.   If the data was valid, then the XmNenterCellCallback callbacks for the new cell
       are called.  These callbacks can be used to specify the editability of the new cell.

       The XmNtraverseCellCallback callbacks are also called when the user attempts to edit a new
       cell  and  when the matrix gains or looses focus.  This allows the application to override
       the default traversal behavior of XbaeMatrix.

       The XmNdefaultActionCallback is provided to allow a double  click  action  in  a  cell  to
       perform some function.

       Motif's Drag and Drop functionality can be achieved via the XmNprocessDragCallback.

       For  large  amounts  of  data, the overhead of assigning data to the widget can be avoided
       using the XmNdrawCellCallback.  This callback also  allows  user  defined  pixmaps  to  be
       placed in a certain cell.  When using this callback, data for string fields can be written
       back to the application by using the XmNwriteCellCallback.

Classes

       XbaeMatrix inherits behavior and resources  from  the  Core,  Composite,  Constraint,  and
       XmManager widget classes.
       The class pointer is xbaeMatrixWidgetClass.
       The class name is XbaeMatrix.

New Resources

       The  following  table  lists  the  new  resources defined by XbaeMatrix.  The codes in the
       ``Access'' column indicate whether the given resource can be set at creation time (C),  or
       set by using XtSetValues (S), or retrieved by using XtGetValues (G).

       ┌─────────────────────────────────────────────────────────────────────────────────────────┐
       │                                XbaeMatrix Resource Set                                  │
       ├─────────────────────────┬──────────────────────┬────────────────┬────────────────┬──────┤
--

Inherited Resources

       The  following  table lists the resources which XbaeMatrix inherits from it's superclasses
       XmManager, Compositeand Core.  For a complete description of each resource, refer  to  the
       man  page  for  that  superclass.  The codes in the ``Access'' column indicate whether the
       given resource can be set at creation time (C),  or  set  by  using  XtSetValues  (S),  or
       retrieved by using XtGetValues (G).

       ┌─────────────────────────────────────────────────────────────────────────────────────────┐
       │                                XmManager Resource Set                                   │
       ├─────────────────────┬─────────────────────┬─────────────────┬────────────────────┬──────┤
--

Callback Information

       XbaeMatrixAnyCallbackStruct
            A  callback struct that is suitable for all callbacks that require the reason, event,
            row and column to be available.  Any callback called may  therefore  cast  the  third
            parameter  to  the following struct in XbaeMatrix and can rest assured that evrything
            in it will be available.

            typedef struct
            {
                 XbaeReasonType   reason;
                 int              row;
                 int              column;
                 XEvent           *event;
            } XbaeMatrixAnyCallbackStruct;

            Each of the members are set to the appropriate struct for the callback.

            If this idea is a little foreign to you, recommended reading is K&R II page 213.

       XmNdefaultActionCallback
            Callbacks on the XmNdefaultActionCallback list are called  when  the  DefaultAction()
            action  occurs.   The  application can bind the DefaultAction() action to any pointer
            based event. When a double click occurs on this pointer event,  DefaultAction()  will
            call  the  callbacks on the XmNdefaultActionCallback list. A pointer to the following
            structure is passed to each callback on the XmNdefaultActionCallback list:

            typedef struct
            {
                    XbaeReasonType       reason;
                    XEvent               *event;
                    int                  row;
                    int                  column;
            } XbaeMatrixDefaultActionCallbackStruct;

            reason    Set to XbaeDefaultActionReason .

            event     The event that invoked this callback.

            row       The row number of the cell in which the double click occurred.

            column    The column number of the cell in which the double click occurred.

            event

            If an application has an XmNdefaultActionCallback, then the  callbacks  on  the  list
            will  be  called  when the user clicks twice in a cell within XmNdoubleClickInterval,
            enabling some action to occur for the particular cell.

       XmNdrawCellCallback
            Callbacks on the XmNdrawCellCallback list are called when the widget needs to draw  a
            cell.  A  pointer  to  the  following  structure  is  passed  to each callback on the
            XmNdrawCellCallback list:

            typedef struct
            {
                 XbaeReasonType    reason;
                 XEvent            *event;
                 int               row;
                 int               column;
                 int               width;
                 int               height;
                 XbaeCellType      type;
                 String            string;
                 Pixmap            pixmap;
                 Pixmap            mask;
                 Pixel             foreground;
                 Pixel             background;
                 int               depth;
            } XbaeMatrixDrawCellCallbackStruct;

            reason    Set to XbaeDrawCellReason.

            event     Always set to NULL

            row       The row number of the cell that needs to be drawn.

            column    The column number of the cell that needs to be drawn.

            width     The width of the cell that needs to be drawn.

            height    The height of the cell that needs to be drawn.

            type      The type of ``data'' the programmer wants drawn in the cell, or which field
                      should be looked at for data to draw:  string or pixmap.

            string    The string to draw if type is set to XbaeString or XbaeStringFree.

            pixmap    The  pixmap  to  copy  if type is set to XbaePixmap.  It will be clipped to
                      width by height if necessary.

            mask      A mask for the pixmap as obtained from  the  XPM  library.   mask  is  only
                      necessary when pixmap has a depth greater than one.

            foreground
                      The foreground color of the cell.

            background
                      The background color of the cell.

            depth     The depth of the pixmap image (in bits per pixel).

            If  the application adds this callback, when the XbaeMatrix determines that a cell at
            (row, column) needs to be redrawn, the normal cell drawing mechanism will be  skipped
            and  this  callback  called so the application can tell the widget what to put in the
            cell.

            The type field is defaulted to XbaeString and no cacheing or saving of the string  or
            pixmap is done.

            If  the  application  sets  type  to  XbaePixmap,  the width, height and depth of the
            returned pixmap will be calculated with a call to XGetGeometry().  If the  programmer
            wishes to supply the width, height and depth there is a marked improvement as a round
            trip to the X server is avoided.  Note that all geometry parameters must be  supplied
            to ensure successful display of the pixmap.

            If  a  mask  is  also  provided, it will be used to display the pixmap transparently.
            Pixmaps drawn in cells also respect the value of XmNcolumnAlignments.

            By defining an XmNdrawCellCallback the need for the storage of  the  XbaeMatrix  data
            within the matrix is eliminated and can prove to be advantageous for memory usage.

            To  write  the  data  back to the application, use the XmNwriteCellCallback described
            below.

       XmNenterCellCallback
            Callbacks on the XmNenterCellCallback list are called from the EditCell() action just
            before  a  cell  is  edited to determine it's editability. A pointer to the following
            structure is passed to each callback on the XmNenterCellCallback list:

            typedef struct
            {
                XbaeReasonType   reason;
                XEvent           *event;
                int              row;
                int              column;
                int              position;
                String           pattern;
                Boolean          auto_fill;
                Boolean          convert_case;
                Boolean          overwrite_mode;
                Boolean          select_text;
                Boolean          map;
                Cardinal         num_params;
                String           *params;
                Boolean          doit;
            } XbaeMatrixEnterCellCallbackStruct;

            reason    Set to XbaeEnterCellReason.

            event     The event that invoked the callback.

            row       The row number of the cell about to be edited.

            column    The column number of the cell about to be edited.

            position  The location of the cursor in the text field.  The default is to place  the
                      cursor at the end of the string in the cell.

            pattern   A  pattern  for the XbaeInput widget (see XbaeInput(3)).  The default is to
                      not specify a pattern.

            auto_fill Used in conjunction with the setting of the pattern to  allow  literals  in
                      the pattern to be automatically inserted.

            convert_case
                      If the pattern specifies an upper or lower case letter, the character typed
                      in the position can automatically be converted to the appropriate case when
                      set to True.  The default is to not convert the case of the typed letter.

            overwrite_mode
                      Normally,  the  cursor  appears  as  the  familiar  I  caret.   By  setting
                      overwrite_mode to True, the text field will go into  overwrite  mode  where
                      keystrokes replace the character underneath the block cursor.

            select_text
                      Indicates whether the text in the cell should be highlighted (only valid if
                      doit is set to True also.

            map       Tells the matrix if the XmText should be mapped onto the cell.  Only  makes
                      sense if doit is set to False.

            num_params
                      The number of String parameters passed to the EditCell() action.

            params    An  array  containing  the  num_params  String  parameters  passed  to  the
                      EditCell() action.

            doit      Indicates whether or not this cell is editable. Setting doit to False  will
                      make this cell not editable. The default value is True.

            If  the  application  determines  that  the cell at (row, column) is not editable, it
            should set the doit flag to False.  If the map flag is also set to False,  XbaeMatrix
            will  not  place  the  XmText  cell  editor on the cell.  If map is left as True, the
            XmText will be placed on the cell but the user will not be  able  to  add  or  delete
            characters  from  it. If the application leaves doit as True, then the TextField will
            be editable.  In addition, if select_text is set to True, the text in the  cell  will
            be selected via XmTextSetSelection.  Assuming XmNpendingDelete for the XmText is also
            True, the selected text will be deleted as soon as the next text insertion occurs.

       XmNlabelActivateCallback
            Callbacks on the XmNlabelActivateCallback list are called after a  button  label  has
            been  activated via a mouse click.  A pointer to the following structure is passed to
            each callback on the XmNlabelActivateCallback list:

            typedef struct
            {
                   XbaeReasonType      reason;
                   XEvent              *event;
                   int                 row;
                   int                 column;
                   Boolean             row_label;
                   String              label;
            } XbaeMatrixLabelActivateCallbackStruct;

            reason    Set to XbaeLabelActivateReason.

            event     The event that invoked this callback.

            row       The row number of the button label or -1 if the button was a column label.

            column    The column number of the button label or -1 if the button was a row label.

            row_label If the button label that invoked the callback is a  row  label,  then  this
                      value is set to True.  If it was a column label then it is set to False.

            label     The label on the button that was pressed.

            When  the  XbaeMatrix receives a ButtonRelease event on the same button label that it
            received a ButtonPress event, the XmNlabelActivateCallback is  called  to  allow  the
            programmer  to  respond to the event.  The callback has been provided to emulate some
            popular spreadsheets on the market.

       XmNleaveCellCallback
            Callbacks on the  XmNleaveCellCallback  list  are  called  from  the  EditCell()  and
            CommitEdit()  actions  just  before  the  edit  to the current cell is committed. The
            application can validate the changes made to the cell, and allow or disallow them.  A
            pointer   to   the   following   structure   is   passed  to  each  callback  on  the
            XmNleaveCellCallback list:

            typedef struct
            {
                 XbaeReasonType    reason;
                 XEvent            *event;
                 int               row, column;
                 String            value;
                 Boolean           doit;

            } XbaeMatrixLeaveCellCallbackStruct;

            reason    Set to XbaeLeaveCellReason.

            event     The event that invoked this callback.

            row       The row number of the cell being edited.

            column    The column number of the cell being edited.

            value     Contains the new data which will be stored in this cell if  doit  is  True.
                      The  memory pointed to by value may be modified, or if the new contents are
                      larger than the current contents, then value should be set to  point  to  a
                      larger piece of allocated memory.

            doit      Indicates  whether the edits applied to this cell should actually be stored
                      into XbaeMatrix.  Setting doit to  False  will  cause  the  changes  to  be
                      discarded and the cell will retain its original value. The default value is
                      True.

            If the application determines that the value entered in the cell at (row, column)  is
            not  valid,  it should set the doit flag to False. This will prevent the changes from
            being stored in the cell. The TextField edit widget will remain on the current  cell.
            If  the  application  leaves  doit as True, then the changes made to the cell will be
            committed and the  TextField  will  move  to  the  next  cell  or  be  unmapped.  The
            application  can  also  modify  the String in value, e.g. to force a String to be all
            upper case.

       XmNmodifyVerifyCallback
            Callbacks on the XmNmodifyVerifyCallback list  are  called  while  a  cell  is  being
            edited.  The  callbacks  are  called before text is inserted into or deleted from the
            TextField edit widget. A pointer  to  the  following  structure  is  passed  to  each
            callback on the XmNmodifyVerifyCallback list:

            typedef struct
            {
                XbaeReasonType               reason;
                XEvent                       *event;
                int                          row;
                int                          column;
                XmTextVerifyCallbackStruct   *verify;
                const char                   *prev_text;
            } XbaeMatrixModifyVerifyCallbackStruct;

            reason    Set to XbaeModifyVerifyReason.

            event     Always set to NULL.

            row       The row number of the cell being edited.

            column    The column number of the cell being edited.

            verify    The contents of this structure and its use are documented in the XmText(3X)
                      man page.

            prev_text The contents of the cell as seen by this user  before  the  new  text.   If
                      other text has already been entered, this value will not match the official
                      XbaeMatrix value of the cell.  This pointer and the string  should  not  be
                      modified.

       XmNprocessDragCallback
            Callbacks  on  the  XmNprocessDragCallback  list  are  called  from the ProcessDrag()
            action. The application can bind the ProcessDrag() action to any pointer based event,
            though  by  default  it  is  bound to the Button2Down event.  When this event occurs,
            ProcessDrag() will call the callbacks on the XmNprocessDragCallback list.  A  pointer
            to  the  following structure is passed to each callback on the XmNprocessDragCallback
            list:

            typedef struct
            {
                  XbaeReasonType      reason;
                  XEvent              *event;
                  int                 row;
                  int                 column;
                  String              string;
                  XbaeCellType        type;
                  Pixmap              pixmap;
                  Pixmap              mask;
                  Cardinal            num_params;
                  String              *params;
            } XbaeMatrixProcessDragCallbackStruct;

            reason    Set to XbaeProcessDragReason.

            event     The XEvent which invoked the ProcessDrag() action.

            row       The row number of the cell where the drag was initiated..

            column    The column number of the cell where the drag was initiated..

            string    The string in the cell where the drag was initiated if type  is  XbaeString
                      or XbaeStringFree.  This is provided as a convenience to the application.

            type      The type of the cell in which the drag was initiated.

            pixmap    The  pixmap in the cell where the drag was initiated if type is XbaePixmap.
                      This is provided as a convenience to the application.

            mask      A mask for the pixmap as obtained from  the  XPM  library.   mask  is  only
                      necessary  when  pixmap  has  a depth greater than one.  Also provided as a
                      convenience to the application.

            num_params
                      The number of String parameters passed to the ProcessDrag() action.

            params    An  array  containing  the  num_params  String  parameters  passed  to  the
                      ProcessDrag() action.

            The  application  can  use  the  XmNprocessDragCallback  list to implement particular
            processing for Motif's drag-and-drop.

       XmNresizeCallback
            Callbacks on the XmNresizeCallback list are called  when  the  XbaeMatrix  widget  is
            resized.  A pointer to the following structure is passed to
             each callback on the XmNresizeCallback list:

            typedef struct
            {
                  XbaeReasonType     reason;
                  XEvent             *event;
                  int                row;
                  int                column;
                  Dimension          width;
                  Dimension          height;
            } XbaeMatrixResizeCallbackStruct;

            reason    Set to XbaeResizeReason.

            event     Always set to NULL

            row       Set to the number of rows in the matrix (provided for convenience).

            column    Set to the number of columns in the matrix (provided for convenience).

            width     The new width of the XbaeMatrix widget.

            height    The new height of the XbaeMatrix widget.

            The   application   can  use  the  XmNresizeCallback  to  adjust  such  resources  as
            XmNcolumnWidths, XmNvisibleColumns and XmNvisibleRows when the widget  containing  an
            XbaeMatrix widget is resized.

       XmNresizeColumnCallback
            Callbacks  on  the  XmNresizeColumnCallback  list  are  called  when  a column of the
            XbaeMatrix widget is dynamically resized by the user.  A  pointer  to  the  following
            structure is passed to each callback on the XmNresizeColumnCallback list:

            typedef struct
            {
                 XbaeReasonType     reason;
                 XEvent             *event;
                 int                row;
                 int                column;
                 int                which;
                 int                columns;
                 short              *column_widths;
            } XbaeMatrixResizeColumnCallbackStruct;

            reason    Set to XbaeResizeColumnReason.

            event     The   XEvent   that   ended   the  resize.   The  event  will  be  of  type
                      XButtonReleasedEvent.

            row       The row in which the ResizeColumn() action began.

            column    The column in which the ResizeColumn() action began (and ended).

            which     The column that was resized in the ResizeColumn() action.

            columns   The number of columns in the XbaeMatrix widget.

            column_widths
                      The widths of each column as they stand after the ResizeColumn() action.

            The application can use the XmNresizeColumnCallback to perform post processing  after
            a  column  has  been resized.  By adjusting the values contained in column_widths the
            XbaeMatrix widget will use the values upon return from the  callback.   Changing  the
            number  of  columns  in  the  matrix  in  the  XmNresizeColumnCallback should be used
            carefully as it may cause unexpected results.

       XmNselectCellCallback
            Callbacks on the XmNselectCellCallback list are called from the SelectCell()  action.
            The  application  can  bind  the SelectCell() action to any pointer based event. When
            this event occurs, SelectCell() will call the callbacks on the  XmNselectCellCallback
            list.  A  pointer  to  the  following  structure  is  passed  to each callback on the
            XmNselectCellCallback list:

            typedef struct
            {
                XbaeReasonType   reason;
                XEvent           *event;
                int              row;
                int              column;
                Boolean          **selected_cells;
                String           **cells;
                Cardinal         num_params;
                String           *params;
            } XbaeMatrixSelectCellCallbackStruct;

            reason    Set to XbaeSelectCellReason.

            event     The XEvent which invoked the SelectCell() action.

            row       The row number of the cell which was selected.

            column    The column number of the cell which was selected.

            selected_cells
                      The  value  of  the  XmNselectedCells  resource.  This  is  provided  as  a
                      convenience  to  the application and will be NULL if no cells have yet been
                      selected.

            cells     The value of the XmNcells resource. This is provided as  a  convenience  to
                      the  application  and  will  be NULL if no cells have been specified or the
                      XmNdrawCellCallback is being used.

            num_params
                      The number of String parameters passed to the SelectCell() action.

            params    An  array  containing  the  num_params  String  parameters  passed  to  the
                      SelectCell() action.

            The  application  can  use  the  XmNselectCellCallback  list  to  implement  it's own
            selection model. The XbaeMatrixSelectCellCallbackStruct contains the array of  String
            parameters  passed to the SelectCell() action which invoked this callback. By binding
            the SelectCell() action to various events via  the  translation  manager,  and  using
            String  action  parameters to distinguish them, the application can implement various
            selection models. For example, the following translations could be used to  implement
            a  model  in  which  a  modifier key indicates whether a single cell or an entire row
            should be selected. The callbacks on the XmNselectCellCallback list would examine the
            parameter and take the appropriate action.

            #override\n\
                            Shift<Btn1Down>:   SelectCell(cell)\n\
                            Ctrl<Btn1Down>:    SelectCell(row)

            The  callbacks on the XmNselectCellCallback list can also be used in other ways, e.g.
            to pop up a cell specific menu.

            NOTE: If no cells have been selected, the value of selected_cells will be NULL.   The
            same applies for cells.  Care must be taken so as not to dereference these members of
            the callback struct.

       XmNtrackCellCallback
            Callbacks on the XmNtrackCellCallback list are being called by  the  HandleTracking()
            action,  which  is triggered by pointer motion.  One of the purposes of this callback
            list is to figure out from which cell to which cell the pointer is  being  moved.   A
            pointer  to  the  XbaeMatrixTrackCellCallbackStruct  structure  is  being passed. Its
            fields are defined as :

            typedef struct _XbaeMatrixTrackCellCallbackStruct
            {
                  XbaeReasonType     reason;
                  XEvent             *event;
                  int                row, column;
                  int                prev_row, prev_column;
                  Position           pointer_x, pointer_y;
            } XbaeMatrixTrackCellCallbackStruct;

            reason    Set to XbaeSelectCellReason.

            event     The XEvent which invoked the HandleTracking() action.

            row       This is the row number that the pointer is currently in.

            column    This is the column number that the pointer is currently in.

            prev_row  The row that the pointer was previously in.

            prev_column
                      The column that the pointer was previously in.

            pointer_x The x position of the pointer.

            pointer_y The y position of the pointer.

       XmNtraverseCellCallback
            Callbacks on the XmNtraverseCellCallback list are called from the  EditCell()  action
            and  when  XbaeMatrix  receives  or  looses focus. The application can customize cell
            traversal using these callbacks.  XbaeMatrix has a default traversal order,  outlined
            below,  which  the  application can override. A pointer to the following structure is
            passed to each callback on the XmNtraverseCellCallback list:

            typedef struct
            {
                XbaeReasonType   reason;
                XEvent           *event;
                int              row;
                int              column;
                int              next_row;
                int              next_column;
                int              fixed_rows;
                int              fixed_columns;
                int              trailing_fixed_rows;
                int              trailing_fixed_columns;
                int              num_rows;
                int              num_columns;
                String           param;
                XrmQuark         qparam;
            } XbaeMatrixTraverseCellCallbackStruct;

            reason    Set to XbaeTraverseCellReason.

            event     The event that invoked this callback.

            row       The row number of the cell currently being edited.

            column    The column number of the cell currently being edited.

            next_row  The row number of the next cell to be edited, this can be  changed  by  the
                      application.

            next_column
                      The column number of the next cell to be edited, this can be changed by the
                      application.

            fixed_rows
                      The value of the XmNfixedRows resource. This is provided as  a  convenience
                      for the application in calculating the next_row and next_column fields.

            fixed_columns
                      The   value  of  the  XmNfixedColumns  resource.  This  is  provided  as  a
                      convenience for the application in calculating the next_row and next_column
                      fields.

            trailing_fixed_rows
                      The  value  of  the  XmNtrailingFixedRows  resource.  This is provided as a
                      convenience for the application in calculating the next_row and next_column
                      fields.

            trailing_fixed_columns
                      The  value  of  the XmNtrailingFixedColumns resource. This is provided as a
                      convenience for the application in calculating the next_row and next_column
                      fields.

            num_rows  The  value  of  the XmNrows resource. This is provided as a convenience for
                      the application in calculating the next_row and next_column fields.

            num_columns
                      The value of the XmNcolumns resource. This is provided as a convenience for
                      the application in calculating the next_row and next_column fields.

            param     The String value of the parameter passed to the EditCell() action.

            qparam    The XrmQuark value of the parameter passed to the EditCell() action.

            The  EditCell()  action  takes  an arbitrary parameter which it passes through to the
            callbacks on the XmNtraverseCellCallback list in both String and XrmQuark forms.  The
            EditCell()  action recognizes five special parameters which it uses to implement it's
            default cell traversal. These parameters and their  corresponding  traversal  results
            are:

            Pointer   Set next_row and next_column to the cell underneath the mouse pointer.

            Left      If  we  are currently editing cell (XmNfixedRows, XmNfixedColumns), then do
                      not move. Otherwise move one column to the left, if  that  column  is  less
                      than XmNfixedColumns , then move up to the last column of the row above.

            Right     If we are currently editing cell (XmNrows - 1, XmNcolumns - 1), then do not
                      move. Otherwise move one column to the right, if  that  column  is  greater
                      than  or  equal to XmNcolumns , then move down to column XmNfixedColumns of
                      the row below.

            Up        Move up one row. If that row is less than XmNfixedRows , then move  to  the
                      last row.

            Down      Move  down  one row. If that row is greater than or equal to XmNrows , then
                      move to row XmNfixedRows.

            If the EditCell() action recognizes one of these special  parameters,  it  calculates
            the  new  cell  to  be  edited accordingly and stores the results in the next_row and
            next_column fields of the XbaeMatrixTraverseCellCallbackStruct.  If  EditCell()  does
            not recognize it's parameter, it sets next_row and next_column to the current row and
            column.  It also stores a String and XrmQuark version of it's parameter in the  param
            and    qparam    fields.     EditCell()    then    calls   the   callbacks   on   the
            XmNtraverseCellCallback  list.   These  callbacks  can  examine  the  parameter   and
            recalculate  the  next_row and next_column fields appropriately.  The application can
            override the default calculation for the special parameters,  or  it  can  define  an
            entirely  new  parameter  with  a corresponding new calculation.  It would do this by
            binding EditCell() with a new  application  specific  parameter  to  an  event  in  a
            translation  table.   It is expected that application callbacks will use the XrmQuark
            version of the parameter for efficiency  reasons  (by  statically  creating  the  new
            XrmQuarks and comparing them against the incoming qparam).

            When  XbaeMatrix  receives  the  focus  it will also call the XmNtraverseCellCallback
            callbacks before returning to the current cell or the upper left most visible cell if
            no cell is currently edited. The XbaeMatrixTraverseCellCallbackStruct will have param
            and qparm set to Focus.  If there is no current cell row and column will  be  set  to
            -1.

            When  XbaeMatrix  looses the focus it will also call the XmNtraverseCellCallback with
            param and qparm set to LoosingFocus.

       XmNvalueChangedCallback
            Callbacks on the XmNvalueChangedCallback list  are  called  while  a  cell  is  being
            edited.  The  callbacks  are  called  after text is inserted into or deleted from the
            TextField edit widget. A pointer  to  the  following  structure  is  passed  to  each
            callback on the XmNvalueChangedCallback list:

            typedef struct
            {
                  XbaeReasonType  reason;
                  XEvent  *event;
                  int     row;
                  int     column;
            } XbaeMatrixValueChangedCallbackStruct;

            reason    Set to XbaeValueChangedReason.

            event     The event that triggered this callback.

            row       The row number of the cell being edited.

            column    The column number of the cell being edited.

       XmNwriteCellCallback
            Callbacks   (although   it   probably   only   makes   sense  to  have  one)  on  the
            XmNwriteCellCallback list are called when the widget needs to write data to  a  cell,
            but only when XmNdrawCellCallback is defined. A pointer to the following structure is
            passed to each callback on the XmNwriteCellCallback list:

            typedef struct
            {
                   XbaeReasonType     reason;
                   XEvent             *event;
                   int                row;
                   int                column;
                   XbaeCellType       type;
                   String             string;
                   Pixmap             pixmap;
                   Pixmap             mask;
            } XbaeMatrixWriteCellCallbackStruct;

            reason    Set to XbaeWriteCellReason.

            event     Always set to NULL

            row       The row number of the cell that needs to be written.

            column    The column number of the cell that needs to be written.

            type      The  type  of  ``data''  contained  in  the  cell,  either  XbaeString   or
                      XbaePixmap.

            string    The string to store if type is set to XbaeString.

            pixmap    The  pixmap  to  store  if  type  is  set  to  XbaePixmap.  (maybe a little
                      meaningless unless you can edit a pixmap in a cell)

            mask      A mask for the pixmap as obtained from  the  XPM  library.   mask  is  only
                      necessary when pixmap has a depth greater than one.

            If  the  application adds this callback, when the XbaeMatrix is editable and has been
            assigned an XmNdrawCellCallback, data on the widget can be edited and stored back  in
            the  application's  data structure.  Only if an XmNdrawCellCallback has been assigned
            to the XbaeMatrix widget, will the XmNwriteCellCallback be called.

            At the moment, pixmap and mask will be sent to the XmNwriteCellCallback as NULL.

Translations

       XbaeMatrix inherits  translations  from  XmManager.   In  addition,  XbaeMatrix  uses  the
       following translation:

       :<Btn1Up>:                 DefaultAction()\n\
       :<Btn1Down>:               DefaultAction() EditCell(Pointer)\n\
       :Shift<Btn2Down>:          ResizeColumns()\n\
       :<Btn2Down>:               ProcessDrag()\n\
       :<Btn1Motion>:             HandleMotion() HandleTracking()()\n\
       :<Motion>:                 HandleTracking()()\n\
       :<Btn4Down>:               ScrollRows(-50)()\n<Btn5Down>:

       XbaeMatrix  installs  the  following  default  XmNtextTranslations  on  the TextField edit
       widget:

       #override\n\
       Shift ~Ctrl ~Meta ~Alt <Key>Tab:   EditCell(Left)\n\
       ~Ctrl ~Meta ~Alt <Key>Tab:         EditCell(Right)\n\
       <Key>osfUp:                        EditCell(Up)\n\
       <Key>osfDown:                      EditCell(Down)\n\
       <Key>osfActivate:                  CommitEdit(False)\n\
       ~Shift ~Meta ~Alt <Key>Return:     CommitEdit(False)\n\
       <Key>osfCancel:                    CommitEdit(False)\n\
       Shift Ctrl ~Meta ~Alt <Key>Tab:    TraversePrev()\n\
       Ctrl ~Meta ~Alt <Key>Tab:          TraverseNext()\n\
       <Key>osfPageDown:                  PageDown()\n\
       <Key>osfPageUp:                    PageUp()\n

Action Routines

       CancelEdit()
              If the single parameter to CancelEdit() is the String True, then it unmaps the edit
              TextField,  discarding any changes which were made to the cell being edited. If the
              parameter is False, then CancelEdit() restores the edit TextField to  the  original
              contents  of  the  cell,  discarding any changes made to the cell being edited. The
              TextField is not unmapped.

       CommitEdit()
              CommitEdit()  first  calls  any  callbacks  on  the  XmNleaveCellCallback  list  to
              determine  if  the changes made to the current cell are valid. If they are, it then
              saves any changes made to  the  cell  into  the  cell.  If  the  callbacks  on  the
              XmNleaveCellCallback  list return that the changes are not valid, CommitEdit() does
              nothing.

              If the changes are valid, CommitEdit() examines it's one parameter, which  must  be
              the  string  True  or  False.  If the parameter is True, then the edit TextField is
              unmapped. If it is False, then the TextField is not unmapped.

       DefaultAction()
              DefaultAction() sets up a mechanism for determining whether  two  successive  mouse
              clicks  form  a  double  click.   The  DefaultAction()  should  normally be used in
              conjunction with other pointer based events and provides a mechanism for acting  on
              double clicks in a cell.

       EditCell()
              EditCell() edits a new cell. EditCell() first calculates the new cell to edit based
              on   it's   single   parameter.   It   then   calls   the    callbacks    on    the
              XmNtraverseCellCallback list to allow them to specify a different cell to edit (see
              the discussion  of  XmNtraverseCellCallback  above).   EditCell()  then  calls  the
              callbacks  on the XmNleaveCellCallback list to determine if the changes made to the
              current cell are valid. If they are, it then saves any changes  made  to  the  cell
              into the cell. If the changes are not valid, EditCell() does nothing further.

              If  the  changes are valid, EditCell() attempts to scroll the new cell to be edited
              so that it is fully visible. If  the  new  cell  is  in  a  fixed  row  or  column,
              EditCell()  returns  and  does  nothing  further  (these  cells  are not editable).
              Otherwise, EditCell() calls the  callbacks  on  the  XmNenterCellCallback  list  to
              determine  if the new cell is editable. It then moves the XmText edit widget to the
              new   cell,   setting   it's   editability   based   on   the   return   from   the
              XmNenterCellCallback callbacks.

       ProcessDrag()
              ProcessDrag()  calls the callbacks on the XmNprocessDragCallback list, passing them
              a pointer to a XbaeMatrixProcessDragCallbackStruct.

       ResizeColumns()
              Allows  the  user  to  dynamically  resize  the  column   widths,   provided   that
              XmNallowColumnResize is True.

       ScrollRows()
              ScrollRows()  makes  the rows of the matrix scroll by the pixel amount specified by
              it's argument.

       ScrollColumns()
              ScrollColumns() makes the  columns  of  the  matrix  scroll  by  the  pixel  amount
              specified by it's argument.

       SelectCell()
              SelectCell()  calls the callbacks on the XmNselectCellCallback list, passing them a
              pointer to a XbaeMatrixSelectCellCallbackStruct.  This structure will  contain  the
              String  parameters  passed  to the SelectCell() action, among other things (see the
              discussion of XmNselectCellCallback above).

       TraverseNext()
              TraverseNext() will traverse out of the Matrix and into the next tab group.

       TraversePrev()
              TraversePrev() will traverse out of the Matrix and into the previous tab group.

       PageDown()
              PageDown() causes the Matrix to scroll down a full page.  The text widget is placed
              on the first non fixed row of the new page.

       PageUp()
              PageUp()  causes the Matrix to scroll up a full page.  The text widget is placed on
              the first non fixed row of the new page.

Type Converters

       In addition to the standard  type  converters  registered  by  Xt  and  Motif,  XbaeMatrix
       registers the following additional type converters:

       CvtStringToStringArray()
              Converts  a comma separated list of Strings to an array of String pointers, one for
              each substring. Commas in the list may be escaped  with  the  character  `\'.  This
              converter  allows the XmNrowLabels and XmNcolumnLabels resources to be specified in
              resource files.

       CvtStringToWidthArray()
              Converts a comma separated list of numeric Strings to an array of  short  integers.
              This  converter  allows  the  XmNcolumnWidths  resource to be specified in resource
              files.

       CvtStringToMaxLengthArray()
              Converts a comma separated list of numeric Strings to an array  of  integers.  This
              converter  allows  the  XmNcolumnMaxLengths  resource  to  be specified in resource
              files.

       CvtStringToAlignmentArray()
              Converts a comma separated list of alignments to an array of unsigned  chars.  This
              converter  allows the XmNcolumnLabelAlignments and XmNcolumnAlignments resources to
              be specified in resource files.

       CvtStringToGridType()
              Converts a single string as discussed in XmNgridType to a grid  type  value.   This
              converter allows XmNgridType to be specified in resource files.

       CvtStringToMatrixScrollBarDisplayPolicy()
              Converts  a  single  string as discussed in XmNhorizontalScrollBarDisplayPolicy and
              XmNverticalScrollBarDisplayPolicy to a display policy value.  This converter allows
              XmNhorizontalScrollBarDisplayPolicy  and  XmNverticalScrollBarDisplayPolicy  to  be
              specified in resource files.

       CvtStringToCellTable()
              Converts a comma separated list  of  Strings  with  \n  delimited  rows  to  a  two
              dimensional  array  of String pointers. This converter allows the XmNcells resource
              to be specified in resource files.

       CvtStringToPixelTable()
              Converts a comma separated list of color names with \n  delimited  rows  to  a  two
              dimensional    array    of    Pixel    values.    This    converter    allows   the
              XmNcellBackgroundsandXmNcolors resources to be specified in resource files.

       CvtStringToBooleanArray()
              Converts a comma separated list  of  string  or  numeric  values  to  an  array  of
              Booleans.   The  converter recongnises a comma separated list of values. Each value
              is  parsed  such  that  if  the  first  character  is  This  converter  allows  the
              XmNcolumnButtonLabels  and XmNrowButtonLabels resources to be specified in resource
              files.

Public Functions

       The following external entry points to XbaeMatrix class methods are defined:

       XbaeCreateMatrix()

              Widget XbaeCreateMatrix()
                  Widget      parent;
                  String      name;
                  ArgList     arglist;
                  Cardinal    argcount;

              parent    Specifies the parent widget ID.

              name      Specifies the name of the created widget

              arglist   Specifies the argument list

              argcount  Specifies the number  of  attribute/value  pairs  in  the  argument  list
                        (arglist)

              XbaeCreateMatrix()  creates  an  unmanaged  instance  of  an  XbaeMatrix widget and
              returns the associated widget ID.

       XbaeMatrixAddColumns()

              void XbaeMatrixAddColumns()
                  Widget     w;
                  int        position;
                  String     *columns;
                  String     *labels;
                  short      *widths;
                  int        *max_lengths;
                  unsigned   char *alignments;
                  unsigned   char *label_alignments;
                  Pixel      *colors;
                  int        num_columns;

              w         An XbaeMatrix widget.

              position  The column position before which to add the new columns. Must be  greater
                        than or equal to zero, and less than or equal to XmNcolumns.

              columns   Points  to  an  ordinary two dimensional array of String, or NULL.  These
                        Strings will be used to modify the XmNcells resource to populate the  new
                        columns.  Each row in the array must have XmNrows elements and represents
                        one of the new columns. columns must have num_columns rows. If columns is
                        NULL, empty columns will be added.

              labels    Points to an array of String, or NULL.  These Strings will be used as the
                        XmNcolumnLabels  for  the  new  columns.  The  labels  array  must   have
                        num_columns elements. If labels is NULL, and XmNcolumnLabels is set, then
                        blank column labels will be used.

              widths    Points to an array of short or NULL.  These values will be  used  as  the
                        XmNcolumnWidths   for  the  new  columns.  The  widths  array  must  have
                        num_columns elements. if widths is NULL then a default width will be used
                        for the new columns.

              max_lengths
                        Points  to  an  array  of int, or NULL.  These values will be used as the
                        XmNcolumnMaxLengths for the new columns. The max_lengths array must  have
                        num_columns  elements.  If  max_lengths  is  NULL, then the corresponding
                        value from widths will be used.

              alignments
                        Points to an array of unsigned char, or NULL.  These values will be  used
                        as the XmNcolumnAlignments for the new columns. The alignments array must
                        have   num_columns   elements.    If    alignments    is    NULL,    then
                        XmALIGNMENT_BEGINNING will be used.

              label_alignments
                        Points  to an array of unsigned char, or NULL.  These values will be used
                        as  the  XmNcolumnLabelAlignments  for  the  new  column   labels.    The
                        label_alignments    array    must    have    num_columns   elements.   If
                        label_alignments is NULL, then XmALIGNMENT_BEGINNING will be used.

              colors    Points to an array of Pixel, or NULL.  These values will be used  to  set
                        the corresponding columns in the XmNcolors table for the new columns. The
                        colors array must have num_columns elements.  If  colors  is  NULL,  then
                        XmNforeground will be used.

              num_columns
                        The number of columns which are being added to the widget.

              XbaeMatrixAddColumns()  allows  the  application  developer  to dynamically add new
              columns anywhere in the Matrix.  The  columns  will  be  added  before  the  column
              specified  in  position.  Columns  are  numbered  starting  at zero.  To append new
              columns onto the end of the  Matrix,  specify  position  as  the  total  number  of
              columns.  Most of the arguments to XbaeMatrixAddColumns() may be specified as NULL.
              Default values will be used by the widget.

              If the programmer attempts to add columns using XbaeMatrixAddColumns()  when  there
              are  no  rows, it will result in a warning message.  There must be at least one row
              in the XbaeMatrix widget to add columns.

              To maintain backward compatibility, the cell backgrounds cannot be set in a call to
              XbaeMatrixAddColumns()  and  must  be  set  (if  so  desired) in a separate call to
              XtVaSetValues().

       XbaeMatrixAddRows()

              void XbaeMatrixAddRows()
                   Widget   w;
                   int      position;
                   String   *rows;
                   String   *labels;
                   Pixel    *colors;
                   int      num_rows;

              w         An XbaeMatrix widget.

              position  The row position before which to add the new rows. Must be  greater  than
                        or equal to zero, and less than or equal to XmNrows.

              rows      Points  to  an  ordinary two dimensional array of String, or NULL.  These
                        Strings will be used to modify the XmNcells resource to populate the  new
                        rows.  Each row in the array must have XmNcolumns elements and represents
                        one of the new rows. rows must have num_rows rows. If rows is NULL, empty
                        rows will be added.

              labels    Points to an array of String, or NULL.  These Strings will be used as the
                        XmNrowLabels for the new  rows.  The  labels  array  must  have  num_rows
                        elements.  If  labels  is  NULL,  and XmNrowLabels is set, then blank row
                        labels will be used

              colors    Points to an array of Pixel, or NULL.  These values will be used  to  set
                        the  corresponding  rows  in  the  XmNcolors  table for the new rows. The
                        colors array must  have  num_rows  elements.  If  colors  is  NULL,  then
                        XmNforeground will be used.

              num_rows  The number of rows which are being added to the widget.

              XbaeMatrixAddRows()  allows  the  application developer to dynamically add new rows
              anywhere in the Matrix. The  rows  will  be  added  before  the  row  specified  in
              position.  Rows  are  numbered starting at zero. To append new rows onto the end of
              the Matrix, specify position as the total number of rows.

              To maintain backward compatibility, the cell backgrounds cannot be set in a call to
              XbaeMatrixAddRows()  and  must  be  set  (if  so  desired)  in  a  separate call to
              XtVaSetValues().

       XbaeMatrixCancelEdit()

              void XbaeMatrixCancelEdit()
                    Widget       w;
                    Boolean      unmap;

              w         An XbaeMatrix widget.

              unmap     Specifies whether the TextField cell edit widget should be unmapped after
                        the edit is canceled.

              XbaeMatrixCancelEdit()  allows the application developer to programmatically cancel
              a cell edit in progress, discarding any changes made by  the  user.  This  function
              unmaps  the TextField edit widget if the unmap flag is True. If unmap is False, the
              contents of the TextField are restored to their original value, and  the  TextField
              is not unmapped.

       XbaeMatrixCommitEdit()

              Boolean XbaeMatrixCommitEdit()
                     Widget        w;
                     Boolean       unmap;

              w         An XbaeMatrix widget.

              unmap     Specifies whether the TextField cell edit widget should be unmapped after
                        an edit is successfully committed.

              XbaeMatrixCommitEdit() can be used by the application developer to programmatically
              commit an edit, saving any changes made by the user.  This will cause the callbacks
              on the XmNleaveCellCallback list to be called to verify that the changes  the  user
              made  are valid. If the changes are valid, then they are saved into the cell and if
              the unmap flag is True, the TextField widget will be unmapped.

       XbaeMatrixDeleteColumns()

              void XbaeMatrixDeleteColumns()
                    Widget    w;
                    int       position;
                    int       num_columns;

              w         An XbaeMatrix widget.

              position  The column position at which to begin deleting columns. Must  be  greater
                        than  or equal to zero, and (position + num_columns) must be less than or
                        equal to XmNcolumns.

              num_columns
                        The number of columns to delete from the widget.

              XbaeMatrixDeleteColumns() allows the application developer  to  dynamically  delete
              columns from anywhere in the Matrix. Columns will be deleted starting at the column
              specified by position.

       XbaeMatrixDeleteRows()

              void XbaeMatrixDeleteRows()
                    Widget    w;
                    int       position;
                    int       num_rows;

              w         An XbaeMatrix widget.

              position  The row position at which to begin deleting rows. Must be greater than or
                        equal  to  zero,  and (position + num_rows) must be less than or equal to
                        XmNrows.

              num_rows  The number of rows to delete from the widget.

              XbaeMatrixDeleteRows() allows the application developer to dynamically delete  rows
              from  anywhere in the Matrix. Rows will be deleted starting at the row specified by
              position.

       XbaeMatrixDeselectAll()

              void XbaeMatrixDeselectAll()
                      Widget        w;

              w         An XbaeMatrix widget.

              XbaeMatrixDeselectAll()  allows  the  application  developer  to   programmatically
              deselect all cells.  XbaeMatrixDeselectAll() redraws the cells in normal video. All
              Booleans in the XmNselectedCells array will be set to False.

       XbaeMatrixDeselectCell()

              void XbaeMatrixDeselectCell()
                     Widget      w;
                     int         row;
                     int         column;

              w         An XbaeMatrix widget.

              row       The row of the cell to deselect.

              column    The column of the cell to deselect.

              XbaeMatrixDeselectCell()  allows  the  application  developer  to  programmatically
              deselect  a  cell.   XbaeMatrixDeselectCell() redraws the cell in normal video. The
              corresponding Boolean in the XmNselectedCells array will be set to False.

       XbaeMatrixDeselectColumn()

              void XbaeMatrixDeselectColumn()
                      Widget      w;
                      int         column;

              w         An XbaeMatrix widget.

              column    The column to deselect.

              XbaeMatrixDeselectColumn() allows the  application  developer  to  programmatically
              deselect  a  column.   XbaeMatrixDeselectColumn() draws the column in normal video.
              The corresponding Booleans in the XmNselectedCells array will be set to False.

       XbaeMatrixDeselectRow()

              void XbaeMatrixDeselectRow()
                      Widget      w;
                      int         row;

              w         An XbaeMatrix widget.

              row       The row to deselect.

              XbaeMatrixDeselectRow()  allows  the  application  developer  to   programmatically
              deselect  a  row.   XbaeMatrixDeselectRow()  draws  the  row  in  reverse video (or
              selectedForeground / selectedBackground if set). The corresponding Booleans in  the
              XmNselectedCells array will be set to False.

       XbaeMatrixDisableRedisplay()

              int XbaeMatrixDisableRedisplay()
                        Widget        w;

              w         An XbaeMatrix widget.

              XbaeMatrixDisableRedisplay()  and  XbaeMatrixEnableRedisplay() allow an application
              to make multiple changes  to  a  matrix  without  immediate  visual  updates.  When
              multiple  changes  are  made  with redisplay enabled, visual flashing often occurs.
              These routines help eliminate this problem.

       XbaeMatrixEditCell()

              void XbaeMatrixEditCell()
                    Widget    w;
                    int       row;

                    int       column;

              w         An XbaeMatrix widget.

              row       The row of the cell to be edited.

              column    The column of the cell to be edited.

              XbaeMatrixEditCell()

              allows the application developer to programmatically force a specific  cell  to  be
              edited. This function will first attempt to commit the edit in the current cell. If
              the XmNleaveCellCallback callbacks disallow this commit, then  XbaeMatrixEditCell()
              will  return.  Otherwise the specified cell is scrolled until it is visible. If the
              specified  cell  is  in  a  fixed  row  or  column,  it  cannot   be   edited   and
              XbaeMatrixEditCell()  will  return. Next, the callbacks on the XmNenterCellCallback
              callback list are called for the specified cell to determine it's editability. Then
              the TextField edit widget is mapped on top of the specified cell.

       XbaeMatrixEnableRedisplay()

              int XbaeMatrixEnableRedisplay()
                    Widget       w;
                    Boolean      redisplay;

              w         An XbaeMatrix widget.

              redisplay Force   the   matrix   to  redisplay  if  True  and  no  other  calls  to
                        XbaeMatrixDisableRedisplay() have been made.

              XbaeMatrixDisableRedisplay() and XbaeMatrixEnableRedisplay() allow  an  application
              to  make  multiple  changes  to  a  matrix  without  immediate visual updates. When
              multiple changes are made with redisplay enabled,  visual  flashing  often  occurs.
              These routines help eliminate this problem.

       XbaeMatrixEventToXY()

              Boolean XbaeMatrixEventToXY()
                    Widget      w;
                    XEvent      *event;
                    int         *x;
                    int         *y;

              w         An XbaeMatrix widget.

              event     An X event structure pointer, usually from an XEventHandler function.

              x         The translated x coordinate.

              y         The translated y coordinate.

              XbaeMatrixEventToXY  enables  the  programmer  to determine the x and y values of a
              given event with respect to the XbaeMatrix widget.  The returned  values  are  also
              adjusted to allow for the XbaeClip widget.

       XbaeMatrixFirstSelectedCell()

              void XbaeMatrixFirstSelectedCell()
                      Widget        w;
                      int           *row;
                      int           *column;

              w         An XbaeMatrix widget.

              row       The first selected row.

              column    The first selected column.

              XbaeMatrixFirstSelectedCell()  allows  the  application developer to find out which
              cell is the first selected.  The function traverses the XbaeMatrix widget in a left
              to  right,  top  to bottom manner to determine this value.  If no cell is selected,
              row and column are set to -1.

       XbaeMatrixFirstSelectedColumn()

              int XbaeMatrixFirstSelectedColumn()
                         Widget         w;

              w         An XbaeMatrix widget.

              XbaeMatrixFirstSelectedColumn() returns the column number  of  the  first  selected
              column  in the XbaeMatrix widget.  The function traverses the matrix from column 0.
              A column must be entirely selected for the column to be considered selected.  If no
              column is selected then -1 is returned.

       XbaeMatrixFirstSelectedRow()

              int XbaeMatrixFirstSelectedRow()
                        Widget        w;

              w         An XbaeMatrix widget.

              XbaeMatrixFirstSelectedRow()  returns  the  row number of the first selected row in
              the XbaeMatrix widget.  The function traverses the matrix from row 0.  A  row  must
              be  entirely selected for the row to be considered selected.  If no row is selected
              then -1 is returned.

       XbaeMatrixGetCell()

              String XbaeMatrixGetCell()
                    Widget     w;
                    int        row;
                    int        column;

              w         An XbaeMatrix widget.

              row       The row of the cell whose value should be retrieved.

              column    The column of the cell whose value should be retrieved.

              XbaeMatrixGetCell() returns the String value stored in  the  specified  cell.  This
              String  should  not  be freed. To examine many cells, it is more efficient to do an
              XtGetValues() on XmNcells and examine the values in that array.

       XbaeMatrixGetCellBackground()

              Pixel XbaeMatrixGetCellBackground()
                       Widget        w;
                       int           row;
                       int           column;

              w         A XbaeMatrix widget.

              row       The row of the cell whose background color should be retrieved.

              column    The column of the cell whose background color should be retrieved.

       XbaeMatrixGetCellColor()

              Pixel XbaeMatrixGetCellColor()
                     Widget       w;
                     int          row;
                     int          column;

              w         A XbaeMatrix widget.

              row       The row of the cell whose foreground color should be retrieved.

              column    The column of the cell whose foreground color should be retrieved.

       XbaeMatrixGetCellPixmap()

              int XbaeMatrixGetCellPixmap()
                     Widget     w;
                     int        row;
                     int        column;
                     Pixmap     *pixmap;
                     Pixmap     *mask;

              w         A XbaeMatrix widget.

              row       The row of the cell whose pixmap and mask should be retrieved.

              column    The column of the cell whose pixmap and mask should be retrieved.

              pixmap    A pointer to a Pixmap variable, in which  the  function  will  store  the
                        cell's pixmap.

              mask      A  pointer  to  a  Pixmap  variable, in which the function will store the
                        cell's pixmap mask.

       XbaeMatrixGetCellTag()

              XmStringTag XbaeMatrixGetCellTag()
                       Widget       w;
                       int          row;
                       int          column;

              w         A XbaeMatrix widget.

              row       The row of the cell whose tag should be retrieved.

              column    The column of the cell tag should be retrieved.

              XbaeMatrixGetCellTag returns the font tag of the indicated  cell.  The  application
              should not modify or free the returned value.
       XbaeMatrixGetCellUserData()

              XtPointer XbaeMatrixGetCellUserData()
                        Widget        w;
                        int           row;
                        int           column;

              w         An XbaeMatrix widget.

              row       The row of the cell whose data should be retrieved.

              column    The column of the cell whose data should be retrieved.

              XbaeMatrixGetCellUserData()  returns  a pointer to the data assigned to the cell in
              the given coordinates.  The data should be set  using  XbaeMatrixSetCellUserData().
              If no data is found to be associated with the particular cell, NULL is returned.

       XbaeMatrixGetColumnWidth()

              int XbaeMatrixGetColumnWidth()
                     Widget       w;
                     int          column;

              w         An XbaeMatrix widget.

              column    The column whose width we're querying.

              XbaeMatrixGetColumnWidth() is a convenient way to query a column width.

       XbaeMatrixGetColumnLabel()

              String XbaeMatrixGetColumnLabel()
                      Widget        w;
                      int           column;

              w         An XbaeMatrix widget.

              column    The column of the label that should be retrieved.

              XbaeMatrixGetColumnLabel()  returns a pointer to the label of the given column.  If
              no column labels exist or the given column is not a valid column NULL is  returned.
              If no data is found to be associated with the particular column, NULL is returned.

       XbaeMatrixGetColumnUserData()

              XtPointer XbaeMatrixGetColumnUserData()
                        Widget          w;

                        int             column;

              w         An XbaeMatrix widget.

              column    The column of the cell whose data should be retrieved.

              XbaeMatrixGetColumnUserData()  returns  a pointer to the data assigned to the given
              column.  The data should be set using XbaeMatrixSetColumnUserData().  If no data is
              found to be associated with the particular column, NULL is returned.

       XbaeMatrixGetCurrentCell()

              void XbaeMatrixGetCurrentCell()
                     Widget       w;
                     int          *row;
                     int          *column;

              w         An XbaeMatrix widget.

              row       The row of the cell the ``cursor'' or TextField is in.

              column    The column of the cell the ``cursor'' or TextField is in.

              XbaeMatrixGetCurrentCell()  allows the application developer to determine what cell
              is being edited or has focus.

       XbaeMatrixGetEventRowColumn()

              int XbaeMatrixGetEventRowColumn()
                      Widget       w;
                      XEvent       *event;
                      int          *row;
                      int          *column;

              w         An XbaeMatrix widget.

              event     An X event structure pointer.  This  is  usually  from  an  XEventHandler
                        function.  It can be either a button or a key event.

              row       The row of the cell the ``cursor'' or TextField is in.

              column    The column of the cell the ``cursor'' or TextField is in.

              XbaeMatrixGetEventRowColumn()  allows  the  application developer to determine what
              cell corresponds to an (x, y) in an event.  If the (x, y) of the event is  a  legal
              cell,  row  and column are set and True is returned.  However, if the (x, y) is not
              over a cell, False is returned, and row and column will have undefined values.

       XbaeMatrixGetNumSelected()

              int XbaeMatrixGetNumSelected()
                       Widget        w;

              w         An XbaeMatrix widget.

              XbaeMatrixGetNumSelected() returns the number of cells that are currently  selected
              in  the  given  matrix.   The  widget  maintains  an internal variable as cells are
              selected and deselected so a complete traversal of the widget is avoided.

       XbaeMatrixGetRowHeight()

              int XbaeMatrixGetRowHeight()
                      Widget      w;
                      int         row;

              w         An XbaeMatrix widget.

              row       The row whose height we query.

              XbaeMatrixGetRowHeight() is a convenient way to query a row height.

       XbaeMatrixGetRowLabel()

              String XbaeMatrixGetRowLabel()
                      Widget        w;
                      int           row;

              w         An XbaeMatrix widget.

              row       The row of the label that should be retrieved.

              XbaeMatrixGetRowLabel() returns a pointer to the label of the given row.  If no row
              labels exist or the given row is not a valid row NULL is returned.

       XbaeMatrixGetRowUserData()

              XtPointer XbaeMatrixGetRowUserData()
                        Widget          w;
                        int             row;

              w         An XbaeMatrix widget.

              row       The row of the cell whose data should be retrieved.

              XbaeMatrixGetRowUserData() returns a pointer to the data assigned to the given row.
              The data should be set using XbaeMatrixSetRowUserData().  If no data is found to be
              associated with the particular row, NULL is returned.

       XbaeMatrixGetXmColumnLabel()

              XmString XbaeMatrixGetXmColumnLabel()
                        Widget        w;
                        int           column;

              w         An XbaeMatrix widget.

              column    The column of the xmLabel that should be retrieved.

              XbaeMatrixGetXmColumnLabel()  returns a pointer to the xmLabel of the given column.
              If no xmColumnLabels exist or the given column  is  not  a  valid  column  NULL  is
              returned.  If no data is found to be associated with the particular column, NULL is
              returned.

       XbaeMatrixGetXmRowLabel()

              XmString XbaeMatrixGetXmRowLabel()
                        Widget        w;
                        int           row;

              w         An XbaeMatrix widget.

              row       The row of the xmLabel that should be retrieved.

              XbaeMatrixGetXmRowLabel() returns a pointer to the xmLabel of the given row.  If no
              xmRowLabels exist or the given row is not a valid row NULL is returned.  If no data
              is found to be associated with the particular row, NULL is returned.

       XbaeMatrixHighlightCell()

              void XbaeMatrixHighlightCell()
                     Widget       w;
                     int          row;
                     int          column;

              w         An XbaeMatrix widget.

              row       The row of the cell to highlight.

              column    The column of the cell to highlight.

              XbaeMatrixHighlightCell() allows  the  application  developer  to  programmatically
              highlight  a  cell.  XbaeMatrixHighlightCell() draws the highlight around the cell.
              The corresponding unsigned char in the XmNhighlightedCells array will be  have  its
              HighlightCell bit set.

       XbaeMatrixHighlightColumn()

              void XbaeMatrixHighlightColumn()
                      Widget       w;
                      int          column;

              w         An XbaeMatrix widget.

              column    The column to highlight.

              XbaeMatrixHighlightColumn()  allows  the  application developer to programmatically
              highlight a column.  XbaeMatrixHighlightColumn() draws  the  highlight  around  the
              column  if  XmNgridType  is  XmGRID_COLUMN_SHADOW  or  from around each cell in the
              column otherwise.  The corresponding  unsigned  chars  in  the  XmNhighlightedCells
              array  will  be  have  its  HighlightColumn or HighlightOther bit set, depending on
              whether XmNgridType is set to XmGRID_COLUMN_SHADOW or not.

       XbaeMatrixHighlightRow()

              void XbaeMatrixHighlightRow()
                      Widget       w;
                      int          row;

              w         An XbaeMatrix widget.

              row       The row to highlight.

              XbaeMatrixHighlightRow()  allows  the  application  developer  to  programmatically
              highlight  a  row.   XbaeMatrixHighlightRow() draws the highlight around the row if
              XmNgridType is XmGRID_ROW_SHADOW or from around each cell  in  the  row  otherwise.
              The  corresponding unsigned chars in the XmNhighlightedCells array will be have its
              HighlightRow or HighlightOther bit set, depending on whether XmNgridType is set  to
              XmGRID_ROW_SHADOW or not.

       XbaeMatrixIsCellSelected()

              Boolean XbaeMatrixIsCellSelected()
                       Widget       w;
                       int          row;
                       int          column;

              w         An XbaeMatrix widget.

              row       The row of the cell to check.

              column    The column of the cell to check.

              XbaeMatrixIsCellSelected() allows the application developer to determine whether or
              not a particular cell is selected.  The  function  returns  True  if  the  cell  is
              selected and False otherwise.

       XbaeMatrixIsCellVisible()

              Boolean XbaeMatrixIsCellVisible()
                      Widget        w;
                      int           row;
                      int           column;

              w         An XbaeMatrix widget.

              row       The row of the cell to check.

              column    The column of the cell to check.

              XbaeMatrixIsCellVisible()  allows the application developer to determine whether or
              not a particular cell is in the visible area of the XbaeMatrix widget. The function
              returns True if the cell is visible and False otherwise.

       XbaeMatrixIsColumnSelected()

              Boolean XbaeMatrixIsColumnSelected()
                       Widget         w;
                       int            column;

              w         An XbaeMatrix widget.

              column    The column of the matrix to check.

              XbaeMatrixIsColumnSelected()  allows the application developer to determine whether
              or not a particular column is selected. The function returns True if the column  is
              selected  and  False  otherwise.  A  column  must  be  selected in its entirety for
              XbaeMatrixIsColumnSelected() to return True.

       XbaeMatrixIsColumnVisible()

              Boolean XbaeMatrixIsColumnVisible()
                       Widget        w;
                       int           column;

              w         An XbaeMatrix widget.

              column    The column of the matrix to check.

              XbaeMatrixIsColumnVisible() allows the application developer to  determine  whether
              or  not  a  particular  column is in the visible area of the XbaeMatrix widget. The
              function returns True if the column is visible and False otherwise.

       XbaeMatrixIsRowSelected()

              Boolean XbaeMatrixIsRowSelected()
                       Widget         w;
                       int            row;

              w         An XbaeMatrix widget.

              row       The row of the matrix to check.

              XbaeMatrixIsRowSelected() allows the application developer to determine whether  or
              not  a particular row is selected. The function returns True if the row is selected
              and  False  otherwise.   A   row   must   be   selected   in   its   entirety   for
              XbaeMatrixIsRowSelected() to return True.

       XbaeMatrixIsRowVisible()

              Boolean XbaeMatrixIsRowVisible()
                       Widget        w;
                       int           row;

              w         An XbaeMatrix widget.

              row       The row of the matrix to check.

              XbaeMatrixIsRowVisible()  allows  the application developer to determine whether or
              not a particular row is in the visible area of the XbaeMatrix widget. The  function
              returns True if the row is visible and False otherwise.

       XbaeMatrixMakeCellVisible()

              int XbaeMatrixMakeCellVisible()
                      Widget      w;
                      int         row;
                      int         column;

              w         An XbaeMatrix widget.

              row       The row to scroll into the visible area of the matrix.

              column    The column to scroll into the visible area of the matrix.

              XbaeMatrixMakeCellVisible()  allows a cell to be programmatically scrolled into the
              visible  area  of  the  XbaeMatrix  widget.   By   calling   this   function,   the
              XmNselectScrollVisible  resource  is  ignored.   For  a more accurate cell location
              after scrolling, the programmer should use the XmNleftColumnandXmNtopRow resources.

       XbaeMatrixNumRows()

              int XbaeMatrixNumRows()
                     Widget     w;

              w         An XbaeMatrix widget.

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

       XbaeMatrixNumColumns()

              int XbaeMatrixNumColumns()
                      Widget      w;

              w         An XbaeMatrix widget.

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

       XbaeMatrixNumRows()

              int XbaeMatrixNumRows()
                     Widget     w;

              w         An XbaeMatrix widget.

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

       XbaeMatrixRefresh()

              void XbaeMatrixRefresh()
                     Widget      w;

              w         An XbaeMatrix widget.

              XbaeMatrixRefresh() allows the application developer to force the widget to  redraw
              itself.   This  might  be  used  when the programmer knows the widget's values have
              changed, but the widget has not detected the change.  For example, the quickest way
              to  swap  the  values of 2 rows would be to do an XtGetValues on XmNcells, swap the
              values of the 2 rows, and  then  do  an  XtSetValues  on  XmNcells  with  the  same
              StringTable  variable.  Because of the way the Intrinsics work, the widget will not
              see this change and will display the old values until a redraw is preformed because
              of  a  resize or scroll event (assuming no other change in the XtSetValues caused a
              redraw).  Calling XbaeMatrixRefresh() will cause the correct values to be drawn and
              overcome  this  limitation in the Intrinsics.  While this function should rarely be
              needed, it is provided ``just in case''.

       XbaeMatrixRefreshCell()

              void XbaeMatrixRefreshCell()
                     Widget     w;
                     int        row;
                     int        column;

              w         An XbaeMatrix widget.

              row       The row of the cell to redraw.

              column    The column of the cell to redraw.

              XbaeMatrixRefreshCell() allows the application developer to redraw a specific  cell
              of   the  matrix.   This  function  is  particularly  useful  when  used  with  the
              XbaeMatrixDrawCellCallback as it allows updates of the  data  without  an  explicit
              expose event.

       XbaeMatrixRefreshColumn()

              void XbaeMatrixRefreshColumn()
                     Widget       w;
                     int          column;

              w         An XbaeMatrix widget.

              column    The column of the matrix to redraw.

              XbaeMatrixRefreshColumn()  allows the application developer to efficiently redraw a
              specific column
               of the matrix.

       XbaeMatrixRefreshRow()

              void XbaeMatrixRefreshRow()
                     Widget       w;
                     int          row;

              w         An XbaeMatrix widget.

              row       The row of the matrix to redraw.

              XbaeMatrixRefreshRow() allows the application developer  to  efficiently  redraw  a
              specific row
               of the matrix.

       XbaeMatrixRowColToXY()

              int XbaeMatrixRowColToXY()
                    Widget     w;
                    int        row;
                    int        column;
                    int        *x;
                    int        *y;

              w         An XbaeMatrix widget.

              row       The row the of the cell in question.

              column    The column the of the cell in question.

              x         The  x  coordinate  returned  that represents the left coordinates of the
                        given cell.

              y         The y coordinate returned that represents the upper  coordinates  of  the
                        given cell.

              XbaeMatrixRowColToXY()   allows   the   application   developer  to  determine  the
              coordinates of the upper left corner of a given cell.  If the given widget  is  not
              an  XbaeMatrix  widget,  False  will  be returned and the values of x and y will be
              undefined.  This function is useful for drag and drop calculations.

       XbaeMatrixSelectAll()

              void XbaeMatrixSelectAll()
                      Widget      w;

              w         An XbaeMatrix widget.

              XbaeMatrixSelectAll() allows the application developer to  programmatically  select
              all  cells.  XbaeMatrixSelectAll() redraws the cells in reverse video. All Booleans
              in the XmNselectedCells array will be set to True.

       XbaeMatrixSelectCell()

              void XbaeMatrixSelectCell()
                    Widget      w;
                    int         row;
                    int         column;

              w         An XbaeMatrix widget.

              row       The row of the cell to select.

              column    The column of the cell to select.

              XbaeMatrixSelectCell() allows the application developer to programmatically  select
              a  cell.   XbaeMatrixSelectCell()  first  scrolls  the  specified  cell until it is
              visible, and then  draws  the  cell  in  reverse  video  (or  selectedForeground  /
              selectedBackground if set).
               The corresponding Boolean in the XmNselectedCells array will be set to True.

       XbaeMatrixSelectColumn()

              void XbaeMatrixSelectColumn()
                     Widget      w;
                     int         column;

              w         An XbaeMatrix widget.

              column    The column to select.

              XbaeMatrixSelectColumn()  allows  the  application  developer  to  programmatically
              select a column.  XbaeMatrixSelectColumn() first scrolls the specified column until
              it  is visible, and then draws the column in reverse video (or selectedForeground /
              selectedBackground if set).  The corresponding  Booleans  in  the  XmNselectedCells
              array will be set to True.

       XbaeMatrixSelectRow()

              void XbaeMatrixSelectRow()
                     Widget      w;
                     int         row;

              w         An XbaeMatrix widget.

              row       The row to select.

              XbaeMatrixSelectRow() allows the application developer to programmatically select a
              row.  XbaeMatrixSelectRow() first scrolls the specified row until  it  is  visible,
              and then draws the row in reverse video (or selectedForeground / selectedBackground
              if set).  The corresponding Booleans in the XmNselectedCells array will be  set  to
              True.

       XbaeMatrixSetCell()

              void XbaeMatrixSetCell()
                  Widget   w;
                  int      row;
                  int      column;
                  const    String value;

              w         An XbaeMatrix widget.

              row       The row of the cell whose value should be set.

              column    The column of the cell whose value should be set.

              value     The new value to set this cell to.

              XbaeMatrixSetCell()  allows  the  application developer to programmatically set the
              value of the specified cell. To set the values  of  many  cells,  it  may  be  more
              efficient to do an XtSetValues() on the XmNcells resource.

       XbaeMatrixSetCellBackground()

              void XbaeMatrixSetCellBackground()
                       Widget       w;
                       int          row;
                       int          column;
                       Pixel        color;

              w         An XbaeMatrix widget.

              row       The row of the cell whose backgroundshould be set.

              column    The column of the cell whose background should be set.

              color     The new color to which to set this cell's background.

              XbaeMatrixSetCellBackground()  is  a  convenient  way  to  specify  and  modify the
              XmNcellBackgrounds resource when changing the  background  of  a  single  cell.  If
              XmNcellBackgrounds  is NULL, then XbaeMatrixSetCellBackground() will create a Pixel
              table initialized to XmNforeground except for the cell specified in it's arguments.
              If  XmNcellBackgrounds is not NULL, then XbaeMatrixSetCellBackground() will changed
              the specified cell in that resource to the specified color.

       XbaeMatrixSetCellColor()

              void XbaeMatrixSetCellColor()
                     Widget      w;
                     int         row;
                     int         column;
                     Pixel       color;

              w         An XbaeMatrix widget.

              row       The row of the cell whose color should be set.

              column    The column of the cell whose color should be set.

              color     The new color to which to set this cell.

              XbaeMatrixSetCellColor() is a convenient way to specify and  modify  the  XmNcolors
              resource  when  changing  the  color  of  a single cell. If XmNcolors is NULL, then
              XbaeMatrixSetCellColor() will create a Pixel  table  initialized  to  XmNforeground
              except  for  the  cell  specified in it's arguments. If XmNcolors is not NULL, then
              XbaeMatrixSetCellColor() will changed the specified cell in that  resource  to  the
              specified color.

       XbaeMatrixSetCellPixmap()

              void XbaeMatrixSetCellPixmap()
                     Widget       w;
                     int          row;
                     int          column;
                     Pixmap       pixmap;
                     Pixmap       mask;

              w         A XbaeMatrix widget.

              row       The row of the cell whose pixmap and mask should be set.

              column    The column of the cell whose pixmap and mask should be set.

              pixmap    the function will store the contents of this Pixmap variable

              mask      the function will store the contents of this variable as the pixmap mask

              XbaeMatrixSetCellPixmap  will  set  the  pixmap  and  the  associated  mask  of the
              indicated cell.  If the row or column are out of bounds, or the widget  is  not  an
              XbaeMatrix  widget,  then  nothing is changed; this erroneous condition is silently
              ignored.

       XbaeMatrixSetCellShadow()

              void XbaeMatrixSetCellShadow()
                  Widget          w;
                  int             row;
                  int             column;
                  unsigned char   shadow_type;

              w         An XbaeMatrix widget.

              row       The row of the cell whose shadow should be set.

              column    The column of the cell whose shadow should be set.

              shadow_type
                        The value to which to set the cells shadow

              XbaeMatrixSetShadow() allows the application developer to programmatically set  the
              shadow of a specified cell.

       XbaeMatrixSetCellTag()

              void XbaeMatrixSetCellTag()
                   Widget        w;
                   int           row;
                   int           column;
                   XmStringTag   tag;

              w         An XbaeMatrix widget.

              row       The row of the cell whose tag should be set.

              column    The column of the cell whose tag should be set.

              tag       The value to which to set the cells tag

              XbaeMatrixSetTag()  allows  the  application  developer to programmatically set the
              font tag of a specified cell. This value is copied (quarkified).

       XbaeMatrixSetCellUserData()

              void XbaeMatrixSetCellUserData()
                     Widget         w;
                     int            row;
                     int            column;
                     XtPointer      data;

              w         An XbaeMatrix widget.

              row       The row of the cell whose value should be set.

              column    The column of the cell whose value should be set.

              data      A pointer to a user defined data area.

              XbaeMatrixSetCellUserData() allows the application  developer  to  programmatically
              set  the user data of a specified cell. To set the data value of many cells, it may
              be more efficient to do an XtSetValues() on  the  XmNcellUserData  resource.   This
              resource is copied.

       XbaeMatrixSetCellWidget()

              void XbaeMatrixSetCellWidget(w, row, column, widget)
                             Widget              w;
                             int                 row;
                             int                 column;
                             Widget              widget;

              XbaeMatrixSetCellWidget()  is  a function to attach a widget to a matrix cell.  The
              cell is selected by specifying its row and column , widget is the cell widget to be
              associated  with  that cell.  XbaeMatrix will manage the cell widget's position and
              size so it is displayed inside the cell at all times, including when scrolling.

              Using a NULL widget removes the link between a  widget  and  its  cell.   Only  one
              widget can be in a cell, a widget should also be in only one cell at a time.

       XbaeMatrixSetCellWidget()

              void XbaeMatrixSetCellWidget(w, row, column, widget)
                             Widget              w;
                             int                 row;
                             int                 column;
                             Widget              widget;

              XbaeMatrixSetCellWidget()  is  a function to attach a widget to a matrix cell.  The
              cell is selected by specifying its row and column , widget is the cell widget to be
              associated  with  that cell.  XbaeMatrix will manage the cell widget's position and
              size so it is displayed inside the cell at all times, including when scrolling.

              Using a NULL widget removes the link between a  widget  and  its  cell.   Only  one
              widget can be in a cell, a widget should also be in only one cell at a time.

       XbaeMatrixSetColumnBackgrounds()

              void XbaeMatrixSetColumnBackgrounds()
                      Widget        w;
                      int           position;
                      Pixel         *colors;
                      int           num_colors;

              w         An XbaeMatrix widget.

              position  The  column position at which to begin applying the new backgrounds. Must
                        be greater than or equal to zero, and (position  +  num_colors)  must  be
                        less than or equal to XmNcolumns.

              colors    Points  to an array of Pixel. These specify the backgrounds for the cells
                        in the specified columns. The colors array must have num_colors elements.

              num_colors
                        The number of colors in the colors array.

              XbaeMatrixSetColumnBackgrounds() is a convenient way  to  specify  and  modify  the
              XmNcellBackgrounds  resource  when  setting  the  background of an entire column or
              columns. If XmNcellBackgrounds is NULL, then XbaeMatrixSetColumnBackgrounds()  will
              create  a Pixel table initialized to XmNforeground except for the columns specified
              in    it's    arguments.    If    XmNcellBackgrounds    is    not    NULL,     then
              XbaeMatrixSetColumnBackgrounds()   will  changed  the  specified  columns  in  that
              resource to the specified colors.

       XbaeMatrixSetColumnColors()

              void XbaeMatrixSetColumnColors()
                     Widget     w;
                     int        position;
                     Pixel      *colors;
                     int        num_colors;

              w         An XbaeMatrix widget.

              position  The column position at which to begin applying the new  colors.  Must  be
                        greater  than  or equal to zero, and (position + num_colors) must be less
                        than or equal to XmNcolumns.

              colors    Points to an array of Pixel. These specify the colors for  the  cells  in
                        the specified columns. The colors array must have num_colors elements.

              num_colors
                        The number of colors in the colors array.

              XbaeMatrixSetColumnColors() is a convenient way to specify and modify the XmNcolors
              resource when setting the color of an entire column or  columns.  If  XmNcolors  is
              NULL,  then  XbaeMatrixSetColumnColors()  will  create a Pixel table initialized to
              XmNforeground except for the columns specified in it's arguments. If  XmNcolors  is
              not  NULL,  then  XbaeMatrixSetColumnColors() will changed the specified columns in
              that resource to the specified colors.

       XbaeMatrixSetColumnWidth()

              void XbaeMatrixSetColumnWidth()
                      Widget      w;
                      int         column;
                      int         width;

              w         An XbaeMatrix widget.

              column    The column whose width we'll be changing.

              width     The new width of this column.  A column width can be 0 to hide a column.

              XbaeMatrixSetColumnWidth() is a convenient way to change  the  width  of  a  column
              without the need to allocate an array with column width numbers.  Passing -1 as the
              new width will reset the column width to the default value.

       XbaeMatrixSetColumnLabel()

              void XbaeMatrixSetColumnLabel()
                      Widget      w;
                      int         column;
                      String      value;

              w         An XbaeMatrix widget.

              column    The column of the label is to be set.

              value     The new value of the label.

              XbaeMatrixSetColumnLabel() allows the  application  developer  to  programmatically
              change the label of a specified column.

       XbaeMatrixSetColumnShadow()

              void XbaeMatrixSetColumnShadow()
                  Widget          w;
                  int             column;
                  unsidned char   shadow_type;

              w         An XbaeMatrix widget.

              column    The column for which the shadow to be set.

              shadow_type
                        The new value of the shadow.

              XbaeMatrixSetColumnShadow()  allows  the  application developer to programmatically
              change the shadow of a specified column.

       XbaeMatrixSetColumnUserData()

              void XbaeMatrixSetColumnUserData()
                      Widget         w;
                      int            column;
                      XtPointer      data;

              w         An XbaeMatrix widget.

              column    The column whose value should be set.

              data      A pointer to a user defined data area.

              XbaeMatrixSetColumnUserData() allows the application developer to  programmatically
              associate user data for the specified column.

       XbaeMatrixSetRowBackgrounds()

              void XbaeMatrixSetRowBackgrounds()
                     Widget       w;
                     int          position;
                     Pixel        *colors;
                     int          num_colors;

              w         An XbaeMatrix widget.

              position  The  row  position  at  which  to  begin applying the new colors. Must be
                        greater than or equal to zero, and (position + num_colors) must  be  less
                        than or equal to XmNrows.

              colors    Points  to an array of Pixel. These specify the backgrounds for the cells
                        in the specified rows. The colors array must have num_colors elements.

              num_colors
                        The number of colors in the colors array.

              XbaeMatrixSetRowBackgrounds() is  a  convenient  way  to  specify  and  modify  the
              XmNcellBackgrounds  resource  when setting the background of an entire row or rows.
              If XmNcellBackgrounds is NULL, then  XbaeMatrixSetRowBackgrounds()  will  create  a
              Pixel  table  initialized  to  XmNforeground  except for the rows specified in it's
              arguments. If XmNcellBackgrounds is not  NULL,  then  XbaeMatrixSetRowBackgrounds()
              will changed the specified rows in that resource to the specified colors.

       XbaeMatrixSetRowColors()

              void XbaeMatrixSetRowColors()
                    Widget    w;
                    int       position;
                    Pixel     *colors;
                    int       num_colors;

              w         An XbaeMatrix widget.

              position  The  row  position  at  which  to  begin applying the new colors. Must be
                        greater than or equal to zero, and (position + num_colors) must  be  less
                        than or equal to XmNrows.

              colors    Points  to  an  array of Pixel. These specify the colors for the cells in
                        the specified rows. The colors array must have num_colors elements.

              num_colors
                        The number of colors in the colors array.

              XbaeMatrixSetRowColors() is a convenient way to specify and  modify  the  XmNcolors
              resource  when  setting  the  color of an entire row or rows. If XmNcolors is NULL,
              then  XbaeMatrixSetRowColors()  will  create   a   Pixel   table   initialized   to
              XmNforeground  except for the rows specified in it's arguments. If XmNcolors is not
              NULL, then  XbaeMatrixSetRowColors()  will  changed  the  specified  rows  in  that
              resource to the specified colors.

       XbaeMatrixSetRowHeight()

              void XbaeMatrixSetRowHeight()
                     Widget      w;
                     int         row;
                     int         height;

              w         An XbaeMatrix widget.

              row       The row whose height we'll be changing.

              height    The new height of this row.  A row height can be 0 to hide a row.

              XbaeMatrixSetRowHeight()  is a convenient way to change the height of a row without
              the need to allocate an array with row height  numbers.   Passing  -1  as  the  new
              height will reset the row's height to the default value.

       XbaeMatrixSetRowLabel()

              void XbaeMatrixSetRowLabel()
                     Widget      w;
                     int         row;
                     String      value;

              w         An XbaeMatrix widget.

              row       The row of the label is to be set.

              value     The new value of the label.

              XbaeMatrixSetRowLabel() allows the application developer to programmatically change
              the label of the specified row.

       XbaeMatrixSetRowShadow()

              void XbaeMatrixSetRowShadow()
                  Widget          w;
                  int             column;
                  unsigned char   shadow_type;

              w         An XbaeMatrix widget.

              row       The row whose shadow should be set.

              shadow_type
                        The value of the new shadow.

              XbaeMatrixSetRowShadow()  allows  the  application  developer  to  programmatically
              change the shadow for the specified row.

       XbaeMatrixSetRowUserData()

              void XbaeMatrixSetRowUserData()
                     Widget        w;
                     int           column;
                     XtPointer     data;

              w         An XbaeMatrix widget.

              row       The row whose value should be set.

              data      A pointer to a user defined data area.

              XbaeMatrixSetRowUserData()  allows  the  application  developer to programmatically
              associate user data for the specified row.

       XbaeMatrixSetXmColumnLabel()

              void XbaeMatrixSetXmColumnLabel()
                      Widget        w;
                      int           column;
                      XmString      value;

              w         An XbaeMatrix widget.

              column    The column of the xmLabel is to be set.

              value     The new value of the xmLabel.

              XbaeMatrixSetXmColumnLabel() allows the application developer  to  programmatically
              change the xmLabel of a specified column.

       XbaeMatrixSetXmRowLabel()

              void XbaeMatrixSetXmRowLabel()
                     Widget        w;
                     int           row;
                     XmString      value;

              w         An XbaeMatrix widget.

              row       The row of the xmLabel is to be set.

              value     The new value of the xmLabel.

              XbaeMatrixSetXmRowLabel()  allows  the  application  developer  to programmatically
              change the xmLabel of a specified row.

       XbaeMatrixSortColumns()

              void XbaeMatrixSortColumns()
                  Widget   w;
                  int      (*proc)(Widget, int, int, void *);
                  void     *user_data;

              w         An XbaeMatrix widget.

              proc      a pointer to a function that can compare columns.

              user_data a pointer the application can use for its own needs.

              XbaeMatrixSortColumns allows you to sort  the  columns  in  the  XbaeMatrix  widget
              according  to  criteria  determined by the proc function.  The proc function should
              have the above signature and functionality as demanded by  the  qsort(3)  function.
              It  will  be  called  with a the matrix being sorted, the indices of two columns to
              compare and the user_data pointer XbaeMatrixSortColumns was called with. It  should
              return -1, 0, or 1 as appropriate. It is guaranteed that the matrix does not change
              while sorting and the necessary reordering will only take place after the last call
              to proc has been made.

       XbaeMatrixSortRows()

              void XbaeMatrixSortRows()
                  Widget   w;
                  int      (*proc)(Widget, int, int, void *);
                  void     *user_data;

              w         An XbaeMatrix widget.

              proc      a pointer to a function that can compare rows.

              user_data a pointer the application can use for its own needs.

              XbaeMatrixSortRows  allows  you to sort the rows in the XbaeMatrix widget according
              to criteria determined by the proc function.  The proc  function  should  have  the
              above signature and functionality as demanded by the qsort(3) function.  It will be
              called with the matrix being sorted, the indices of two rows  to  compare  and  the
              user_data  pointer XbaeMatrixSortRows was called with. It should return -1, 0, or 1
              as appropriate. It is guaranteed that the matrix does not change while sorting  and
              the  necessary reordering will only take place after the last call to proc has been
              made.

       XbaeMatrixUnhighlightAll()

              void XbaeMatrixUnhighlightAll()
                       Widget         w;

              w         An XbaeMatrix widget.

              XbaeMatrixUnhighlightAll() allows the  application  developer  to  programmatically
              unhighlight  all  cells.   XbaeMatrixUnhighlightAll() erases the highlight from all
              cells.  All unsigned  chars  in  the  XmNhighlightedCells  array  will  be  set  to
              HighlightNone.

       XbaeMatrixUnhighlightCell()

              void XbaeMatrixUnhighlightCell()
                      Widget       w;
                      int          row;
                      int          column;

              w         An XbaeMatrix widget.

              row       The row of the cell to unhighlight.

              column    The column of the cell to unhighlight.

              XbaeMatrixUnhighlightCell()  allows  the  application developer to programmatically
              unhighlight a cell.  XbaeMatrixUnhighlightCell()  erases  the  highlight  from  the
              cell.   The  corresponding  unsigned  char in the XmNhighlightedCells array will be
              have its HighlightCell bit cleared.

       XbaeMatrixUnhighlightColumn()

              void XbaeMatrixUnhighlightColumn()
                       Widget       w;
                       int          column;

              w         An XbaeMatrix widget.

              column    The column to unhighlight.

              XbaeMatrixUnhighlightColumn() allows the application developer to  programmatically
              unhighlight  a  column.   XbaeMatrixUnhighlightColumn()  erases  the highlight from
              around the column if XmNgridType is XmGRID_COLUMN_SHADOW or from around  each  cell
              in   the   column   otherwise.    The   corresponding   unsigned   chars   in   the
              XmNhighlightedCells array will be have its HighlightColumn  or  HighlightOther  bit
              cleared, depending on whether XmNgridType is set to XmGRID_COLUMN_SHADOW or not.

       XbaeMatrixUnhighlightRow()

              void XbaeMatrixUnhighlightRow()
                       Widget       w;
                       int          row;

              w         An XbaeMatrix widget.

              row       The row to unhighlight.

              XbaeMatrixUnhighlightRow()  allows  the  application  developer to programmatically
              unhighlight a row.  XbaeMatrixUnhighlightRow() erases the highlight from around the
              row  if  XmNgridType  is  XmGRID_ROW_SHADOW  or  from  around  each cell in the row
              otherwise.  The corresponding unsigned chars in the XmNhighlightedCells array  will
              be  have  its  HighlightRow  or  HighlightOther  bit  cleared, depending on whether
              XmNgridType is set to XmGRID_ROW_SHADOW or not.

       XbaeMatrixVisibleCells()

              int XbaeMatrixVisibleCells()
                  Widget    w;
                  int       *top_row;
                  int       *bottom_row;
                  int       *left_column;
                  int       *right_column;

              w         An XbaeMatrix widget.

              top_row   The first row that is currently visible in the matrix.

              bottom_row
                        The last row that is currently visible in the matrix.

              left_column
                        The leftmost column that is currently visible in the matrix.

              right_column
                        The rightmost column that is currently visible in the matrix.

              XbaeMatrixVisibleCells()  allows  the  the  application  developer  to  obtain  the
              currently visible portion of the XbaeMatrix w.

       XbaeMatrixVisibleColumns()

              int XbaeMatrixVisibleColumns()
                       Widget        w;

              w         An XbaeMatrix widget.

              XbaeMatrixVisibleColumns() allows the the application developer to programmatically
              check how many columns are currently displayed in the XbaeMatrix  w.   A  partially
              visible column will be declared an entire column.

       XbaeMatrixVisibleRows()

              int XbaeMatrixVisibleRows()
                      Widget       w;

              w         An XbaeMatrix widget.

              XbaeMatrixVisibleRows()  allows  the  the application developer to programmatically
              check how many rows are currently displayed  in  the  XbaeMatrix  w.   A  partially
              visible row will be declared an entire row.

       XbaeGetVersionNum()

              int XbaeGetVersionNum()

              XbaeGetVersionNum()  is  a  function that returns the numeric representation of the
              version of the Xbae library that your program is working with.  This  is  the  run-
              time  version of the Xbae widgets, where XbaeVersion is a macro that represents the
              compile-time version.

              The numeric representation is a simple calculation based on the major,  minor,  and
              pico  numbers  representing  an  Xbae  widget release.  E.g. version 4.8.1 would be
              represented as 40801.

              Releases prior to 4.8.0 didn't have this functionality.

       XbaeGetVersionText()

              char * XbaeGetVersionText()

              XbaeGetVersionText() is a function that returns the textual representation  of  the
              version  of  the  Xbae library that your program is working with.  This is the run-
              time version of the Xbae widgets, where XbaeVersionTxt is a macro  that  represents
              the compile-time version.

Additional Behavior

       Using  XtSetValues  to  set the Matrix's XmNwidth resource to 0 will cause it to recompute
       it's horizontal size. It will request  a  new  size  which  results  in  XmNvisibleColumns
       columns  being  displayed. If XmNvisibleColumns is 0, then it will request a new size such
       that it does not need a horizontal ScrollBar (full horizontal size).

       Using XtSetValues to set the Matrix's XmNheight resource to 0 will cause it  to  recompute
       it's  vertical size. It will request a new size which results in XmNvisibleRows rows being
       displayed. If XmNvisibleRows is 0, then it will request a new size such that it  does  not
       need a vertical ScrollBar (full vertical size).

       An XtSetValues on XmNvisibleRows will cause the Matrix to request a new size which results
       in XmNvisibleRows non-fixed rows being displayed, only if the new value is different  than
       the old one.

       An  XtSetValues  on  XmNvisibleColumns  will  cause the Matrix to request a new size which
       results in the first XmNvisibleColumns non-fixed columns being displayed, only if the  new
       value is different than the old one.

       An  XtSetValues on any other resource will not result in a request for a new size. Setting
       other resources in conjunction with setting XmNwidth and/or XmNheight to 0 allows for more
       control of the Matrix's geometry.

       An  XtSetValues setting XmNrowLabelWidth to 0 will cause XmNrowLabelWidth to be set to the
       width of the longest row label.

Virtual Bindings

       The bindings for virtual keys are vendor specific.  For  information  about  bindings  for
       virtual buttons and keys, see VirtualBindings(3X).

AUTHOR

       Andrew  Wason (aw@bae.bellcore.com) of Bellcore, Piscataway NJ, wrote the original version
       of the Xbae widgets.  His final release of the widgets was version 3.8.

       Kevin Brannen (kbrannen@metronet.com) took over maintainership  following  Andrew  Wason's
       departure and released version 4.0.

       Andrew Lister (lister@db.com) maintained from 1995 to 1999.

SPECIAL THANKS

       Andrew Wason for the original idea and source code.
       Jay Schmidgall for his contributions.
       Nick Banyard for providing the multibyte extensions.
       Callum Gibson for the pattern parsing in the XbaeInput widget.
       Sascha Goebel for debugging the scroll-per-pixel code.
       Tobias Oed for lots of code cleanup and debugging.
       The  people  from  Arcad Systemhaus for code submission for XbaeMatrixSort and a couple of
       related functionalities, and easier pixmap support.

RELEASE

       This document describes XbaeMatrix, version 4.60.4.

SEE ALSO

       Core(3X), Composite(3X), XmManager(3X), XmScrollBar(3X), XbaeInput(3X), XmText(3X)

Notice of Limitation

       Bellcore, previous and current maintainers of the Xbae  widgets  (collectively  'authors')
       provide  this  information  solely  to  professionals  who  have the appropriate degree of
       experience to understand and interpret its contents in accordance with generally  accepted
       engineering or other professional standards and applicable regulations. No recommendations
       as to products or vendors is made or should be implied.

       While the information contained herein  has  been  prepared  from  sources  deemed  to  be
       reliable,  the authors reserve the right to revise the information without notice, but has
       no obligation to do so. Unless the recipient has  been  expressly  granted  a  license  by
       Bellcore  under separate applicable written agreement with Bellcore, no license, expressed
       or implied, is granted under  any  patents,  copyrights  or  other  intellectual  property
       rights. Use of the information is at your discretion and shall not be deemed an inducement
       by Bellcore  to  infringe  any  existing  or  later-issued  patent,  copyrights  or  other
       intellectual property right.

       THE  AUTHORS  MAKE  NO REPRESENTATIONS AND EXTENDS NO WARRANTIES, EXPRESS OR IMPLIED, WITH
       RESPECT TO THE INFORMATION, INCLUDING, BUT NOT  LIMITED  TO,  THE  IMPLIED  WARRANTIES  OF
       MERCHANTABILITY  AND  FITNESS  FOR  ANY  PARTICULAR  PURPOSE,  AND  THE  WARRANTY  AGAINST
       INFRINGEMENT OF PATENTS OR OTHER INTELLECTUAL PROPERTY RIGHTS. THE INFORMATION IS PROVIDED
       ``AS  IS'',  AND  IN NO EVENT SHALL THE AUTHORS OR ANY OF ITS AFFILIATES BE LIABLE FOR ANY
       DAMAGES, INCLUDING ANY LOST PROFITS OR OTHER INCIDENTAL OR CONSEQUENTIAL DAMAGES  RELATING
       TO THE INFORMATION.

       Copyright 1991, 1992 Bellcore.
       Copyright 1995-99 Andrew Lister All Rights Reserved.
       Copyright 1999-2002 LessTif Developers

       The above no warranty extends to all additions and contributions.  No contributor shall be
       held liable; this work is provided ``as is''.  If this is a problem for  you,  then  don't
       use this software.