Chapter 6

These widgets may contain arbitrary widget children. They implement a policy for the size and location of their children.

Box	This widget will pack its children as tightly as possible in non-overlapping rows.
Dialog	An implementation of a commonly used interaction semantic to prompt for auxiliary input from the user, such as a filename.
Form	A more sophisticated layout widget that allows the children to specify their positions relative to the other children, or to the edges of the Form.
Paned	Allows children to be tiled vertically or horizontally. Controls are also provided to allow the user to dynamically resize the individual panes.
Porthole	Allows viewing of a managed child which is as large as, or larger than its parent, typically under control of a Panner widget.
Tree	Provides geometry management of widgets arranged in a directed, acyclic graph.
Viewport	Consists of a frame, one or two scrollbars, and an inner window. The inner window can contain all the data that is to be displayed. This inner window will be clipped by the frame with the scrollbars controlling which section of the inner window is currently visible.

6.0.1. A Brief Note on Geometry Management

The geometry management semantics provided by the X Toolkit give full control of the size and position of a widget to the parent of that widget. While the children are allowed to request a certain size or location, it is the parent who makes the final decision. Many of the composite widgets here will deny any geometry request from their children by default. If a child widget is not getting the expected size or location, it is most likely the parent disallowing a request, or implementing semantics slightly different than those expected by the application programmer.

If the application wishes to change the size or location of any widget it should make a call to XtSetValues. This will allow the widget to ask its parent for the new size or location. As noted above the parent is allowed to refuse this request, and the child must live with the result. If the application is unable to achieve the desired semantics, then perhaps it should use a different composite widget. Under no circumstances should an application programmer resort to XtMoveWidget or XtResizeWidget; these functions are exclusively for the use of Composite widget implementors.

For more information on geometry management consult the X Toolkit Intrinsics-C Language Interface.

6.1. Box Widget

Application Header file	<X11/Xaw/Box.h>
Class Header file	<X11/Xaw/BoxP.h>
Class	boxWidgetClass
Class Name	Box
Superclass	Composite

The Box widget provides geometry management of arbitrary widgets in a box of a specified dimension. The children are rearranged when resizing events occur either on the Box or its children, or when children are managed or unmanaged. The Box widget always attempts to pack its children as tightly as possible within the geometry allowed by its parent.

Box widgets are commonly used to manage a related set of buttons and are often called Button Box widgets, but the children are not limited to buttons. The Box's children are arranged on a background that has its own specified dimensions and color.

6.1.1. Resources

When creating a Box widget instance, the following resources are retrieved from the argument list or from the resource database:

accelerators	A list of event to action bindings to be executed by this widget, even though the event occurred in another widget. (See the X Toolkit Intrinsics-C Language Interface for details).
ancestorSensitive	The sensitivity state of the ancestors of this widget. A widget is insensitive if either it or any of its ancestors is insensitive. This resource should not be changed with XtSetValues, although it may be queried.
background	A pixel value which indexes the widget's colormap to derive the background color of the widget's window.
backgroundPixmap	The background pixmap of this widget's window. If this resource is set to anything other than XtUnspecifiedPixmap, the pixmap specified will be used instead of the background color.
borderColor	A pixel value which indexes the widget's colormap to derive the border color of the widget's window.
borderPixmap	The border pixmap of this widget's window. If this resource is set to anything other than XtUnspecifiedPixmap, the pixmap specified will be used instead of the border color.
borderWidth	The width of this widget's window border.
children	A list of all this composite widget's current children.
colormap	The colormap that this widget will use.
depth	The depth of this widget's window.
destroyCallback	All functions on this list are called when this widget is destroyed.
height width	The height and width of this widget in pixels.
hspace vspace	The amount of space, in pixels, to leave between the children. This resource specifies the amount of space left between the outermost children and the edge of the box.
mappedWhenManaged	If this resource is True, then the widget's window will automatically be mapped by the Toolkit when it is realized and managed.
numChildren orientation	The number of children in this composite widget. Specifies whether the preferred shape of the box (i.e. the result returned by the query_geometry class method) is tall and narrow XtorientVerti cal or short and wide XtorientHorizontal. When the Box is a child of a parent which enforces width constraints, it is usually better to specify XtorientVertical (the default). When the parent enforces height constraints, it is usually better to specify XtorientHorizontal. A converter is registered for this resource that will convert the following strings: horizontal and vertical.
screen	The screen on which this widget is displayed. This is not a settable resource.
sensitive	Whether or not the toolkit should pass user events to this widget. The widget will not get input events if either ancestorSensitive or sensitive is False.
translations	The event bindings associated with this widget.
x y	The location of the upper left outside corner of this widget in its parent.

6.1.2. Layout Semantics

Each time a child is managed or unmanaged, the Box widget will attempt to reposition the remaining children to compact the box. Children are positioned in order left to right, top to bottom. The packing algorithm used depends on the orientation of the Box.

XtorientVertical	When the next child does not fit on the current row, a new row is started. If a child is wider than the width of the box, the box will request a larger width from its parent and will begin the layout process from the beginning if a new width is granted.
XtorientHorizontal	When the next child does not fit on the current row, the Box widens if possible (so as to keep children on a single row); otherwise a new row is started.

