NAME

SYNOPSIS

Include File:

#include <Xmt/Layout.h>

Constructor:

XmtCreateLayout()

Class Name:

XmtLayout

Class Pointer:

xmtLayoutWidgetClass

Class Hierarchy:

Core → Composite → Constraint → XmManager → XmBulletinBoard → XmtLayout

DESCRIPTION

Children of the Layout widget are laid out in nested rows and columns, with specified amounts of blank space between them. All children (including rows and columns), and the space between the children have a ``stretchiness'' factor that specifies how much each child or space will grow when the widget is resized. This is a fully general layout scheme, derived from the TeX ``boxes-and-glue'' text layout algorithm. It is as powerful and flexible as the ``attachment'' scheme used by the XmForm widget, for example, but easier to understand, and through the layout grammar, far easier to specify.

The Layout widget provides some features beyond simple layout of widgets. It will draw a frame around any of its children, will draw a separator running along any edge of any child, and can also display a text caption for each of its children. Since the Layout widget does this drawing itself, the overhead of the XmFrame, XmSeparator, and XmLabel widgets that would otherwise be needed is avoided. The Layout widget also supports special gadget children that display text and pixmap labels. These gadgets are cheaper than widgets, and are even cheaper than the Motif XmGadget types.

Finally, the Layout widget allows the sizes of its children to be specified in resolution-independent units. The static layout grammar allows sizes to be directly specified in inches, millimeters, points, ems or ens, and a public function exists to convert from these units to pixels for dynamic layouts.

RESOURCES

Layout inherits the resources of the XmBulletinBoard class, and defines or overrides the following resources:

XmtNdebugLayout

If True, the Layout widget will draw a one pixel wide frame around each of its children, including spaces, rows and columns. This makes it easy to see which nested row or column each child is positioned in, and can help when debugging layouts. When this resource is set, XmtNlayoutFrameType and the other frame constraint resources, described below, are ignored.

XmtNdefaultSpacing

