.\" (c) Copyright 1994, 1995, Microline Software, Inc. ALL RIGHTS RESERVED
.\"
.\" THIS SOFTWARE IS FURNISHED UNDER A LICENSE AND MAY BE COPIED AND USED
.\" ONLY IN ACCORDANCE WITH THE TERMS OF THAT LICENSE AND WITH THE INCLUSION
.\" OF THE ABOVE COPYRIGHT NOTICE. THIS SOFTWARE AND DOCUMENTATION, AND ITS
.\" COPYRIGHTS ARE OWNED BY MICROLINE SOFTWARE AND ARE PROTECTED BY UNITED
.\" STATES COPYRIGHT LAWS AND INTERNATIONAL TREATY PROVISIONS.
.\"
.\" THE INFORMATION IN THIS SOFTWARE IS SUBJECT TO CHANGE WITHOUT NOTICE
.\" AND SHOULD NOT BE CONSTRUED AS A COMMITMENT BY MICROLINE SOFTWARE.
.\"
.\" THIS SOFTWARE AND REFERENCE MATERIALS ARE PROVIDED "AS IS" WITHOUT
.\" WARRANTY AS TO THEIR PERFORMANCE, MERCHANTABILITY, FITNESS FOR ANY
.\" PARTICULAR PURPOSE, OR AGAINST INFRINGEMENT. MICROLINE SOFTWARE
.\" ASSUMES NO RESPONSIBILITY FOR THE USE OR INABILITY TO USE THIS
.\" SOFTWARE.
.\"
.\" MICROLINE SOFTWARE SHALL NOT BE LIABLE FOR INDIRECT, SPECIAL OR
.\" CONSEQUENTIAL DAMAGES RESULTING FROM THE USE OF THIS PRODUCT. SOME
.\" STATES DO NOT ALLOW THE EXCLUSION OR LIMITATION OF INCIDENTAL OR
.\" CONSEQUENTIAL DAMAGES, SO THE ABOVE LIMITATIONS MIGHT NOT APPLY TO
.\" YOU.
.\"
.\" MICROLINE SOFTWARE SHALL HAVE NO LIABILITY OR RESPONSIBILITY FOR SOFTWARE
.\" ALTERED, MODIFIED, OR CONVERTED BY YOU OR A THIRD PARTY, DAMAGES
.\" RESULTING FROM ACCIDENT, ABUSE OR MISAPPLICATION, OR FOR PROBLEMS DUE
.\" TO THE MALFUNCTION OF YOUR EQUIPMENT OR SOFTWARE NOT SUPPLIED BY
.\" MICROLINE SOFTWARE.
.\"
.\" U.S. GOVERNMENT RESTRICTED RIGHTS
.\" This Software and documentation are provided with RESTRICTED RIGHTS.
.\" Use, duplication or disclosure by the Government is subject to
.\" restrictions as set forth in subparagraph (c)(1) of the Rights in
.\" Technical Data and Computer Software Clause at DFARS 252.227-7013 or
.\" subparagraphs (c)(1)(ii) and (2) of Commercial Computer Software -
.\" Restricted Rights at 48 CFR 52.227-19, as applicable, supplier is
.\" Microline Software, 41 Sutter St Suite 1374, San Francisco, CA 94104.
.\"
.TH XmLGrid 3X "R1" "XML1" "XML"
.SH NAME
XmLGrid
.SH SYNOPSIS
#include <XmL/Grid.h>
.LP
.SH DESCRIPTION
A grid consists of cells in rows and columns. There are three basic
cell types, defined by the nature of the cell content: TEXT (editable
text), LABEL (display only text) and PIXMAP (pixmap images). Cells and
regions within the grid may be formatted with borders and shadowing.
Rows and columns may be fixed on the top, bottom, left and right to
remain in view while scrolling horizontally or vertically. There may
be heading and footer rows at the top and bottom, and heading and
footer columns at the left and right, in addition to the content
rows and columns in the center of the grid. While headings and
footers must be fixed, content rows may scroll or may also be
fixed on the top, bottom, left and right.
.SS Class Information
Grid inherits from XmManager, Constraint, Composite and Core. Its
class pointer is xmlGridWidgetClass. Its class name is XmLGrid.
.SS New Resources
The grid resources defined below affect its overall layout and
appearance. Definitions of resources affecting rows, columns and
cells follow the grid resource definitions.
.nf
.ft B
Name Class
Type Default Access
.ft P
XmNallowColumnResize XmCAllowColumnResize
Boolean False CSG
XmNallowDragSelected XmCAllowDragSelected
Boolean False CSG
XmNallowDrop XmCAllowDrop
Boolean False CSG
XmNallowRowResize XmCAllowRowResize
Boolean False CSG
XmNblankBackground XmCBlankBackground
Pixel Dynamic CSG
XmNbottomFixedCount XmCBottomFixedCount
int 0 CSG
XmNbottomFixedMargin XmCBottomFixedMargin
Dimension 0 CSG
XmNcolumns XmCColumns
int 0 G
XmNdebugLevel XmCDebugLevel
char 0 CSG
XmNeditTranslations XmCTranslations
XtTranslations Dynamic CSG
XmNfontList XmCFontList
XmFontList Dynamic CSG
XmNfooterColumnCount XmCFooterColumnCount
int 0 G
XmNfooterRowCount XmCFooterRowCount
int 0 G
XmNheadingColumnCount XmCHeadingColumnCount
int 0 G
XmNheadingRowCount XmCHeadingRowCount
int 0 G
XmNhiddenColumns XmCHiddenColumns
int 0 G
XmNhiddenRows XmCHiddenRows
int 0 G
XmNhorizontalScrollBar XmCHorizontalScrollBar
Widget Dynamic G
XmNhorizontalSizePolicy XmCHorizontalSizePolicy
unsigned char XmCONSTANT CSG
XmNhsbDisplayPolicy XmCHsbDisplayPolicy
unsigned char XmAS_NEEDED CSG
XmNlayoutFrozen XmCLayoutFrozen
Boolean False CSG
XmNleftFixedCount XmCLeftFixedCount
int 0 CSG
XmNleftFixedMargin XmCLeftFixedMargin
Dimension 0 CSG
XmNrightFixedCount XmCRightFixedCount
int 0 CSG
XmNrightFixedMargin XmCRightFixedMargin
Dimension 0 CSG
XmNrows XmCRows
int 0 G
XmNscrollBarMargin XmCScrollBarMargin
Dimension 2 CSG
XmNscrollColumn XmCScrollColumn
int Dynamic CSG
XmNscrollRow XmCScrollRow
int Dynamic CSG
XmNselectBackground XmCSelectBackground
Pixel Dynamic CSG
XmNselectForeground XmCSelectForeground
Pixel Dynamic CSG
XmNselectionPolicy XmCGridSelectionPolicy
unsigned char XmSELECT_ CELL CSG
XmNshadowRegions XmCShadowRegions
int 511 CSG
XmNtextWidget XmCTextWidget
Widget Dynamic G
XmNtraverseTranslations XmCTranslations
XtTranslations Dynamic CSG
XmNtopFixedCount XmCTopFixedCount
int 0 CSG
XmNtopFixedMargin XmCTopFixedMargin
Dimension 0 CSG
XmNuseAverageFontWidth XmCUseAverageFontWidth
Boolean True CSG
XmNverticalScrollBar XmCVerticalScrollBar
Widget 0 G
XmNverticalSizePolicy XmCVerticalSizePolicy
unsigned char XmCONSTANT CSG
XmNvsbDisplayPolicy XmCVsbDisplayPolicy
unsigned char XmAS_NEEDED CSG
.fi
.IP XmNallowColumnResize
If True, the user may resize a column by dragging the right
edge of a cell in a heading row. When the user resizes a column,
the column's XmNcolumnSizePolicy is set to XmCONSTANT and the
column's XmNcolumnWidth is set to the pixel width chosen by the
user. If the grid contains no heading rows, this resource has no
effect. If False, interactive column resizing is disabled.
.IP XmNallowDragSelected
If True, the user may interactively drag cell contents (strings)
to a drop site. If False, dragging is disabled.
.IP XmNallowDrop
If True, the user is allow to drop cell contents (strings) into the
Grid. If False, the Grid will not register itself as a drop site.
.IP XmNallowRowResize
If True, the user may resize a row by dragging the bottom edge of
a cell in a heading column. When the user resizes a row, the
row's XmNrowSizePolicy is set to XmCONSTANT and the row's
XmNrowHeight is set to the pixel height chosen by the user. If
the grid contains no heading columns, this resource has no effect.
If False, interactive row resizing is disabled.
.IP XmNblankBackground
If a grid has a horizontal scrollbar which is scrolled completely
to the right or a vertical scrollbar which is scrolled to the
bottom, an empty area can exist after the last set of scrolling cells. The
color of this empty region is set by the XmNblankBackground
resource. It will only be visible when the grid is scrolled fully
to the right or bottom. This value is initially set to the background
color of the grid widget.
.IP XmNbottomFixedCount
The number of fixed rows at the bottom of the grid including
footer rows. Since footer rows must be fixed, this value may not
be set smaller than the number of footer rows. If this value is
greater than the total number of rows, then as additional rows
are added they will be fixed until this value is reached.
.IP XmNbottomFixedMargin
The height, in pixels, of the margin between the bottom fixed
rows and any rows above them.
.IP XmNcolumns
The number of content columns. The grid updates this resource
every time a content column is added or removed. To get the total
number of columns in the grid (heading, content and footer)
add this value to the number of heading and footer columns.
.IP XmNdebugLevel
If set to a value greater than 0, debugging messages will be
printed to stderr. When set to 0 (the default) only error
messages will be reported.
.IP XmNeditTranslations
The translations merged into the Text widget child of the grid
when the grid goes from traverse mode into edit mode.
.IP XmNfontList
The default font list for new cells. Changing this resource
does not affect existing cells. If this value is NULL, a
font list is obtained from the nearest parent that is a
subclass of BulletinBoard, MenuShell, or VendorShell.
.IP XmNfooterColumnCount
The number of footer columns. The grid updates this resource
every time a footer column is added or removed.
.IP XmNfooterRowCount
The number of footer rows. The grid updates this resource every
time a footer row is added or removed.
.IP XmNheadingColumnCount
The number of heading columns. The grid updates this resource
every time a heading column is added or removed.
.IP XmNheadingRowCount
The number of heading rows. The grid updates this resource every
time a heading row is added or removed.
.IP XmNhiddenColumns
The total number of hidden columns. The grid updates this
resource every time a column is hidden or unhidden. Hidden
columns are columns with a width of 0.
.IP XmNhiddenRows
The total number of hidden rows. The grid updates this resource
every time a row is hidden or unhidden. Hidden rows are rows
with a height of 0.
.IP XmNhorizontalScrollBar
The widget ID of the grid's horizontal ScrollBar.
.IP XmNhorizontalSizePolicy
Determines how the grid sizes itself horizontally. Possible values:
.nf
XmVARIABLE /* grid always requests full width */
XmCONSTANT /* user or parent sets grid width and
scrollbar is displayed if required */
.fi
If this value is XmVARIABLE, the grid determines the amount of
horizontal space required to display the entire grid and
requests this space from its parent. When the width of the grid
changes, it will request more or less space causing it to
shrink or expand as its parent widget allows. It will appear
truncated, without a horizontal ScrollBar, if not enough
space is given by the parent. If this value is XmCONSTANT the
user or the parent widget must define the grids width and a
horizontal ScrollBar will appear if needed.
.IP XmNhsbDisplayPolicy
When XmNhorizontalSizePolicy is XmCONSTANT, this resource
controls whether to display the horizontal scroll bar if
all rows fit in the viewing area. Possible values:
.nf
XmSTATIC /* scrollbar always displays */
XmAS_NEEDED /* scrolbar only displayed when
scrolling is possible */
.fi
.IP XmNlayoutFrozen
If True, the grid's layout is frozen and the grid will not
recompute its layout until this resource is set to False. When
this resource is set back to False, the layout will be recomputed
and the entire grid will redraw. When rows or columns are added
to or deleted from the grid, or if row heights, column widths or
margins are changed, the grid must recompute its layout by determining which
cells to display on the screen. If a number of changes to the
grid layout are going to take place, then by setting this resource
to True before executing the first change and setting it to False after
the last change is requested, the grid will not recompute its
layout after each change. Setting this value will not affect what
is displayed on the screen as it is only used to increase performance. If
only a single layout change is requested, such as when adding or
deleting a single range of rows or columns, this resource should
not be used in an attempt to increase performance as the change
may not require a redraw of the grid. This resource should also
not be used around code which does not cause the grid to recompute
its layout, such as changing cell or border colors, as that
would decrease performance.
.IP XmNleftFixedCount
The number of fixed columns at the left of the grid including
heading columns. Since heading columns must be fixed, this
value may not be set smaller than the number of heading columns. If
this value is greater than the total number of columns, then
as additional columns are added they will be fixed until this
value is reached.
.IP XmNleftFixedMargin
The width, in pixels, of the margin between the left fixed
columns and any columns to their right.
.IP XmNrightFixedCount
The number of fixed columns at the right of the grid including
footer columns. Since footer columns must be fixed, this value
may not be set smaller than the number of footer columns. If
this value is greater than the total number of columns, then
as additional columns are added they will be fixed until this
value is reached.
.IP XmNrightFixedMargin
The width, in pixels, of the margin between the right fixed
columns and any columns to their left.
.IP XmNrows
The number of content rows. The grid updates this resource
every time a content row is added or removed. To get the total
number of rows in the grid (heading, content and footer) add this value
to the number of heading and footer rows.
.IP XmNscrollBarMargin
The margin, in pixels, between the ScrollBars and the displayed cells.
.IP XmNscrollColumn
The left-most scrolling content column currently displayed.
This value may be set to change the current scroll position.
If setting this value causes the scroll position to change, the grid's scroll
callbacks will be called. If this value is set greater than the
last possible scrolling column, the grid will scroll to the last
possible scrolling column. If this value is set less than the first possible
scrolling column, the grid will scroll to the first possible scrolling column.
.IP XmNscrollRow
The top scrolling content row currently displayed. This value
may be set to change the current scroll position. If setting this
value causes the scroll position to change, the grid's scroll
callbacks will be called. If this value is set greater than the
last possible scrolling row, the grid will scroll to the last
possible scrolling row. If this value is set less than the first possible
scrolling row, the grid will scroll to the first possible scrolling row.
.IP XmNselectBackground
The background color of cells, rows or columns which are
currently selected. This value is initially set to the foreground
color of the grid widget.
.IP XmNselectForeground
The foreground color of cells, rows or columns which are
currently selected. This value is initially set to the background
color of the grid widget.
.IP XmNselectionPolicy
Determines the types of selections allowed in the grid.
In SELECT_NONE mode, user selections have no effect by default and
cell select callbacks are called each time a user selects a cell. The
application may set selections of rows/columns or cells. In
SELECT_SINGLE_ROW mode, one or zero content rows may be selected.
In SELECT_BROWSE_ROW mode, one content row must be selected at all
times. Initially, however, no rows are selected (the application should
select a first row). In SELECT_MULTIPLE_ROW, multiple content rows
may be selected. In any of the SELECT_..._ROW modes, when cells
in heading or footer rows are selected by a user, the grid will
call its cell select callbacks. Therefore, the application must
be sure to check the type of selection made in its select
callback(s). In SELECT_CELL mode, arbitrary regions of cells
in content rows and content columns may be selected. A user
may select cells in heading rows to select columns and cells
in heading columns to select rows. Possible values:
.nf
XmSELECT_NONE /* no selections */
XmSELECT_SINGLE_ROW /* 0 or 1 row selection */
XmSELECT_BROWSE_ROW /* 1 row selection */
XmSELECT_MULTIPLE_ROW /* multiple row selection */
XmSELECT_CELL /* multiple row, column, cell selections */
.fi
.IP XmNshadowRegions
Determines which regions are drawn with shadows. There are 9 regions
in the grid numbered as follows:
.nf
1 2 4
8 16 32
64 128 256
.fi
Where 1, 2 and 4 combine to make the top fixed rows. 1, 8 and 64
combine into the left fixed columns, 16 is the scrolling region,
etc. The value should be set to the summation of the regions
numbers which should be drawn with a shadow. For example, if
this value is set to 428 (64 + 128 + 256) the grid will draw
a shadow box around each region in the bottom row. Regions not
included are drawn without shadows.
.IP XmNtextWidget
The widget ID of the grid's Text widget.
.IP XmNtraverseTranslations
The translations merged into the Text widget child of the grid
when the grid goes from edit mode into traverse mode.
.IP XmNtopFixedCount
The number of fixed rows at the top of the grid including
heading rows. Since heading rows must be fixed, this value may
not be set smaller than the number of heading rows. If this value is
greater than the total number of rows, then as additional rows
are added they will be fixed until this value is reached.
.IP XmNtopFixedMargin
The height, in pixels, of the margin between the top fixed rows
and any rows below them.
.IP XmNuseAverageFontWidth
Cells in the grid which contain text calculate their preferred
width based on the font list character width of the font list
assigned to the cell. The grid calculates the font list character
width when font lists are assigned to cells. If the value of
this resource is True, the font list character width will be
calculated by averaging all of the glyph widths in the font list. If this
value is False, the font list character width will equal the
the maximum glyph width in the font list. Changing this resource
only affects font lists assigned after this value is changed, it does not
affect the current layout of the grid. Also, this resource
only affects cells containing proportional fonts since a fixed
width font's average glyph width will equal its maximum glyph width.
.IP XmNverticalScrollBar
The widget ID of the grid's vertical ScrollBar.
.IP XmNverticalSizePolicy
Determines how the grid sizes itself vertically. Possible values:
.nf
XmVARIABLE /* grid always requests full height */
XmCONSTANT /* user or parent sets grid height and
scrollbar is displayed if needed */
.fi
If this value is XmVARIABLE, the grid determines the amount
of vertical space required to display the entire grid and
requests this space from its parent. When the height of the grid
changes, it will request more or less space causing it to
shrink or expand as its parent widget allows. It will appear
truncated, without a vertical ScrollBar, if not enough space
is given by the parent. If this value is XmCONSTANT the user or
the parent widget must define the grids hheight and a vertical
ScrollBar will appear if needed.
.IP XmNvsbDisplayPolicy
When XmNverticalSizePolicy is XmCONSTANT, this resource
controls whether to display the vertical scroll bar if
all rows fit in the viewing area. Possible values:
.nf
XmSTATIC /* scrollbar always displays */
XmAS_NEEDED /* scrolbar only displayed when
scrolling is possible */
.fi
.SS Row/Column/Cell Resources
Grid defines the resources in the table below affecting rows,
columns and cells. A SetValues call can set values for a
single column using XmNcolumn or for a range of columns using
XmNcolumnRangeStart and XmNcolumnRangeEnd. Row values can be
set using XmNrow or XmNrowRangeStart and XmNrowRangeEnd.
Cell values can be set for a single cell using XmNcolumn and
XmNrow, or a range of cells using a variety of combinations
of row and column specifications. A GetValues call can retrieve
values for a column using XmNcolumnPtr, a row using XmNrowPtr,
and a cell using both XmNcolumnPtr and XmNrowPtr.
.nf
.ft B
Name Class
Type Default Access
.ft P
XmNcellAlignment XmCCellAlignment
unsigned char XmALIGNMENT_CENTER SG
XmNcellBackground XmCCellBackground
Pixel Dynamic SG
XmNcellBottomBorderPixel XmCCellBottomBorderPixel
Pixel Dynamic SG
XmNcellBottomBorderType XmCBottomBorderType
unsigned char XmBORDER_LINE SG
XmNcellColumnSpan XmCCellColumnSpan
int 0 SG
XmNcellDefaults XmCCellDefaults
Boolean False S
XmNcellFontList XmCCellFontList
XmFontList Dynamic SG
XmNcellForeground XmCCellForeground
Pixel Dynamic SG
XmNcellLeftBorderPixel XmCCellLeftBorderPixel
Pixel Dynamic SG
XmNcellLeftBorderType XmCCellLeftBorderType
unsigned char XmBORDER_LINE SG
XmNcellPixmap XmCCellPixmap
Pixmap XmUNSPECIFIED_PIXMAP SG
XmNcellRightBorderPixel XmCCellRightBorderPixel
Pixel Dynamic SG
XmNcellRightBorderType XmCCellRightBorderType
unsigned char XmBORDER_LINE SG
XmNcellRowSpan XmCCellRowSpan
int 0 SG
XmNcellString XmCXmString
XmString NULL SG
XmNcellTopBorderPixel XmCCellTopBorderPixel
Pixel Dynamic SG
XmNcellTopBorderType XmCCellTopBorderType
unsigned char XmBORDER_LINE SG
XmNcellType XmCCellType
unsigned char XmLABEL_CELL SG
XmNcellUserData XmCUserData
XtPointer 0 SG
XmNcolumn XmCColumn
int -1 S
XmNcolumnPtr (none)
XtPointer 0 G
XmNcolumnRangeEnd XmCColumnRangeEnd
int -1 S
XmNcolumnRangeStart XmCColumnRangeStart
int -1 S
XmNcolumnSizePolicy XmCColumnSizePolicy
unsigned char XmVARIABLE SG
XmNcolumnStep XmCColumnStep
int 1 S
XmNcolumnType XmCColumnType
unsigned char XmCONTENT S
XmNcolumnWidth XmCColumnWidth
Dimension 8 SG
XmNcolumnUserData XmCUserData
XtPointer 0 SG
XmNrow XmCRow
int -1 S
XmNrowHeight XmCRowHeight
Dimension 1 SG
XmNrowPtr (none)
XtPointer 0 G
XmNrowRangeEnd XmCRowRangeEnd
int -1 S
XmNrowRangeStart XmCRowRangeStart
int -1 S
XmNrowSizePolicy XmCRowSizePolicy
unsigned char XmVARIABLE SG
XmNrowStep XmCRowStep
int 1 S
XmNrowType XmCRowType
unsigned char XmCONTENT S
XmNrowUserData XmCUserData
XtPointer 0 SG
.fi
.IP XmNcellAlignment
Determines the alignment of the XmString or Pixmap contained in
the cell. Possible values:
.nf
XmALIGNMENT_LEFT /* left, centered vertically */
XmALIGNMENT_CENTER /* centered horizontally and vertically */
XmALIGNMENT_RIGHT /* right, centered vertically */
XmALIGNMENT_TOP_LEFT /* top left */
XmALIGNMENT_TOP /* top, centered horizontally */
XmALIGNMENT_TOP_RIGHT /* top right */
XmALIGNMENT_BOTTOM_LEFT /* bottom left */
XmALIGNMENT_BOTTOM /* bottom, centered horizontally */
XmALIGNMENT_BOTTOM_RIGHT /* bottom right */
.fi
If a cell Pixmap does not have a width or height set, the
cell's alignment will be top left regardless of the value of
this resource since any other alignment could not be calculated.
.IP XmNcellBackground
The cell's background color.
.IP XmNcellBottomBorderPixel
The color of the cell's bottom border. If the cell's bottom
border type is XmNONE, no bottom border will be drawn and this
resource has no effect. The default value of this resource is the
bottom shadow color of the grid.
.IP XmNcellBottomBorderType
Determines the type of border to draw at the bottom of
the cell. Possible values:
.nf
XmBORDER_NONE /* no border */
XmBORDER_LINE /* line border */
.fi
.IP XmNcellColumnSpan
The number of columns to the right that are spanned by this cell.
You may combine this with a row span to span both rows and columns.
When a cell spans into adjacent cells, those spanned cells are
not displayed; instead, the contents of the spanning cell are
displayed in the spanned area. This effectively makes the spanning
cell larger while not changing the cell's row or column size.
If cell spans overlap, the visual behavior of the spanned cells
will become undefined. If rows or columns are added or deleted
inside a spanned area, the visual behavior of the spanned
cells will become undefined. If rows or columns are moved or
reordered in a way which does not preserve existing cell spans,
the visual behavior of the spanned cells will become undefined. The
width of a column span in pixels cannnot exceed the maximum
value of the type Dimension. Setting a column span on a cell
sets its preferred cell width to 4 pixels. All cells in a span must
exist at the time the span is set.
.IP XmNcellDefaults
Setting this value to True in a SetValues call indicates that
the call is setting the default cell values. When cells are
created (by adding rows or columns), their attributes are
defined by the default cell values. This value is always reset
to False after a SetValues call completes.
.IP XmNcellFontList
The font list used for the cell's text. By default, the value
of this resource is set to the grid's XmNfontList. Changing this
value may cause the row or column containing the cell to resize if
the row's XmNrowSizePolicy or the column's XmNcolumnSizePolicy
is XmVARIABLE.
.IP XmNcellForeground
The cell's foreground color.
.IP XmNcellLeftBorderPixel
The color of the cell's left border. If the cell's left border
type is XmNONE, no left border will be drawn and this resource
has no effect. The default value of this resource is the top shadow
color of the grid.
.IP XmNcellLeftBorderType
Determines the type of border to draw at the left of the cell.
Possible values:
.nf
XmBORDER_NONE /* no border */
XmBORDER_LINE /* line border */
.fi
.IP XmNcellPixmap
The Pixmap to draw in the cell if the cell's type is XmPIXMAP_CELL.
As in other widgets, the grid does not make a copy of the Pixmap.
Therefore, the Pixmap should not be freed until it is
no longer required to be displayed by the grid. Changing this
value may cause the row or column containing the cell to resize
if the row's XmNrowSizePolicy or the column's XmNcolumnSizePolicy
is XmVARIABLE. This value may be XmUNSPECIFIED_PIXMAP.
.IP XmNcellRightBorderPixel
The color of the cell's right border. If the cell's right border
type is XmNONE, no right border will be drawn and this resource
has no effect. The default value of this resource is the bottom
shadow color of the grid.
.IP XmNcellRightBorderType
Determines the type of border to draw at the right of the cell.
Possible values:
.nf
XmBORDER_NONE /* no border */
XmBORDER_LINE /* line border */
.fi
.IP XmNcellRowSpan
The number of rows below that are spanned by this cell. You may
combine this with a column span to span both rows and columns.
When a cell spans into adjacent cells, those spanned cells
are not displayed; instead, the contents of the spanning cell
are displayed in the spanned area. This effectively makes the
spanning cell larger while not changing the cell's row or column size.
If cell spans overlap, the visual behavior of the spanned cells
will become undefined. If rows or columns are added or deleted
inside a spanned area, the visual behavior of the spanned cells will
become undefined. If rows or columns are moved or reordered in
a way which does not preserve existing cell spans, the visual
behavior of the spanned cells will become undefined. The height
of a row span in pixels cannnot exceed the maximum value of the
type Dimension. Setting a row span on a cell sets its preferred
cell height to 4 pixels. All cells in a span must exist at the time
the span is set.
.IP XmNcellString
The compound string to draw in the cell if the cell's type
is XmTEXT_CELL or XmLABEL_CELL. As in other widgets, the grid
makes a copy of the string and so the string may be freed after
it is used to set this value. Retrieving this value will return
a copy of the cell's string, therefore the retrieved string should
be freed when it will no longer be used. This value
may be NULL.
.IP XmNcellTopBorderPixel
The color of the cell's top border. If the cell's top border
type is XmNONE, no top border will be drawn and this resource
has no effect. The default value of this resource is the top shadow color
of the grid.
.IP XmNcellTopBorderType
Determines the type of border to draw at the top of the cell.
Possible values:
.nf
XmBORDER_NONE /* no border */
XmBORDER_LINE /* line border */
.fi
.IP XmNcellType
The type of the cell. Possible values:
.nf
XmLABEL_CELL /* cell displaying non-editable text */
XmTEXT_CELL /* cell containing editable text */
XmPIXMAP_CELL /* cell displaying a Pixmap */
.fi
Changing this value may cause the row or column containing the
cell to resize if the row's XmNrowSizePolicy or the column's
XmNcolumnSizePolicy is XmVARIABLE. Changing a cell's type from
XmLABEL_CELL or XmTEXT_CELL to XmPIXMAP_CELL will free the
XmNcellString currently contained in the cell and will set
the XmNcellString to NULL. Changing from XmPIXMAP_CELL to
XmLABEL_CELL or XmTEXT_CELL will cause the cell's XmNcellPixmap
to be set to XmUNSPECIFIED_PIXMAP.
.IP XmNcellUserData
A pointer value unused by the grid. This resource allows you
to attach a pointer to any cell in the grid.
.IP XmNcolumn
Defines which column(s) or cell(s) a SetValues call will affect.
A value of -1 (the default) means all columns. This value is
always reset to -1 after the SetValues call completes. The value of 0
defines the first column of a column type. This resource may not
be used in a GetValues call.
.IP XmNcolumnPtr
Defines which column, or column a cell is contained in, a
GetValues call should retrieve values for. This value is a
pointer to a column which should be obtained using XmLGridGetColumn().
This resource may not be used in a SetValues call.
.IP XmNcolumnRangeEnd
Defines the last column or column of cells in a range which a
SetValues call will affect. This resource may not be used in a
GetValues call. This resource must be used with the
XmNcolumnRangeStart resource.
.IP XmNcolumnRangeStart
Defines the first column or column of cells in a range which
a SetValues call will affect. This resource may not be used
in a GetValues call. This resource must be used with the
XmNcolumnRangeEnd resource.
.IP XmNcolumnSizePolicy
Defines how the column width is determined. Possible values:
.nf
XmCONSTANT /* column size is fixed */
XmVARIABLE /* column may resize when cell size changes */
.fi
If XmVARIABLE, the column will size itself to the maximum
preferred width of the column's cells. For cells containing text,
this usually equals the cell's average or maximum font list glyph
width multiplied by the XmNcolumnWidth (plus space for borders, etc).
If XmCONSTANT, the XmNcolumnWidth value is assumed to be in
pixels and the column width will equal that value.
.IP XmNcolumnStep
Defines the column increment when setting values of multiple
columns or cells in a SetValues call. For example, a column
step of 2 will skip every other column. This value is 1 by default
and will reset to 1 after a SetValues call completes.
.IP XmNcolumnType
Defines which type of columns or cells a SetValues call will
affect. This resource may not be used in a GetValues call.
Possible values:
.nf
XmALL_TYPES /* all column types - heading/content and footer */
XmCONTENT /* columns containing the grid's contents */
XmHEADING /* heading columns on the far left */
XmFOOTER /* footer columns on the far right */
.fi
This resource is used along with XmNcolumn or XmNcolumnRangeStart and
XmNcolumnRangeEnd and determines which type of column the column or
column range specifies. By default, this value is set to XmCONTENT.
This value is always reset to XmCONTENT after a SetValues call completes.
.IP XmNcolumnUserData
A pointer value unused by the grid. This resource allows you
to attach a pointer to any column in the grid.
.IP XmNcolumnWidth
If XmNcolumnSizePolicy is XmVARIABLE, the value of this resource
represents the column width in characters and if a font list in
any cell in the column is changed, the column will resize
if required. The pixel width of a column is determined by the
maximum preferred width of the column's cells. Cells containing
text usually determine their preferred width by multiplying the
cell's average or maximum font list glyph width by the column's
XmNcolumnWidth. Pixmap cells ignore this resource since their
preferred width is the width of their pixmap. If
XmNcolumnSizePolicy is XmCONSTANT, the value of this resource
represents the column width in pixels.
.IP XmNrow
Defines which row(s) or cell(s) a SetValues call will affect.
A value of -1 (the default) means all rows. The value of 0
defines the first row of a row type. This value is always
reset to -1 after a SetValues call completes. This resource
may not be used in a GetValues call.
.IP XmNrowHeight
If XmNrowSizePolicy is XmVARIABLE, the value of this resource
represents the row height in characters and if a font list in
any cell in this row is changed, the row will resize if required. The
pixel height of a row is determined by the maximum preferred
height of the row's cells. Cells containing text usually determine
their preferred height by taking their maximum font list
character height and multiplying it by the row's XmNrowHeight.
Pixmap cells ignore this resource since their preferred height
is the height of their pixmap. If XmNrowSizePolicy is
XmCONSTANT, the value of this resource represents the row height in pixels.
.IP XmNrowPtr
Defines which row, or row a cell is contained in, a GetValues
call should retrieve values for. This value is a pointer to a
row which should be obtained using XmLGridGetRow(). This
resource may not be used in a SetValues call.
.IP XmNrowRangeEnd
Defines the last row or row of cells in a range which a SetValues
call will affect. This resource may not be used in a GetValues
call. This resource must be used with the XmNrowRangeStart resource.
.IP XmNrowRangeStart
Defines the first row or row of cells in a range which a SetValues
call will affect. This resource may not be used in a GetValues call.
This resource must be used with the XmNrowRangeEnd resource.
.IP XmNrowSizePolicy
Defines how the row height is determined. Possible values:
.nf
XmCONSTANT /* row size is fixed */
XmVARIABLE /* row may resize when cell size changes */
.fi
If XmVARIABLE, the row will size itself to the maximum preferred
height of the row's cells. For cells containing text, this usually
equals the cell's maximum font list glyph height multiplied
by the XmNrowHeight (plus space for borders, etc). If XmCONSTANT,
the XmNrowHeight value is assumed to be in pixels and the row
height will equal that value.
.IP XmNrowStep
Defines the row increment when setting values of multiple rows
or cells in a SetValues call. For example, a row step of 2 will
skip every other row. This value is 1 by default and will reset to 1
when a SetValue call completes.
.IP XmNrowType
Defines which type of rows or cells a SetValues call will affect.
This resource may not be used in a GetValues call. Possible values:
.nf
XmALL_TYPES /* all row types - heading/content and footer */
XmCONTENT /* rows containing the grid's contents */
XmHEADING /* heading rows on the top */
XmFOOTER /* footer rows on the bottom */
.fi
This resource is used along with XmNrow or XmNrowRangeStart and
XmNrowRangeEnd and determines which type of row the row or row
range specifies. By default, this value is set to XmCONTENT.
This value is always reset to XmCONTENT after a SetValues call completes.
.IP XmNrowUserData
A pointer value unused by the grid. This resource allows you
to attach a pointer to any row in the grid.
.SS Callback Resources
Grid defines the following callback resources.
.nf
.ft B
Callback Reasons Called When
.ft P
XmNactivateCallback XmCR_ACTIVATE Cell is activated with
Return or double-click
XmNaddCallback XmCR_ADD_CELL Row, column or cell is
XmCR_ADD_COLUMN created by calling a function
XmCR_ADD_ROW which adds rows or columns
XmNcellDrawCallback XmCR_CELL_DRAW Cell with no value (has no
string/pixmap set) is drawn
XmNcellDropCallback XmCR_CELL_DROP Cell value was changed by new
value dropped into cell
XmNcellFocusCallback XmCR_CELL_FOCUS_IN Focus cell is set or changed
XmCR_CELL_FOCUS_OUT
XmNcellPasteCallback XmCR_CELL_PASTE Cell value was changed by new
value pasted into cell
XmNdeleteCallback XmCR_DELETE_CELL Row, column or cell is
XmCR_DELETE_COLUMN deleted by calling a
XmCR_DELETE_ROW function which deletes
rows or columns
XmNdeselectCallback XmCR_DESELECT_CELL Row, column or cell
XmCR_DESELECT_COLUMN changes from selected
XmCR_DESELECT_ROW to deselected (see also
XmNselectionPolicy resource)
XmNeditCallback XmCR_EDIT_BEGIN Cell edit begins, cancels,
XmCR_EDIT_CANCEL completes or when an
XmCR_EDIT_COMPLETE insert-begin occurs in
XmCR_EDIT_INSERT a cell
XmNresizeCallback XmCR_RESIZE_ROW Row or column is resized
XmCR_RESIZE_COLUMN interactively
XmNscrollCallback XmCR_SCROLL_ROW Current scrolled row or
XmCR_SCROLL_COLUMN column position changes
XmNselectCallback XmCR_SELECT_CELL Row, column or cell is
XmCR_SELECT_COLUMN selected (see also
XmCR_SELECT_ROW XmNselectionPolicy resource)
.fi
.SS Callback Structure
Each callback function is passed a pointer to the structure
shown below; however, only those values which are meaningful
for the callback are set.
.nf
typedef struct
{
int reason; /* callback reason */
XEvent *event; /* event causing callback or NULL */
int rowType, columnType; /* row and column types */
int row, int column; /* row and column positions */
XRectangle *clipRect; /* clipping rectangle */
XmLGridDrawInfoStruct *drawInfo; /* pointer to draw info */
void *object; /* reserved */
} XmLGridCallbackStruct;
.fi
The drawInfo pointer is set to point to the structure below for
XmNcellDraw callbacks.
.nf
typedef struct
{
GC gc; /* GC used for drawing */
XRectangle *cellRect; /* dimensions and location of
cell to draw */
Pixel selectBackground, selectForeground;
/* select foreground and background */
Boolean hasFocus; /* True if cell has focus */
Boolean isSelected; /* True if cell, row, or column
is selected */
XmStringDirection stringDirection;
/* direction for string drawing */
} XmLGridDrawInfoStruct;
.fi
The following table shows which values are set for which callback
reasons. Elements not set will have undefined values.
.nf
.ft B
Reason Values Set
.ft P
XmCR_ACTIVATE event, rowType, columnType, row, column
XmCR_ADD_CELL rowType, columnType
XmCR_ADD_COLUMN columnType
XmCR_ADD_ROW rowType
XmCR_CELL_DRAW event, rowType, columnType, row, column,
clipRect, drawInfo
XmCR_CELL_FOCUS_IN rowType, columnType, row, column
XmCR_CELL_FOCUS_OUT rowType, columnType, row, column
XmCR_DELETE_CELL rowType, columnType
XmCR_DELETE_COLUMN columnType
XmCR_DELETE_ROW rowType
XmCR_DESELECT_CELL rowType, columnType, row, column
XmCR_DESELECT_COLUMN columnType, column
XmCR_DESELECT_ROW rowType, row
XmCR_EDIT_BEGIN rowType, columnType, row, column
XmCR_EDIT_COMPLETE rowType, columnType, row, column
XmCR_EDIT_CANCEL rowType, columnType, row, column, clipRect
XmCR_EDIT_INSERT rowType, columnType, row, column, clipRect
XmCR_RESIZE_ROW rowType, row
XmCR_RESIZE_COLUMN columnType, column
XmCR_SCROLL_ROW rowType, row
XmCR_SCROLL_COLUMN columnType, column
XmCR_SELET_CELL rowType, columnType, row, column
XmCR_SELECT_COLUMN columnType, column
XmCR_SELECT_ROW rowType, row
.ni
.SS Inherited Resources
Grid inherits the resources shown below. The grid resets its
default XmNshadow-Thickness to 2.
.nf
.ft B
Resource From Resource From
.ft P
XmNaccelerators Core XmNinitialResourcePersist Core
XmNancestorSensitive Core XmNinsertPosition Composite
XmNbackground Core XmNmappedWhenManaged Core
XmNbackgroundPixmap Core XmNnavagationType Manager
XmNborderColor Core XmNnumChildren Composite
XmNborderPixmap Core XmNscreen Core
XmNborderWidth Core XmNsensitive Core
XmNbottomShadowColor Manager XmNshadowThicknses Manager
XmNbottomShadowPixmap Manager XmNstringDirection Manager
XmNchildren Composite XmNtopShadowColor Manager
XmNcolormap Core XmNtopShadowPixmap Manager
XmNdepth Core XmNtranslations Core
XmNdestroyCallback Core XmNtraversalOn Manager
XmNforeground Manager XmNunitType Manager
XmNheight Core XmNuserData Manager
XmNhelpCallback Manager XmNwidth Core
XmNhighlightColor Manager XmNx Core
XmNhighlightPixmap Manager XmNy Core
.fi
.SS Grid Translations
Grid defines the translations shown below.
.nf
.ft B
Event Action Event Action
.ft P
BSelect Press XmLGridSelect(BEGIN) BExtend Motion XmLGridButtonMotion()
BExtend Press XmLGridSelect(EXTEND) BToggle Motion XmLGridButtonMotion()
BToggle Press XmLGridSelect(TOGGLE) BSelect Release XmLGridSelect(END)
BSelect Motion XmLGridButtonMotion() BExtend Release XmLGridSelect(END)
.fi
.SS Grid Text Traverse Translations
When the grid widget enters traverse mode, it overrides its Text
widget child's translations with those shown below.
.nf
.ft B
Event Action
.ft P
KUp XmLGridTraverse(UP)
MCtrl KPageDown XmLGridTraverse(PAGE_RIGHT)
MShift KUp XmLGridTraverse(EXTEND_UP)
MCtrl MShift KPageDown XmLGridTraverse(EXTEND_ PAGE_RIGHT)
MCtrl KUp XmLGridTraverse(PAGE_UP)
KTab XmLGridTraverse(RIGHT)
KDown XmLGridTraverse(DOWN)
MShift KTab XmLGridTraverse(LEFT)
MShift KDown XmLGridTraverse(EXTEND_DOWN)
KBeginLine XmLGridTraverse(TO_TOP)
MCtrl KDown XmLGridTraverse(PAGE_DOWN)
KEndLine XmLGridTraverse(TO_BOTTOM)
KLeft XmLGridTraverse(LEFT)
KHome XmLGridTraverse(TO_TOP)
MShift KLeft XmLGridTraverse(EXTEND_LEFT)
MCtrl KHome XmLGridTraverse(TO_TOP_LEFT)
MCtrl KLeft XmLGridTraverse(PAGE_LEFT)
KEnd XmLGridTraverse(TO_BOTTOM)
KRight XmLGridTraverse(RIGHT)
MCtrl KEnd XmLGridTraverse(TO_BOTTOM_RIGHT)
MShift KRight XmLGridTraverse(EXTEND_RIGHT)
KInsert XmLGridEdit()
MCtrl KRight XmLGridTraverse(PAGE_RIGHT)
KF2 XmLGridEdit()
KPageUp XmLGridTraverse(PAGE_UP)
KSelect Press XmLGridSelect(BEGIN)
MShift KPageUp XmLGridTraverse(EXTEND_ PAGE_UP)
MCtrl KSelect Press XmLGridSelect(TOGGLE)
MCtrl KPageUp XmLGridTraverse(PAGE_LEFT)
KSelect Release XmLGridSelect(END)
MCtrl MShift KPageUp XmLGridTraverse(EXTEND_ PAGE_LEFT)
KEntend Press XmLGridSelect(EXTEND)
KPageDown XmLGridTraverse(PAGE_DOWN)
KExtend Release XmLGridSelect(END)
MShift KPageDown XmLGridTraverse(EXTEND_ PAGE_DOWN)
KActivate XmLGridSelect(ACTIVATE)
.fi
.SS Grid Text Edit Translations
When the grid widget enters edit mode, it overrides its Text
widget child's translations with those shown below.
.nf
.ft B
Event Action Event Action
.ft P
KDown XmLGridEditComplete(DOWN) KCancel XmLGridEditCancel()
MShift KTab XmLGridEditComplete(LEFT) KActivate XmLGridEditComplete()
KTab XmLGridEditComplete(RIGHT) KUp XmLGridEditComplete(UP)
.fi
.SS Action Routines
Grid defines the actions shown below.
.IP XmLGridButtonMotion()
Moves any active resize line or extends the current selection if needed.
.IP XmLGridCursorMotion()
Changes the cursor to a resize cursor if it is over a resize area.
.IP XmLGridEdit()
Enters the grid into edit mode and begins an edit of the current focus cell.
.IP XmLGridEditCancel()
Cancels any cell edit in progress and returns the grid to traverse mode.
.IP XmLGridEditComplete(direction)
Completes any edit in progress and traverses in the direction specified.
.IP XmLGridSelect(mode)
Begins or completes selection of the mode type given depending
on the event passed to the action function.
.IP XmLGridTraverse(direction)
Traverses in the given direction from the current focus cell.
If traversal is successful, the new focus cell will be made
visible, scrolling the grid if necessary.
.SH "SEE ALSO"
XmLCreateGrid(3X) XmLGridAddColumns(3X) XmLGridAddRows(3X)
XmLGridColumnIsVisible(3X) XmLGridDeleteAllColumns(3X) XmLGridDeleteAllRows(3X) XmLGridDeleteColumns(3X) XmLGridDeleteRows(3X) XmLGridDeselectAllCells(3X)
XmLGridDeselectAllColumns(3X) XmLGridDeselectAllRows(3X)
XmLGridDeselectCell(3X) XmLGridDeselectColumn(3X) XmLGridDeselectRow(3X)
XmLGridEditBegin(3X) XmLGridEditCancel(3X) XmLGridEditComplete(3X)
XmLGridGetCell(3X) XmLGridGetColumn(3X) XmLGridGetFocus(3X)
XmLGridGetRow(3X) XmLGridGetSelectedCellCount(3X) XmLGridGetSelectedCells(3X)
XmLGridGetSelectedColumnCount(3X) XmLGridGetSelectedColumns(3X)
XmLGridGetSelectedRow(3X) XmLGridGetSelectedRowCount(3X)
XmLGridGetSelectedRows(3X) XmLGridMoveColumns(3X) XmLGridMoveRows(3X)
XmLGridRead(3X) XmLGridReadPos(3X) XmLGridRedrawAll(3X) XmLGridRedrawCell(3X)
XmLGridRedrawColumn(3X) XmLGridRedrawRow(3X) XmLGridReorderColumns(3X)
XmLGridReorderRows(3X) XmLGridRowColumnToXY(3X) XmLGridRowlsVisible(3X)
XmLGridSelectAllCells(3X) XmLGridSelectAllColumns(3X) XmLGridSelectAllRows(3X)
XmLGridSelectCell(3X) XmLGridSelectColumn(3X) XmLGridSelectRow(3X)
XmLGridSetFocus(3X) XmLGridSetStrings(3X) XmLGridSetStringsPos(3X)
XmLGridWrite(3X) XmLGridWritePos(3X) XmLGridXYToRowColumn(3X)