After positioning all children, the Box widget attempts to shrink its own size to the minimum dimensions required for the layout.

6.2.Dialog Widget

Application Header file	<X11/Xawt/Dialog.h>
Class Header file	<X11/Xaw/Dialog P.h>
Class	dialogWidgetClass
Class Name	Dialog
Superclass	Form

The Dialog widget implements a commonly used interaction semantic to prompt for auxiliary input from a user. For example, you can use a Dialog widget when an application requires a small piece of information, such as a filename, from the user. A Dialog widget, which is simply a special case of the Form widget, provides a convenient way to create a preconfigured form.

The typical Dialog widget contains three areas. The first line contains a description of the function of the Dialog widget, for example, the string Filename:. The second line contains an area into which the user types input. The third line can contain buttons that let the user confirm or cancel the Dialog input. Any of these areas may be omitted by the application.

6.2.1. Resources

When creating a Dialog widget instance, the following resources are retrieved from the argument list or the resource database:

Name	Class	Type	Notes	Default Value
accelerators	Accelerators	AcceratorTable		NULL
ancestorSensitive	AncestorSensitive	Boolean	D	True
background	Background	Pixel		XtDefaultBackground
backgroundPixmap	Pixmap	Pixmap		XtUnspecifiedPixmap
borderColor	BorderColor	Pixel		XtDefaultForeground
borderPixmap	Pixmap	Pixmap		XtUnspecifiedPixmap
borderWidth	BorderWidth	Dimension		1
children	ReadOnly	WidgetList	R	NULL
colormap	Colormap	Colormap		Parent's Colormap
defaultDistance	Thickncss	int		4
depth	Depth	int	C	Parent's Depth
destroyCallback	Callback	XtCallbackList		NULL
height	Height	Dimension	A	Enough space to contain all children
icon	Icon	Bitmap		None
label	Label	String		"label"
mappedWhenManaged	MappedWhenManaged	Boolean		True
numChildren	ReadOnly	Cardinal	R	0
screen	Screen	Screen	R	Parent's Screen
sensitive	Sensitive	Boolean		True
translations	Translations	TranslationTable		NULL
value	Value	String		no value widget
width	Width	Dimension	A	Enough space to contain all children
x	Position	Position		0
y	Positon	Position		0

accelerators	A list of event to action bindings to be executed by this widget, even though the event occurred in another widget. (See the X Toolkit Intrinsics-C Language Intrinsics for details).
ancestorSensitive	The sensitivity state of the ancestors of this widget. A widget is insensitive if either it or any of its ancestors is insensitive. This resource should not be changed with XtSetValues, although it may be queried.
Background	A pixel value which indexes the widget's colormap to derive the back ground color of the widget's window.
backgroundPixmap	The background pixmap of this widget's window. If this resource is set to anything other than XtUnspecifiedPixmap, the pixmap specified will be used instead of the background color.
borderColor	A pixel value which indexes the widget's colormap to derive the border color of the widget's window.
borderPixmap	The border pixmap of this widget's window. If this resource is set to anything other than XtUnspecifiedPixmap, the pixmap specified will be used instead of the border color.
borderWidth	The width of this widget's window border.
children	A list of all this composite widget's current children.
colormap	The colormap that this widget will use.
defaultDistance	The default internal spacing for the children. This is the default value for the constraint resources horizDistance and vertDistance.
depth	The depth of this widget's window.
destroyCallback	All functions on this list are called when this widget is destroyed.
height width	The height and width of this widget in pixels.
icon	A pixmap image to be displayed immediately to the left of the Dialog widget's label.
label	A string to be displayed at the top of the Dialog widget.
mappedWhenManaged	If this resource is True, then the widget's window will automatically be mapped by the Toolkit when it is realized and managed.
numChildren	The number of children in this composite widget.
screen	The screen on which this widget is displayed. This is not a settable resource.
sensitive	Whether or not the toolkit should pass user events to this widget. The widget will not get input events if either ancestorSensitive or sensitive is False.
translations	The event bindings associated with this widget.
value	An initial value for the string field that the user will enter text into. By default, no text entry field is available to the user. Specifying an initial value for value activates the text entry field. If string input is desired, but no initial value is to be specified then set this resource to "" (empty string).
x y	The location of the upper left outside corner of this widget in its parent.

6.2.2. Constraint Resources

Each child of the Dialog widget may request special layout resources be applied to it. These constraint resources allow the Dialog widget's children to specify individual layout requirements.

bottom left right
top	What to do with this edge of the child when the parent is resized. This resource may be any edgeType. See Layout Semantics for details.
fromHoriz
fromVert	Which widget this child should be placed underneath (or to the right of). If a value of NULL is specified then this widget will be positioned relative to the edge of the parent.
horizDistance
vertDistance	The amount of space, in pixels, between this child and its left or upper neighbor.
resizable	If this resource is False then the parent widget will ignore all geometry request made by this child. The parent may still resize this child itself, however.

6.2.3. Layout Semantics

