SgGrid(3X) UNIX System V SgGrid(3X)
NAME
SgGrid - The SgGrid widget class
SYNOPSIS
#include <Sgm/Grid.h>
VERSION
This page documents the version of Sgm that accompanies
Motif 1.2.
DESCRIPTION
SgGrid 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 XmNcolumn 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 convenience 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;
Page 1 (printed 1/22/99)
SgGrid(3X) UNIX System V SgGrid(3X)
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);
Page 2 (printed 1/22/99)
SgGrid(3X) UNIX System V SgGrid(3X)
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 | *
Page 3 (printed 1/22/99)
SgGrid(3X) UNIX System V SgGrid(3X)
*| |*| | *
*|------------|*--------------| *
******************************************
* |*------------------------|*
* |*| |*
* |*| |*
* |*| |*
*|------------|*| |*
*| |*| |*
*| Button3 |*| Button4 |*
*| |*| |*
*|------------|*| |*
* |*| |*
* |*| |*
* |*| |*
* *-------------------------*
******************************************
Classes
SgGrid inherits behavior and resources from Core, Composite,
Constraint, 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 programmer to specify data. The programmer can also
set the resource values 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
Page 4 (printed 1/22/99)
SgGrid(3X) UNIX System V SgGrid(3X)
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
SgGridSetRowResizability and
SgGridSetColumnResizability, below). By default, this
factor is "1" for all widgets, leading to an equal
sizing strategy.
XmNdefaultLayout
Specifies a default spacing between rows and columns.
This value can be overriden on a per row/column basis
using SgGridSetColumnMargin 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
Page 5 (printed 1/22/99)
SgGrid(3X) UNIX System V SgGrid(3X)
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 randomly 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;
Page 6 (printed 1/22/99)
SgGrid(3X) UNIX System V SgGrid(3X)
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 contains. The margin is added to both
sides of each row or column, so adding a 1 pixel marign
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 Resources
SgGrid 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
Page 7 (printed 1/22/99)
SgGrid(3X) UNIX System V SgGrid(3X)
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
Page 8 (printed 1/22/99)
SgGrid(3X) UNIX System V SgGrid(3X)
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 INFORMATION
Composite(3X), Constraint(3X), Core(3X),
XmBulletinBoard(3X), SgCreateGrid, SgCreateGridDialog(3X),
and XmManager(3X).
Page 9 (printed 1/22/99)