SgGrid(3X)SgGrid(3X)NAMESgGrid — The SgGrid widget class
SYNOPSIS
#include <Sgm/Grid.h>
VERSION
This page documents the version of Sgm that accompanies Motif 1.2.
DESCRIPTIONSgGrid is a container widget with no input semantics of its own. It
arranges its children in a two dimensional grid of arbitrary size. Each
row and column of this grid may be separately designated as having a
fixed size or as having some degree of stretchability. In addition,
each child may be resizable in either or both directions, or forced to
a fixed size. If a child is a fixed size, and smaller than the cell
that contains it, the childs position within the cell is determined by
an XmNgravity resource.
Following are some important considerations in using an SgGrid widget:
The position of each child must be set using the XmNrow and XmN‐
column resources. If no position is specified, the child will be
placed in an unspecified free cell.
The resizability of each row and column must be set using conve‐
nience functions SgGridSetRowResize and SgGridSetColumnResize.
The default is for all rows and columns to be resizable. All
widgets are resized according to their relative natural size.
Unmapping a child has no effect on the SgGrid except that the
child is not mapped.
EXAMPLES
The following example creates a grid of four buttons that all size (and
resize) equally to fill one quarter of their parent.
createGrid(Widget parent) {
int n;
Arg args[10];
Widget grid, child1, child2, child3, child4;
n = 0;
XtSetArg(args[n], XmNnumRows, 2); n++;
XtSetArg(args[n], XmNnumColumns, 2); n++;
grid = SgCreateGrid( parent, "grid", args, n );
child1 = XtVaCreateManagedWidget( "child1",
xmPushButtonWidgetClass, grid,
XmNrow, 0,
XmNcolumn, 0,
NULL );
child2 = XtVaCreateManagedWidget( "child2",
xmPushButtonWidgetClass, grid,
XmNrow, 0,
XmNcolumn, 1,
NULL );
child3 = XtVaCreateManagedWidget( "child3",
xmPushButtonWidgetClass, grid,
XmNrow, 1,
XmNcolumn, 0,
NULL );
child4 = XtVaCreateManagedWidget( "child4",
xmPushButtonWidgetClass, grid,
XmNrow, 1,
XmNcolumn, 1,
NULL );
XtManageChild(grid); }
The following example creates four buttons. The top row has a fixed
vertical size, while the bottom row is resizable. The left column has a
fixed size, but the right column can be resized. The button in the
lower right can be resized, but the others cannot. The button in the
lower left cell, which can be resized vertically, floats in the middle
of its cell. The button in the upper right stays to the left of its
cell.
createGrid(Widget parent) {
int n;
Arg args[10];
Widget grid, chidl1, child2, child3, child4;
n = 0;
XtSetArg(args[n], XmNnumRows, 2); n++;
XtSetArg(args[n], XmNnumColumns, 2); n++;
grid = SgCreateGrid( parent, "grid", args, n );
SgGridSetColumnResizability(grid, 0, 0);
SgGridSetRowResizability(grid, 0, 0);
child1 = XtVaCreateManagedWidget( "child1",
xmPushButtonWidgetClass, grid,
XmNrow, 0,
XmNcolumn, 0,
NULL );
child2 = XtVaCreateManagedWidget( "child2",
xmPushButtonWidgetClass, grid,
XmNrow, 0,
XmNcolumn, 1,
XmNresizeHorizontal, FALSE,
XmNgravity, WestGravity,
NULL );
child3 = XtVaCreateManagedWidget( "child3",
xmPushButtonWidgetClass, grid,
XmNrow, 1,
XmNcolumn, 0,
XmNresizeVertical, FALSE,
XmNgravity, CenterGravity,
NULL );
child4 = XtVaCreateManagedWidget( "child4",
xmPushButtonWidgetClass, grid,
XmNrow, 1,
XmNcolumn, 1,
NULL );
XtManageChild(grid); }
This creates an initial layout like the following. The "*"'s are the
boundaries of each cell in the grid, while the "-"'s are the sides of
the button widgets. ********************************
* -------------*---------------*
* | |*| |*
* | Button1 |*| Button2 |*
* | |*| |*
* |-----------|*--------------|*
* ******************************
* |-----------|*--------------|*
* | |*| |*
* | Button3 |*| Button4 |*
* | |*| |*
* -------------*---------------*
********************************
When resized to be larger, this window will appear as follows:
******************************************
*--------------*--------------- *
*| |*| | *
*| Button1 |*| Button2 | *
*| |*| | *
*|------------|*--------------| *
******************************************
* |*------------------------|*
* |*| |*
* |*| |*
* |*| |*
*|------------|*| |*
*| |*| |*
*| Button3 |*| Button4 |*
*| |*| |*
*|------------|*| |*
* |*| |*
* |*| |*
* |*| |*
* *-------------------------*
******************************************
Classes
SgGrid inherits behavior and resources from Core, Composite, Con‐
straint, XmManager, and XmBulletinBoard classes.
The class pointer is sgGridWidgetClass.
The class name is SgGrid.
New Resources
The following table defines a set of widget resources used by the pro‐
grammer to specify data. The programmer can also set the resource val‐
ues for the inherited classes to set attributes for this widget. To
reference a resource by name or by class in a .Xdefaults file, remove
the XmN or XmC prefix and use the remaining letters. To specify one of
the defined values for a resource in a .Xdefaults file, remove the Xm
prefix and use the remaining letters (in either lowercase or uppercase,
but include any underscores between words). The codes in the access
column indicate if the given resource can be set at creation time (C),
set by using XtSetValues (S), retrieved by using XtGetValues (G), or is
not applicable (N/A).
SgGrid Resource Set
Name Class Type Default Access
─────────────────────────────────────────────────────────────────────
XmNnumRows XmCNumRows int 1 CG
XmNnumColumns XmCNumColumns int 1 CG
XmNshowGrid XmCShowGrid Boolean FALSE CSG
XmNautoLayout XmCAutoLayout Boolean TRUE CSG
XmNdefaultSpacing XmCDefaultSpacing Dimension 4 CSG
XmNnumRows
Specifies the number of rows in the grid. This resource must be
specified at widget creation time. The default is 1.
XmNnumColumns
Specifies the number of columns in the grid. This resource must
be specified at widget creation time. The default is 1.
XmNshowGrid
When TRUE, the SgGrid widget visibly displays the boundaries of
each cell in the grid. This can be useful for debugging resize
specifications. The default is FALSE.
XmNautoLayout
When TRUE (the default), all rows or columns that have a non-
zero resizability are sized according to the desired natural
size of the widgets in that row or column. If this resource is
FALSE, all widgets in resizable rows or columns are sized
according to a relative resizability factor (see SgGridSetRowRe‐
sizability and SgGridSetColumnResizability, below). By default,
this factor is "1" for all widgets, leading to an equal sizing
strategy.
XmNdefaultSpacing
Specifies a default spacing between rows and columns. This value
can be overridden on a per row/column basis using SgGridSet‐
ColumnMargin or SgGridSetRowMargin.
SgGrid Constraint Resource Set
Name Class Type Default Access
────────────────────────────────────────────────────────────────────────────────
XmNgravity XmCGravity int NorthWestGravity CSG
XmNresizeVertical XmCResizeVertical Boolean TRUE CSG
XmNresizeHorizontal XmCResizeHorizontal Boolean TRUE CSG
XmNrow XmCRow int dynamic CSG
XmNcolumn XmCColumn int dynamic CSG
XmNgravity
If a child widget is not resizable, and is smaller than the cell
that contains it, the child's gravity controls its position
within the cell. Gravity may be any of the gravity values
defined by Xlib except StaticGravity and ForgetGravity. The
default is NorthWestGravity; Note that gravity has no effect is
both verticalResize and horizontalResize are TRUE.
XmNresizeVertical
If TRUE, the child will be resized to fill the cell containing
it in the vertical direction. The default is TRUE;
XmNresizeHorizontal
If TRUE, the child will be resized to fill the cell containing
it in the horizontal direction. The default is TRUE;
XmNrow
Determines the row of the grid in which the child is placed. If
no row is specified, the child will be placed in a cell randomly
selected from those not currently occupied.
XmNcolumn
Determines the column of the grid in which the child is placed.
If no row is specified, the child will be placed in a cell ran‐
domly selected from those not currently occupied.
Grid Functions
SgGridSetRowResizability(widget, row, factor )
Widget widget ;
int row;
int factor;
Set the degree to which the specified row can be resized. The default
is a value of 1 for all rows, which means that all rows will be equally
resizable, if the value of XmNautoLayout is false. Setting this value
to 0 establishes the specified row as not resizable, regardless of the
setting of XmNautoLayout. Other values are taken relative to all other
rows. For example, if an SgGrid widget has three rows, whose resize
factors are set to 100, 100, and 200, the first and second rows will
occupy 1/4 (computed as: 100/(100+100+200)) of the space, while the the
third row will occupy one half of the available space.
SgGridSetColumnResizability( widget, col, factor )
Widget widget ;
int col;
int factor;
This function sets the resizability of individual columns, and works in
a similar fashion as SgGridSetRowResizability.
SgGridSetRowMargin(widget, row, margin )
Widget widget ;
int row;
Dimension margin;
Set the margin height of the specified row. Each row and column can
have a margin between it's edge and the widgets the row or column con‐
tains. The margin is added to both sides of each row or column, so
adding a 1 pixel margin grows the relevant dimension of the affected
row or column by 2 pixels.
SgGridSetColumnMargin( widget, col, margin )
Widget widget ;
int col;
Dimension margin;
Set the margin width of the specified column.
Inherited ResourcesSgGrid inherits behavior and resources from the following superclasses.
For a complete description of each resource, refer to the man page for
that superclass.
XmBulletinBoard Resource Set
Name Class Type Default Access
──────────────────────────────────────────────────────────────────────────────────
XmNallowOverlap XmCAllowOverlap Boolean True CSG
XmNautoUnmanage XmCAutoUnmanage Boolean True CG
XmNbuttonFontList XmCButtonFontList XmFontList dynamic CSG
XmNcancelButton XmCWidget Widget NULL SG
XmNdefaultButton XmCWidget Widget NULL SG
XmNdefaultPosition XmCDefaultPosition Boolean True CSG
XmNdialogStyle XmCDialogStyle unsigned char dynamic CSG
XmNdialogTitle XmCDialogTitle XmString NULL CSG
XmNfocusCallback XmCCallback XtCallbackList NULL C
XmNlabelFontList XmCLabelFontList XmFontList dynamic CSG
XmNmapCallback XmCCallback XtCallbackList NULL C
XmNmarginHeight XmCMarginHeight Dimension 0 CSG
XmNmarginWidth XmCMarginWidth Dimension 0 CSG
XmNnoResize XmCNoResize Boolean False CSG
XmNresizePolicy XmCResizePolicy unsigned char XmRESIZE_ANY CSG
XmNshadowType XmCShadowType unsigned char XmSHADOW_OUT CSG
XmNtextFontList XmCTextFontList XmFontList dynamic CSG
XmNtextTranslations XmCTranslations XtTranslations NULL C
XmNunmapCallback XmCCallback XtCallbackList NULL C
XmManager Resource Set
Name Class Type Default Access
────────────────────────────────────────────────────────────────────────────────────────────────────────
XmNbottomShadowColor XmCBottomShadowColor Pixel dynamic CSG
XmNbottomShadowPixmap XmCBottomShadowPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG
XmNforeground XmCForeground Pixel dynamic CSG
XmNhelpCallback XmCCallback XtCallbackList NULL C
XmNhighlightColor XmCHighlightColor Pixel dynamic CSG
XmNhighlightPixmap XmCHighlightPixmap Pixmap dynamic CSG
XmNinitialFocus XmCInitialFocus Widget dynamic CSG
XmNnavigationType XmCNavigationType XmNavigationType XmTAB_GROUP CSG
XmNshadowThickness XmCShadowThickness Dimension dynamic CSG
XmNstringDirection XmCStringDirection XmStringDirection dynamic CG
XmNtopShadowColor XmCBackgroundTopShadowColor Pixel dynamic CSG
XmNtopShadowPixmap XmCTopShadowPixmap Pixmap dynamic CSG
XmNtraversalOn XmCTraversalOn Boolean True CSG
XmNunitType XmCUnitType unsigned char dynamic CSG
XmNuserData XmCUserData Pointer NULL CSG
Composite Resource Set
Name Class Type Default Access
───────────────────────────────────────────────────────────────────────
XmNchildren XmCReadOnly WidgetList NULL G
XmNinsertPosition XmCInsertPosition XtOrderProc NULL CSG
XmNnumChildren XmCReadOnly Cardinal 0 G
Core Resource Set
Name Class Type Default Access
───────────────────────────────────────────────────────────────────────────────────────────────────────────────
XmNaccelerators XmCAccelerators XtAccelerators dynamic N/A
XmNancestorSensitive XmCSensitive Boolean dynamic G
XmNbackground XmCBackground Pixel dynamic CSG
XmNbackgroundPixmap XmCPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG
XmNborderColor XmCBorderColor Pixel XtDefaultForeground CSG
XmNborderPixmap XmCPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG
XmNborderWidth XmCBorderWidth Dimension 0 CSG
XmNcolormap XmCColormap Colormap dynamic CG
XmNdepth XmCDepth int dynamic CG
XmNdestroyCallback XmCCallback XtCallbackList NULL C
XmNheight XmCHeight Dimension dynamic CSG
XmNinitialResourcesPersistent XmCInitialResourcesPersistent Boolean True C
XmNmappedWhenManaged XmCMappedWhenManaged Boolean True CSG
XmNscreen XmCScreen Screen * dynamic CG
XmNsensitive XmCSensitive Boolean True CSG
XmNtranslations XmCTranslations XtTranslations dynamic CSG
XmNwidth XmCWidth Dimension dynamic CSG
XmNx XmCPosition Position 0 CSG
XmNy XmCPosition Position 0 CSG
Translations
SgGrid inherits translations from XmBulletinBoard.
RELATED INFORMATIONComposite(3X), Constraint(3X), Core(3X), XmBulletinBoard(3X), SgCreate‐
Grid, SgCreateGridDialog(3X), and XmManager(3X).
SgGrid(3X)