The Dialog widget uses two different sets of layout semantics. One is used when initially laying out the children. The other is used when the Dialog is resized.

The first layout method uses the fromVert and fromHoriz resources to place the children of the Dialog. A single pass is made through the Dialog widget's children in the order that they were created. Each child is then placed in the Dialog widget below or to the right of the widget specified by the fromVert and fromHoriz resources. The distance the new child is placed from its left or upper neighbor is determined by the horizDistance and vertDistance resources. This implies some things about how the order of creation affects the possible placement of the children. The Form widget registers a string to widget converter which does not postpone conversion and does not cache conversion results.

The second layout method is used when the Dialog is resized. It does not matter what causes this resize, and it is possible for a resize to happen before the widget becomes visible (due to constraints imposed by the parent of the Dialog). This layout method uses the bottom, top, left, and right resources. These resources are used to determine what will happen to each edge of the child when the Dialog is resized. If a value of XawChain<something> is specified, the edge of the child will remain a fixed distance from the chain edge of the Dialog. For example if XawChainLeft is specified for the right resource of a child then the right edge of that child will remain a fixed distance from the left edge of the Dialog widget. If a value of XawRubber is specified, that edge will grow by the same percentage that the Dialog grew. For instance if the Dialog grows by 50% the left edge of the child (if specified as XawRubber will be 50% farther from the left edge of the Dialog). One must be very careful when specifying these resources, for when they are specified incorrectly children may overlap or completely occlude other children when the Dialog widget is resized.

6.2.3.1. Example

If you wish to force the Dialog to never resize one or more of its children then set left and right to XawChainLeft and top and bottom to XawChainTop. This will cause the child to remain a fixed distance from the top and left edges of the Dialog, and to never resize.

6.2.3.2. Special Considerations

The Dialog widget automatically sets the top and bottom resources for all Children that are subclasses of the Command widget, as well as the widget children that are used to contain the label, value, and icon. This policy allows the buttons at the bottom of the Dialog to interact correctly with the predefined children, and makes it possible for a client to simply create and manage a new Command button without having to specify its constraints.

The Dialog will also set from Left to the last button in the Dialog for each new button added to the Dialog widget.

The automatically added constraints cannot be overridden, as they are policy decisions of the Dialog widget. If a more flexible Dialog is desired, the application is free to use the Form widget to create its own Dialog policy.

6.2.4. Automatically Created Children.

The Dialog uses Label widgets to contain the label and icon. These widgets are named label and icon respectively. The Dialog value is contained in an AsciiText widget whose name is value. Using XtNameToWidget the application can change those resources associated with each of these widgets that are not available through the Dialog widget itself.

6.2.5. Convenience Routines

To return the character string in the text field, use XawDialogGetValueString.

String XawDialogGetValueString(w)

Widget w;

w	Specifies the Dialog widget.

This function returns a copy of the value string of the Dialog widget This string is allocated by the AsciiText widget and will remain valid and unchanged until another call to XawDialogGetValueString or an XtGetValues call on the value widget, when the string will be automatically freed, and a new string is returned. This string may be freed earlier by calling the function XawAsciiSourceFreeString.

To add a new button to the Dialog widget use XawDialogAddButton.

void XawDialogAddButton(w, name,func, client data)

Widget w;
String name;
XtCallbackProc func;
XtPointer client_data;

w	Specifies the Dialog widget.
name	Specifies the name of the new Command button to be added to the Dialog
func	Specifies a callback function to be called when this button is activated. If NULL is specified then no callback is added.
client_data	Specifies the client_data to be passed to the func.

This function is merely a shorthand for the code sequence:

{
                        Widget button = XtCreateManagedWidget(name, commandWidgetClass, w, NULL, ZERO);
                        XtAddCallback(button, XtNcallback, func, client_data);
}

Application Header file	<X11/Xaw/Form.h>
Class Header file	<X11/Xaw/FormP.h>
Class	formWidgetClass
Class Name	Form
Superclass	Constraint

The Form widget can contain an arbitrary number of children or subwidgets. The Form provides geometry management for its children, which allows individual control of the position of each child. Any combination of children can be added to a Form. The initial positions of the children may be computed relative to the positions of previously created children. When the Form is resized, it computes new positions and sizes for its children. This computation is based upon information provided when a child is added to the Form.

The default width of the Form is the minimum width needed to enclose the children after computing their initial layout, with a margin of defaultDistance at the right and bottom edges. If a width and height is assigned to the Form that is too small for the layout, the children will be clipped by the right and bottom edges of the Form.

6.3.1. Resources

When creating an Form widget instance, the following resources are retrieved from the argument list or from the resource database:

Name	Class	Type	Notes	Default Value
accelerators	Accelerators	AcceleratorTable		NULL
ancestorSensitive	AncestorSensitive	Boolean	D	True
background	Background	Pixel		XtDefaultBackground
backgroundPixmap	Pixmap	Pixmap		XtUnspecifiedPixmap
borderColor	Border Color	Pixel		XtDefaultForeground
borderPixmap	Pixmap	Pixmap		XtUnspecifiedPixmap
borderWidth	BorderWidth	Dimension		1
children	ReadOnly	WidgetList	R	NULL
colormap	Colormap	Colormap		Parent'sColormap
defaultDistance	Thickness	int		4
depth	Depth	int	C	Parent's Depth
destroyCallback	Callback	XtCallbackList		NULL
height	Height	Dimension	A	Enough space to contain all children
mappedwhenManaged	MappedwhenManaged	Boolean		True
nurnChildrcn	ReadOnly	Cardinal	R	0
screen	screen	Screen	R	Parent's screen
sensitive	sensitive	Boolean		True
translations	Translations	TranslationTable		NULL
width	Width	Dimension	A	Enough space to contain all children
x	Position	Position		0
y	Position	Position		0

accelerators	A list of event to action bindings to be executed by this widget, even though the event occurred in another widget. (See the X Toolkit Intrinsics-C Language Interface for details).
ancestorSensitive	The sensitivity state of the ancestors of this widget. A widget is insensitive if either it or any of its ancestors is insensitive. This resource should not be changed with XtSetValues, although it may be queried.
background	A pixel value which indexes the widget's colormap to derive the back ground color of the widget's window.
backgroundPixmap	The background pixmap of this widget's window. If this resource is set to anything other than XtUnspecifiedPixmap, the pixmap specified will be used instead of the background color.
borderColor	A pixel value which indexes the widget's colormap to derive the border color of the widget's window.
borderPixmap	The border pixmap of this widget's window. If this resource is set to anything other than XtUnspecifiedPixmap, the pixmap specified will be used instead of the border color.
borderWidth	The width of this widget's window border.
children	A list of all this composite widget's current children.
colormap	The colormap that this widget will use.
defaultDistance	The default internal spacing for the children. This is the default value for the constraint resources horizDistance and vertDistance.
depth	The depth of this widget's window.
destroyCallback	All functions on this list are called when this widget is destroyed.
height
width	The height and width of this widget in pixels.
mappedWhenManaged	If this resource is True, then the widget's window will automatically be mapped by the Toolkit when it is realized and managed.
numChildren	The number of children in this composite widget.
screen	The screen on which this widget is displayed. This is not a settable resource.
sensitive	Whether or not the toolkit should pass user events to this widget. The widget will not get input events if either ancestorSensitive or sensitive is False.
translations	The event bindings associated with this widget.
x
y	The location of the upper left outside corner of this widget in its parent.

6.3.2. Constraint Resources

Each child of the Form widget may request special layout resources be applied to it. These constraint resources allow the Form widget's children to specify individual layout requirements.

bottom
left
right
top	What to do with this edge of the child when the parent is resized. This resource may be any edgeType. See Layout Semantics for details.
fromHoriz
fromVert	Which widget this child should be placed underneath (or to the right of). If a value of NULL is specified then this widget will be positioned relative to the edge of the parent.
horizDistance
vertDistance	The amount of space, in pixels, between this child and its left or upper neighbor.
resizable	If this resource is False then the parent widget will ignore all geometry request made by this child. The parent may still resize this child itself, however.

6.3.3. Layout Semantics

The Form widget uses two different sets of layout semantics. One is used when initially laying out the children. The other is used when the Form is resized.

The first layout method uses the fromVert and fromHoriz resources to place the children of the Form. A single pass is made through the Form widget's children in the order that they were created. Each child is then placed in the Form widget below or to the right of the widget specified by the fromVert and fromHoriz resources. The distance the new child is placed from its left or upper neighbor is determined by the horizDistance and vertDistance resources. This implies some things about how the order of creation affects the possible placement of the children. The Form widget registers a string to widget converter which does not postpone conversion and does not cache conversion results.

The second layout method is used when the Form is resized. It does not matter what causes this resize, and it is possible for a resize to happen before the widget becomes visible (due to constraints imposed by the parent of the Form). This layout method uses the bottom, top, left, and right resources. These resources are used to determine what will happen to each edge of the child when the Form is resized. If a value of XawChain<something> is specified, the edge of the child will remain a fixed distance from the chain edge of the Form. For example if XawChainLeft is specified for the right resource of a child then the right edge of that child will remain a fixed distance from the left edge of the Form widget. If a value of XawRubber is specified, that edge will grow by the same percentage that the Form grew. For instance if the Form grows by 50% the left edge of the child (if specified as XawRubber will be 50% farther from the left edge of the Form). One must be very careful when specifying these resources, for when they are specified incorrectly children may overlap or completely occlude other children when the Form widget is resized.

6.3.3.1. Example

If you wish to force the Form to never resize one or more of its children, then set left and right to XawChainLeft and top and bottom to XawChainTop. This will cause the child to remain a fixed distance from the top and left edges of the Form, and never to resize.

6.3.4. Convenience Routines

void XawFormDoLayout(w, do_layout)

Widget w;
Boolean do_layout;

w	Specifies the Form widget.
do_layout	Specifies whether the layout of the Form widget is enabled (True) or disabled (False).

When making several changes to the children of a Form widget after the Form has been realized, it is a good idea to disable relayout until after all changes have been made.

6.4. Paned Widget