The width or height, in pixels, of the fixed-size, nonstretchable space specified in the layout grammar with the `#' character. This value is not directly used by the Layout widget or the XmtLayoutSpace gadget.

XmtNfont

An XFontStruct pointer used to set the XmtNfontList resource if it is left unspecified. This resource is provided because it is sometimes more convenient to specify an Xlib XFontStruct than a Motif XmFontList.

XmtNfontList

The XmFontList that is be used by all XmtLayoutString gadget children and may also be used other XmtLayout Gadget children that draw text. If this resource is unspecified, the XmtNfont resource will be used to create an XmFontList instead.

XmtNlayout

A string that specifies a static layout for the children of the Layout widget. In order for this resource to work, the application programmer must register the layout grammar parser by calling XmtRegisterLayoutParser(). See the ``Layout Grammar'' section below for more information. This resource should be set when the Layout widget is created, and may never be changed. The Layout widget parses this string once, without modifying it, and never refers to it again. For this reason, the widget does not make a copy of the string, which means that this resource should not be queried.

XmNmarginHeight

The height, in pixels of the margin between the top and bottom edges of the widget and the nearest child. This is an XmBulletinBoard resource; the Layout widget over rides the default value to 5 pixels.

XmNmarginWidth

The width, in pixels of the margin between the left and right edges of the widget and the nearest child. This is an XmBulletinBoard resource; the Layout widget over rides the default value to 5 pixels.

XmtNorientation

The orientation of the topmost (automatically created) row or column of the Layout widget. Children widgets that are not explicitly positioned in a row or column with constraint resources will be placed in this toplevel row or column. Legal values are XmVERTICAL and XmHORIZONTAL. XmVERTICAL is the default, so that the Layout widget arranges its children in a column. This resource may be set when the Layout widget is created, but may never be changed.

Constraint RESOURCES The Layout widget specifies the layout and decoration of its children through constraint resources. Each of the constraint resource names begins with the prefix ``layout'' in order to avoid name clashes with the resources of the child widgets to which these constraints are applied.

The Layout constraint resources are the following:

XmtNlayoutAfter

The widget directly after which, in the same row or column, this child should be laid out. Setting this resource positions the child in the Layout widget and causes the XmtNlayoutBefore, XmtNlayout In, and XmtNlayoutPosition constraint resources to be updated to reflect the new position. If this resource is set, it overrides those other position resources.

XmtNlayoutAllowResize

Whether the Layout widget will attempt to grant resize requests from children. If False, any geometry request from this child will be refused. The default is True.

XmtNlayoutBefore

The widget directly before which, in the same row or column, this child should be laid out. Setting this resource positions the child in the Layout widget and causes the XmtNlayoutAfter, XmtNlayoutIn, and XmtNlayoutPosition constraint resources to be updated to reflect the new position. The XmtNlayoutAfter resource overrides this resource, if it is set, and this resource overrides the XmtNlayoutIn and XmtNlayoutPosition resources.

XmtNlayoutCaption

An XmString to be displayed by the Layout widget as a caption for this child. This string is drawn entirely by the Layout widget without the need for an XmLabel or any other widget or gadget.

XmtNlayoutCaptionAlignment

The alignment of lines within a multi-line caption. This resource is of the same type as the XmNalignment resource of the XmLabel widget and has three legal values: XmALIGNMENT_BEGINNING which draws the lines flush left with the bounding box of the whole string, XmALIGNMENT_CENTER, which centers the individual lines within the box, and XmALIGNMENT_END which draws the lines flush right. This resource only has effect when the caption has more than one line; it controls the positioning of individual lines relative to the caption as a whole. Do not confuse it with the XmtNlayoutCaptionJustification resource which controls the positioning of the entire caption relative to the widget.

XmtNlayoutCaptionJustification

The justification of the caption along the edge specified by the XmtNlayoutCaptionPosition resource. For captions placed along the left or right edges of the widget, this resource controls the vertical justification of the caption, and for captions placed along the top or bottom edges, it controls the horizontal justification. The values XmtLayoutFlushLeft and XmtLayoutFlushTop are equivalent and both produce left or top justification depending upon the XmtNlayoutCaptionPosition resource. The value XmtLayoutCentered centers the caption vertically or horizontally, and the values XmtLayoutFlushRight and XmtLayoutFlushBottom produce right or bottom justification.

XmtNlayoutCaptionMargin

The distance, in pixels, between the closest edge of the caption and the child widget, or between the caption and the frame surrounding the child widget. To save space in the Layout constraint record, this resource is stored in a unsigned character field, and therefore has a maximum value of 255 pixels.

XmtNlayoutCaptionPosition

The edge of the child widget along which the caption should be displayed. Legal values are XmtLayoutLeft, XmtLayoutRight, XmtLayoutTop, and XmtLayoutBottom.

XmtNlayoutFrameLineType

The style of line to be used for the frame. The values XmtLayoutFrameShadowIn, XmtLayoutFrameShadowOut, XmtLayoutFrameEtchedIn, and XmtLayoutFrameEtchedOut draw the standard shadowed and etched frames supported by the XmFrame widget. XmtLayoutFrameSingleLine draws a single line in the foreground color, with its width specified by the XmtNlayoutFrameThickness constraint. XmtLayoutFrameDoubleLine draws two single-pixel wide lines, with a separation determined by the XmtNlayoutFrameThickness constraint. When the XmtNlayoutFrameType resource specifies that the frame should be drawn as a separator along only one edge of the widget, the ``shadow in'' and ``shadow out'' types are drawn as ``etched in'' and ``etched out''.

XmtNlayoutFrameMargin

The distance, in pixels, between the inside of the frame and the child widget, or the frame and the caption, if a caption is specified and appears within the frame. For efficiency, this resource is stored in an unsigned character field of the Layout constraint record. This means that the maximum value of this resource is 255.

XmtNlayoutFramePosition

How the frame should be positioned with respect to the caption, if any, of the child. The value XmtLayoutFrameInside specifies that the frame should be drawn inside of the caption. In this case, the position of the caption may be adjusted, depending on its justification, so that it is flush with an outside edge of the frame rather than an edge of the child widget itself. The value XmtLayoutFrameOutside specifies that the frame should surround both the child widget and its caption. The value XmtLayoutFrameThrough specifies that the frame and caption should be drawn independently at the distances from the child specified by the XmtNlayout FrameMargin and XmtNlayoutCaptionMargin constraints. By default, this will cause the caption to be drawn over a portion of the frame, which produces an appealing visual effect with some line types.

XmtNlayoutFrameThickness

The line thickness of the frame to be drawn. This resource is stored in an unsigned character field of the Layout constraint record. This means that the maximum value for this resource is 255.

XmtNlayoutFrameType

The type of frame to be drawn. The default value, XmtLayoutFrameNone specifies that no frame is to be drawn. XmtLayoutFrameBox specifies that a traditional frame is to be drawn as a box around the child. The remaining legal values for this resource, XmtLayoutFrameLeft, XmtLayoutFrameRight, XmtLayoutFrameTop, and XmtLayoutFrameBottom, specify that the frame is to be drawn only along one edge of the widget. In this case, the frame serves as a separator, like those drawn by the Motif XmSeparator widget.

XmtNlayoutHeight

The preferred height, in pixels, of this child. If specified, this is the initial height of the child, and is the base height from which the child will stretch or shrink. If set to 0, the child's preferred height will be used. Note that this size does not include any space required for the child's margins, caption, or frame.

XmtNlayoutIn

The row or column gadget within which this child should be laid out. Setting this constraint resource, in conjunction with XmtNlayoutPosition resource, positions the child in the Layout widget and causes the XmtNlayoutAfter and XmtNlayoutBefore resources to be set to reflect the position. The XmtNlayoutAfter and XmtNlayoutBefore resources override this resource, if either is set. If none of these resources are set, then the child will be positioned in the topmost row or column. The orientation of this topmost box is determined by the Layout XmtNorientation resource.

XmtNlayoutJustification

The justification of this child within the width of its column, or within the height of its row. This resource is of type XmtLayoutJustification which is an enumerated type with the following legal values: XmtLayoutFilled, XmtLayoutCentered, XmtLayoutFlushLeft, XmtLayoutFlushTop, XmtLayoutFlushRight, and XmtLayoutFlushBottom. The default is XmtLayoutFilled which specifies that the child should be as wide as its containing column or as high as its containing row. The other values indicate that the child should be laid out at its natural size against the left, top, right, or bottom edges of the containing row or column, or centered within its containing row or column. Note that this resource only positions child widgets within the ``minor dimension'' of a row or column-vertically in a row and horizontally in a column.

XmtNlayoutMarginHeight

The height, in pixels, of a margin to be placed above and below the child widget. This margin falls outside of any caption or frame that the child might have. For memory efficiency, this resource is stored in an unsigned character field, and therefore has a maximum value of 255. The default margin for most children is one-half of the space size specified by the XmtNdefaultSpacing resource of the Layout widget itself, but the default margin for rows and columns is 0, so that children positioned within nested rows and columns do not become nested within multiple margins.

XmtNlayoutMarginWidth

The width, in pixels, of a margin to be placed to the left and to the right of the child widget. This margin falls outside of any caption or frame that the child might have. For memory efficiency, this resource is stored in an unsigned character field, and therefore has a maximum value of 255. The default margin for most children is one-half of the space size specified by the XmtNdefaultSpacing resource of the Layout widget itself, but the default margin for rows and columns is 0, so that children positioned within nested rows and columns do not become nested within multiple margins.

XmtNlayoutPosition

The numerical position within the containing row or column at which this child should be laid out. Setting this constraint resource, in conjunction with XmtNlayoutIn resource, positions the child in the Layout widget and causes the XmtNlayoutAfter and XmtNlayoutBefore resources to be set to reflect that position. The XmtNlayoutAfter and XmtNlayoutBefore resources override this resource, if either is set. The position 0 specifies that the child is to be the first in the row or column, and the special value -1 (the default) specifies that it is to be the last. The defaults for the positioning constraint resources are chosen so that children will be positioned by default at the end of the topmost (automatically created) row or column.

XmtNlayoutSensitive

Specifies whether the child is sensitive or not. If False, the child's caption, if any, will be drawn ``greyed out'' with a stipple. Generally, if a child has a caption, this constraint resource should be set whenever a widget's XtNsensitive resource is set either directly or with XtSetSensitive(). The XmtChooser and XmtInputField wid gets are often used with a caption, and automatically set this resource whenever their XtNsensitive resource changes.

XmtNlayoutShrinkability

The ``shrinkability factor'' for this child, which controls whether, and in what proportion to other children, this child will shrink when the parent Layout widget is made smaller than its default size. The default value is 10 for all widgets, XmGadgets, rows, columns, and XmtLayoutSpace gadgets. For Layout string, pixmap, and separator gadgets, the default is 0.

XmtNlayoutStretchability

The ``stretchability factor'' for this child, which controls whether, and in what proportion to other children, this child will stretch when the parent Layout widget is made larger than its default size. The default value is 10 for all widgets, XmGadgets, rows, columns, and XmtLayoutSpace gadgets. For Layout string, pixmap, and separator gadgets, the default is 0.

XmtNlayoutWidth

The preferred width, in pixels, of this child. If specified, this is the initial width of the child, and the base width from which the child will stretch or shrink. If unspecified, the child's preferred width will be used. Note that this size does not include any space required for the child's margins, caption, or frame.

Row and Column Resources

The Layout widget arranges its children into nested rows and columns. These rows and columns are themselves children of the Layout widget, implemented as a special gadget type, the XmtLayoutBox. The Layout widget and the XmtLayoutBox gadget work together closely, and much of the important layout functionality of the Layout widget is in fact implemented by the XmtLayoutBox. Because the XmtLayoutBox is so important to the layout process, its resources are summarized here. You can find a more complete listing in the XmtLayoutBox reference page.

Layout Grammar

The XmtNlayout resource is a string which specifies the layout of the Widget and XmGadget children of the XmtLayout widget, and may also specify XmtLayoutGadget children to be automatically created. The string is a list of items that appear in the toplevel row or column (its orientation is determined by the XmtNorientation resource). These items may include nested rows or columns which have a list of their own items within curly braces. Any item may have a list of modifiers which specify size, stretchability, justification, captions, frames, and so on.

Rows, columns, and other layout gadgets are automatically created as the layout specification is parsed. Widgets and XmGadget items can be specified by name in the layout string. When an item name is encountered without any type, it is assumed to be a widget or gadget that will be created later. The XmtLayout widget remembers the position and modifiers specified for this widget, and applies them when a widget by that name is eventually created.

The XmtLayout widget does not link the parser for this layout grammar by default. If you specify a value for the XmtNlayout resource, you should also register the parser by calling XmtRegisterLayoutParser(). If an application never calls this function, that code will never be linked. This means that statically linked applications that do not use the parser do not pay the overhead of the parser code.

The layout grammar was designed to be easily readable and intuitive. Chapter 18, The Layout Widget: A Tutorial, provides an extended tutorial on using the grammar, and Chapter 19, The Layout Widget: The Details, contains an annotated definition of the grammar that explains the semantics as well as the syntax.

For reference, the layout grammar is summarized in BNF form below. Items within single quotes are terminal symbols of the grammar-keywords or punctuation that should appear exactly as shown. Items in italics are non-terminals-items that are defined elsewhere in the grammar, or which are implicitly defined. Items within curly braces are repeated zero or more times and items within square brackets are optional. When a non-terminal has more than one possible definition, they are presented on separate lines, or are separated by vertical bars.

Note that the grammar is case-sensitive and that almost all keywords begin with a capital letter. This means that keywords will not conflict with widget names which, by convention, begin with a lowercase letter.

TRANSLATIONS and ACTIONS

The Layout widget inherits the translations of the Xm BulletinBoard class which serve mainly to allow traversal to work for XmGadget children of the widget. The Layout widget does not define any new translations, nor any new actions.

CALLBACKS

The Layout widget does not define any new callback resources.

Types

A number of the Layout widget and XmtLayoutBox gadget resources and constraint resources use enumerated types. These types are defined as follows in the header file <Xmt/Layout.h>.

typedef enum {



XmtLayoutFilled,


XmtLayoutFlushLeft,


XmtLayoutFlushTop,


XmtLayoutFlushRight,


XmtLayoutFlushBottom,


XmtLayoutCentered



} XmtLayoutJustification;
typedef enum {



XmtLayoutTop,


XmtLayoutBottom,


XmtLayoutLeft,


XmtLayoutRight



} XmtLayoutEdge;
typedef enum {



XmtLayoutFrameNone,


XmtLayoutFrameBox,


XmtLayoutFrameLeft,


XmtLayoutFrameRight,


XmtLayoutFrameTop,


XmtLayoutFrameBottom



} XmtLayoutFrameType;
typedef enum {



XmtLayoutFrameShadowIn,


XmtLayoutFrameShadowOut,


XmtLayoutFrameEtchedIn,


XmtLayoutFrameEtchedOut,


XmtLayoutFrameSingleLine,


XmtLayoutFrameDoubleLine,



} XmtLayoutFrameLineType;
typedef enum {



XmtLayoutFrameInside,


XmtLayoutFrameThrough,


XmtLayoutFrameOutside



} XmtLayoutFramePosition;
typedef enum {



XmtLayoutSpaceNone,


XmtLayoutSpaceEven,


XmtLayoutSpaceLREven,


XmtLayoutSpaceInterval,


XmtLayoutSpaceLCR



} XmtLayoutSpaceType;

SEE ALSO