Application Header file	<X11/Xaw/Paned.h>
Class Header file	<X11/Xaw/PanedP.h>
Class	panedWidgetClass
Class Name	Paned
Superclass	Constraint

The Paned widget manages children in a vertically or horizontally tiled fashion. The panes may be dynamically resized by the user by using the grips that appear near the right or bottom edge of the border between two panes.

The Paned widget may accept any widget class as a pane except Grip. Grip widgets have a special meaning for the Paned widget, and adding a Grip as its own pane will confuse the Paned widget.

6.4.1. Using the Paned Widget

The grips allow the panes to be resized by the user. The semantics of how these panes resize is somewhat complicated, and warrants further explanation here. When the mouse pointer is positioned on a grip and pressed, an arrow is displayed that indicates the pane that is to be to be resized. While keeping the mouse button down, the user can move the grip up and down (or left and right). This, in turn, changes the size of the pane. The size of the Paned widget will not change. Instead, it chooses another pane (or panes) to resize. For more details on which pane it chooses to resize, see Layout Semantics.

One pointer binding allows the border between two panes to be moved, without affecting any of the other panes. When this occurs the pointer will change to an arrow that points along the pane border.

The default bindings for the Paned widget's grips are:

6.4.2. Resources

When creating a Paned widget instance, the following resources are retrieved from the argument list or the resource database:

accelerators	A list of event to action bindings to be executed by this widget, even though the event occurred in another widget. (See the X Toolkit Intrinsics-C Language Interface for details).
ancestorSensitive	The sensitivity state of the ancestors of this widget. A widget is insensitive if either it or any of its ancestors is insensitive. This resource should not be changed with XtSetValues, although it may be queried.
background	A pixel value which indexes the widget's colormap to derive the background color of the widget's window.
backgroundPixmap	The background pixmap of this widget's window. If this resource is set to anything other than XtUnspecifiedPixmap, the pixmap specified will be used instead of the background color.
borderColor	A pixel value which indexes the widget's colormap to derive the border color of the widget's window.
borderPixmap	The border pixmap of this widget's window. If this resource is set to anything other than XtUnspecifiedPixmap, the pixmap specified will be used instead of the border color.
borderWidth	The width of this widget's window border.
children	A list of all this composite widget's current children.
colormap	The colormap that this widget will use.
cursor	The cursor to use when the mouse pointer is over the Paned widget, but not in any of its children (children may also inherit this cursor). It should be noted that the internal borders are actually part of the Paned widget, not the children.
depth	The depth of this widget's window.
destroyCallback	All functions on this list are called when this widget is destroyed.
gripCursor	The cursor to use when the grips are not active. The default value is verticalGripCursor or horizontalGripCursor depending on the orientation of the Paned widget.
gripIndent	The amount of space left between the right (or bottom) edge of the Paned widget and all the grips.
gripTranslation	Translation table that will be applied to all grips.
height
width	The height and width of this widget in pixels.
horizontalBetweenCursor
verticalBetweenCursor	The cursor to be used for the grip when changing the boundary between two panes. These resources allow the cursors to be different depending on the orientation of the Paned widget.
horizontalGripCursor
verticalGripCursor	The cursor to be used for the grips when they are not active. These resources allow the cursors to be different depending on the orientation of the Paned widget.
internalBorderColor	A pixel value which indexes the widget's colormap to derive the internal border color of the widget's window. The class name of this resource allows Paned*BorderColor: blue to set the internal border color for the Paned widget. An optimization is invoked if internalBorderColor and background are the same, and the internal borders are not drawn. internalBorderWidth is still left between the panes, however.
internalBorderWidth	The width of the internal borders. This is the amount of space left between the panes. The class name of this resource allows Paned*BorderWidth: 3 to set the internal border width for the Paned widget.
leftCursor
rightCursor	The cursor used to indicate which is the important pane to resize when the Paned widget is oriented horizontally.
lowerCursor
upperCursor	The cursor used to indicate which is the important pane to resize when the Paned widget is oriented vertically.
mappedWhenManaged	If this resource is True, then the widget's window will automatically be mapped by the Toolkit when it is realized and managed.
numChildren	The number of children in this composite widget. This is not the same as the number of panes, since this also contains a grip for some of the panes, use XawPanedGetNumSub to retrieve the number of panes.
orientation	The orientation to stack the panes. This value can be either XtorientVertical or XtorientHorizontal. A converter is registered for this resource that will convert the following strings: vertical and horizontal.
refigureMode	This resource allows pane layout to be suspended. If this value is False, then no layout actions will be taken. This may improve efficiency when adding or removing more than one pane from the Paned widget.
screen	The screen on which this widget is displayed. This is not a settable resource.
sensitive	Whether or not the toolkit should pass user events to this widget. The widget will not get input events if either ancestorSensitive or sensitive is False.
translations	The event bindings associated with this widget.
x
y	The location of the upper left outside corner of this widget in its parent.

6.4.3. Constraint Resources

Each child of the Paned widget may request special layout resources be applied to it. These constraint resources allow the Paned widget's children to specify individual layout requirements.

allowResize	If this value is False the the Paned widget will disallow all geometry requests from this child.
max
min	The absolute maximum or minimum size for this pane. These values will never be overridden by the Paned widget. This may cause some panes to be pushed off the bottom (or right) edge of the paned widget.
PreferredPaneSize	Normally the paned widget makes a QueryGeometry call on a child to determine the preferred size of the child's pane. There are times when the application programmer or the user has a better idea of the preferred size of a pane. Setting this resource causes the value passed to be interpreted as the preferred size, in pixels, of this pane.
ResizeToPreferred	Determines whether or not to resize each pane to its preferred size when the Paned widget is resized. See Layout Semantics for details.
ShowGrip	If True then a grip will be shown for this pane. The grip associated with a pane is either below or to the right of the pane. No grip is ever shown for the last pane.
SkipAdjust	This resource is used to determine which pane is forced to be resized. Setting this value to True makes this pane less likely to be forced to be resized. See Layout Semantics for details.

6.4.4. Layout Semantics

In order to make effective use of the Paned widget it is helpful to know the rules it uses to determine which child will be resized in any given situation. There are three rules used to determine which child is resized. While these rules are always the same, the panes that are searched can change depending upon what caused the relayout.

Layout Rules

1	Do not let a pane grow larger than its, max or smaller than its min.
2	Do not adjust panes with skipAdjust set.
3	Do not adjust panes away from their preferred size, although moving one closer to its preferred size is fine.

When searching the children the Paned widget looks for panes that satisfy all the rules, and if unsuccessful then it eliminates rule 3 and then 2. Rule 1 is always enforced.

If the relayout is due to a resize or change in management then the panes are searched from bottom to top. If the relayout is due to grip movement then they are searched from the grip selected in the direction opposite the pane selected.

6.4.4.1. Resizing Panes from a Grip Action

The pane above the grip is resized by invoking the GripAction with UpLeftPane specified. The panes below the grip are each checked against all rules, then rules 2 and 1 and finally against rule 1 only. No pane above the chosen pane will ever be resized.

The pane below the grip is resized by invoking the GripAction with LowRightPane specified. The panes above the grip are each checked in this case. No pane below the chosen pane will ever be resized.

Invoking GripAction with ThisBorderOnly specified just moves the border between the panes. No other panes are ever resized.

6.4.4.2. Resizing Panes after the Paned widget is resized.

When the Pane widget is resized it must determine a new size for each pane. There are two methods of doing this. The Paned widget can either give each pane its preferred size and then resize the panes to fit, or it can use the current sizes and then resize the panes to fit. The resizeToPreferred resource allows the application to tell the Paned widget whether to query the child about its preferred size (subject to the preferredPaneSize) or to use the current size when refiguring the pane locations after the pane has been resized.

There is one special case. All panes assume they should resize to their preferred size until the Paned widget becomes visible to the user.

6.4.4.3. Managing Children and Geometry Management

The Paned widget always resizes its children to their preferred sizes when a new child is managed, or a geometry management request is honored. The Paned widget will first attempt to resize itself to contain its panes exactly. If this is not possible then it will hunt through the children, from bottom to top (right to left), for a pane to resize.

6.4.4.4. Special Considerations

When a user resizes a pane with the grips, the Paned widget assumes that this new size is the preferred size of the pane.

6.4.5. Grip Translations

The Paned widget has no action routines of its own, as all actions are handled through the grips. The grips are each assigned a default Translation table.

<Btn1Down>:	GripAction(Start, UpLeftPane)
<Btn2Down>:	GripAction(Start, ThisBorderOnly)
<Btn3Down>:	GripAction(Start, LowRightPane)
<Btn1Motion>:	GripAction(Move, UpLeftPane)
<Btn2Motion>:	GripAction(Move, ThisBorderOnly)
<Btn3Motion>:	GripAction(Move, LowRightPane)
Any<BtnUp>:	GripAction(Commit)

The Paned widget interprets the GripAction as taking two arguments. The first argument may be any of the following:

Start	Sets up the Paned widget for resizing and changes the cursor of the grip. The second argument determines which pane will be resized, and can take on any of the three values shown above.
Move	The internal borders are drawn over the current pane locations to animate where the borders would actually be placed if you were to move this border as shown. The second argument must match the second argument that was passed to the Start action, that began this process. If these arguments are not passed, the behavior is undefined.
Commit	This argument causes the Paned widget to commit the changes selected by the previously started action. The cursor is changed back to the grip's inactive cursor. No second argument is needed in this case.

6.4.6. Convenience Routines

void XawPanedAllowResize(w, allow resize)

Widget w;
Boolean allow resize;

If allow_resize is True, the Paned widget allows geometry requests from the child to change the pane's height. If allow_resize is False, the Paned widget ignores geometry requests from the child to change the pane's height. The default state is True before the Pane is realized and False after it is realized. This procedure is equivalent to changing the allowResize constraint resource for the child.

To change the minimum and maximum height settings for a pane, use XawPanedSetMinMax:

void XawPanedSetMinMax(w, min, max)

Widget w;

int min, max;

This procedure is equivalent to setting the min and max constraint resources for the child.

To retrieve the minimum and maximum height settings for a pane, use XawPanedGetMinMax:

void XawPanedGetMinMax(w, min_return, mat_return)

Widget w;

int *min_return, *max_return;

This procedure is equivalent to getting the ,min and ,max resources for this child child.

To enable or disable automatic recalculation of pane sizes and positions, use XawPanedSetRefigureMode:

void XawPanedSetRefigureMode(w, mode)

Widget w;

Boolean mode;

When making several changes to the children of a Paned widget after the Paned has been realized, it is a good idea to disable relayout until after all changes have been made.

To retrieve the number of panes in a paned widget use XawPanedGetNumSub:

int XawPanedGetNumSub(w)

Widget w;

This function returns the number of panes in the Paned widget. This is not the same as the number of children, since the grips are also children of the Paned widget.

6.5. Porthole Widget

The Porthole widget provides geometry management of a list of arbitrary widgets, only one of which may be managed at any particular time. The managed child widget is reparented within the porthole and is moved around by the application (typically under the control of a Panner widget).

6.5.1. Resources

When creating a Porthole widget instance, the following resources are retrieved from the argument list or from the resource database:

accelerators	A list of event to action bindings to be executed by this widget, even though the event occurred in another widget. (See the X Toolkit Intrinsics-C Language Interface for details).
ancestorSensitive	The sensitivity state of the ancestors of this widget. A widget is insensitive if either it or any of its ancestors is insensitive. This resource should not be changed with XtSetValues, although it may be queried.
background	A pixel value which indexes the widget's colormap to derive the background color of the widget's window.
backgroundPixmap	The background pixmap of this widget's window. If this resource is set to anything other than XtUnspecifiedPixmap, the pixmap specified will be used instead of the background color.
borderColor	A pixel value which indexes the widget's colormap to derive the border color of the widget's window.
borderPixmap	The border pixmap of this widget's window. If this resource is set to anything other than XtUnspecifiedPixmap, the pixmap specified will be used instead of the border color.
borderWidth	The width of this widget's window border.
children	A list of all this composite widget's current children.
colormap	The colormap that this widget will use.
depth	The depth of this widget's window.
destroyCallback	All functions on this list are called when this widget is destroyed.
height
width	The height and width of this widget in pixels.
mappedWhenManaged	If this resource is True, then the widget's window will automatically be mapped by the Toolkit when it is realized and managed.
numChildren	The number of children in this composite widget.
reportCallback	A list of functions to invoke whenever the managed child widget changes size or position.
screen	The screen on which this widget is displayed. This is not a settable resource.
sensitive	Whether or not the toolkit should pass user events to this widget. The widget will not get input events if either ancestorSensitive or sensitive is False.
translations	The event bindings associated with this widget.
x
y	The location of the upper left outside corner of this widget in its parent.

6.5.2. Layout Semantics

The Porthole widget allows its managed child to request any size that is as large or larger than the Porthole itself and any location so long as the child still obscures all of the Porthole. This widget typically is used with a Panner widget.

6.5.3. Porthole Callbacks

The functions registered on the reportCallback list are invoked whenever the managed child changes size or position:

void ReportProc(porthole, client data, report)

Widget porthole;
XtPointer client data;
XtPointer report; /* (XawPannerReport *) */

6.6. Tree Widget

The Tree widget provides geometry management of arbitrary widgets arranged in a directed, acyclic graph (i.e., a tree). The hierarchy is constructed by attaching a constraint resource called treeParent to each widget indicating which other node in the tree should be treated as the widget's superior. The structure of the tree is shown by laying out the nodes in the standard format for tree diagrams with lines drawn connecting each node with its children.

The Tree sizes itself according to the needs of its children and is not intended to be resized by its parent. Instead, it should be placed inside another composite widget (such as the Porthole or Viewport) that can be used to scroll around in the tree.

6.6.1. Resources

When creating a Tree widget instance, the following resources are retrieved from the argument list or from the resource database:

6.6.2. Constraint Resources

Each child of the Tree widget must specify its superior node in the tree. In addition, it may specify a GC to use when drawing a line between it and its inferior nodes.

treeGC	This specifies the GC to use when drawing lines between this widget and its inferiors in the tree. If this resource is not specified, the Tree's fore ground and lineWidth will be used.
treeParent	This specifies the superior node in the tree for this widget. The default is for the node to have no superior (and to therefore be at the top of the tree).

6.6.3. Layout Semantics

Each time a child is managed or unmanaged, the Tree widget will attempt to reposition the remaining children to fix the shape of the tree if the autoReconfigure resource is set. Children at the top (most superior) of the tree are drawn at the side specified by the gravity resource.

After positioning all children, the Tree widget attempts to shrink its own size to the minimum dimensions required for the layout.

6.6.4. Convenience Routines

The most efficient way to layout a tree is to set autoReconfigure to False and then use the XawTreeForceLayout routine to arrange the children.

void XawTreeForceLayout(w)

Widget w;

6.7. Viewport Widget

The Viewport widget consists of a frame window, one or two Scrollbars, and an inner window. The size of the frame window is determined by the viewing size of the data that is to be displayed and the dimensions to which the Viewport is created. The inner window is the full size of the data that is to be displayed and is clipped by the frame window. The Viewport widget controls the scrolling of the data directly. No application callbacks are required for scrolling.

When the geometry of the frame window is equal in size to the inner window, or when the data does not require scrolling, the Viewport widget automatically removes any scrollbars. The forceBars option causes the Viewport widget to display all scrollbars permanently.

6.7.1. Resources

When creating a Viewport widget instance, the following resources are retrieved from the argument list or the resource database:

Name	Class	Type	Notes	Default Value
accelerators	Acsclerators	AcocicratorTable		NULL
allowHoriz	Boolean	Boolean		False
allowVert	Boolean	Boolean		False
ancestorSensitive	AncesorScnsitive	Boolean	D	True
background	Background	Pixel		XtDcfaulLBackground
backgroundPixmap	Pixmap	Pixmap		XtUnspecifiedPixmap
borderColor	BorderColor	Pixel		XtDcfaultForeground
borderPixmap	Pixmap	Pixmap		XtUnspecifiedPixmap
borderWidth	BorderWidth	Dimension		1
children	ReadOnly	WidgetList	R	NULL
colormap	Colormap	Colormap		Parent's Colormap
depth	Depth	int	C	Parent's Depth
destroyCallback	Callback	XtCallbackList		NULL
forceBars	Boolean	Boolean		Falsc
height	Height	Dimension		height of the child
mappedWhenManaged	MappedWhenManaged	Boolean		True
numChildren	ReadOnly	Cardinal	R	0
reportCallback	ReportCallback	XtCallbackList		NULL
screen	Screen	Screen	R	Parent's Screen
sensitive	Sensitive	Boolean		True
translations	Translations	TranslationTable		NULL
useBottom	Boolean	Boolean		False
useRight	Boolean	Boolean		False
width	Width	Dimension		width the child
x	Position	Position		0
y	Position	Position		0

accelerators	A list of event to action bindings to be executed by this widget, even though the event occurred in another widget. (See the X Toolkit Intrinsics-C Language Interface for details).
allowHoriz
allowVert	If these resources are False then the Viewport will never create a scrollbar in this direction. If it is True then the scrollbar will only appear when it is needed, unless forceBars is True.
ancestorSensitive	The sensitivity state of the ancestors of this widget. A widget is insensitive if either it or any of its ancestors is insensitive. This resource should not be changed with XtSetValues, although it may be queried.
background	A pixel value which indexes the widget's colormap to derive the background color of the widget's window.
backgroundPixmap	The background pixmap of this widget's window. If this resource is set to anything other than XtUnspecifiedPixmap, the pixmap specified will be used instead of the background color.
borderColor	A pixel value which indexes the widget's colormap to derive the border color of the widget's window.
borderPixmap	The border pixmap of this widget's window. If this resource is set to anything other than XtUnspecifiedPixmap, the pixmap specified will be used instead of the border color.
borderWidth	The width of this widget's window border.
children	A list of all this composite widget's current children.
colormap	The colormap that this widget will use.
depth	The depth of this widget's window.
destroyCallback	All functions on this list are called when this widget is destroyed.
forceBars	When True the scrollbars that have been allowed will always be visible on the screen. If False the scrollbars will be visible only when the inner window is larger than the frame.
height
width	The height and width of this widget in pixels.
mappedWhenManaged	If this resource is True, then the widget's window will automatically be mapped by the Toolkit when it is realized and managed.
numChildren	The number of children in this composite widget.
reportCallback	These callbacks will be executed whenever the Viewport adjusts the viewed area of the child. The call_data parameter is a pointer to an XawPannerReport structure.
screen	The screen on which this widget is displayed. This is not a settable resource.
sensitive	Whether or not the toolkit should pass user events to this widget. The widget will not get input events if either ancestorSensitive or sensitive is False.
translations	The event bindings associated with this widget.
useBottom
useRight	By default the scrollbars appear on the left and top of the screen. These resources allow the vertical scrollbar to be placed on the right edge of the Viewport, and the horizontal scrollbar on the bottom edge of the Viewport.
x
y	The location of the upper left outside corner of this widget in its parent.

6.7.2. Layout Semantics

The Viewport widget manages a single child widget. When the size of the child is larger than the size of the Viewport, the user can interactively move the child within the Viewport by repositioning the scrollbars.

The default size of the Viewport before it is realized is the width and/or height of the child. After it is realized, the viewpoint will allow its child to grow vertically or horizontally if allowVert or allowHoriz are set, respectively. If the corresponding vertical or horizontal scrollbar is not enabled, the Viewport will propagate the geometry request to its own parent and the child will be allowed to change size only if the Viewport's parent allows it. Regardless of whether or not scrollbars are enabled in the corresponding direction, if the child requests a new size smaller than the Viewport size, the change will be allowed only if the parent of the Viewport allows the Viewport to shrink to the appropriate dimension.

The scrollbar children of the Viewport are named horizontal and vertical. By using these names the programmer can specify resources for the individual scrollbars. XtSetValues can be used to modify the resources dynamically once the widget ID has been obtained with XtNameToWidget.