NAME

Paned widget − geometry-managing widget for vertical or horizontal tiles. 

SYNOPSIS

Public Headers:<X11/StringDefs.h> <X11/Xaw/Paned.h>

Private Header:<X11/Xaw/PanedP.h>

Class Name:Paned

Class Pointer:panedWidgetClass

Instantiation:widget = XtCreateWidget(name, panedWidgetClass, ...) 

CLASS HIERARCHY

Core → Composite → Constraint → Paned

DESCRIPTION

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. 

When the pointer is positioned on a grip and pressed, an arrow is displayed that indicates the pane that is being resized.  While keeping the pointer button down, the user can move the pointer up and down (or left and right).  This, in turn, changes the border between the panes, causing one pane to shrink and some other pane (or panes) to grow.  The size of the Paned widget will not change. 

The choice of alternate pane is a function of the XtNmin, XtNmax, and XtNskipAdjust constraints on the other panes.  With the default bindings, button 1 resizes the pane above or to the left of the selected grip, button 3 resizes the pane below or to the right of the selected grip, and button 2 repositions the border between two panes only. 

RESOURCES

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

CONSTRAINTS

During the creation of a child pane, the following resources, by which the Paned widget controls the placement of the child, can be specified in the argument list or retrieved from the resource database:

LAYOUT SEMANTICS

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.  Three rules determine which child is resized.  Although these rules are always the same, the panes that are searched can change depending upon what caused the relayout. 

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 three rules; if unsuccessful, the Paned widget eliminates rule 3 and then rule 2.  Rule 1 is always enforced. 

If the relayout is due to a resize or a 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. 

RESIZING PANES FROM A GRIP ACTION

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

The pane below (or to the right of) the grip is resized by invoking the GripAction with LowRightPane specified.  The panes above (or to the left of) the grip are each checked in this case.  No pane below (or to the right of) 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. 

RESIZING PANES AFTER THE PANED WIDGET IS RESIZED

When the Paned 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. 

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, it will hunt through the children, from bottom to top (right to left), looking for a pane to resize. 

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

TRANSLATIONS AND ACTIONS

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:

StartSets 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 (UpLeftPane, ThisBorderOnly, LowRightPane). 

MoveThe 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. 

CommitThis 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. 

PUBLIC FUNCTIONS

You add panes after the parent frame is created.  Any type of widget can be 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. 

•To enable or disable a child’s request for pane resizing, use XawPanedAllowResize(): void XawPanedAllowResize(w, allow_resize)
     Widget w;
     Boolean allow_resize; where:

wSpecifies the widget ID of the child widget pane. 

allow_resize
Enables or disables a pane window for resizing requests.

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 Paned widget is realized and False after it is realized.  This procedure is equivalent to changing the XtNallowResize 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; where:

wSpecifies the widget ID of the child widget pane. 

minSpecifies the minimum height of the child, in pixels. 

maxSpecifies the maximum height of the child, in pixels. 

This procedure is equivalent to setting the XtNmin and XtNmax resources for the child. 

•To retrieve the minimum and maximum height settings for a pane, use XawPanedGetMinMax(): void XawPanedGetMinMax(w, min_return, max_return)
     Widget w;
     int ∗min_return, ∗max_return;   /∗ RETURNED ∗/ where:

wSpecifies the widget ID of the Paned widget. 

min_returnReturns the minimum height of the child, expressed in pixels. 

max_returnReturns the maximum height of the child, expressed in pixels. 

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

•To enable or disable automatic recalculation of pane sizes and positions, use XawPanedSetRefigureMode(): void XawPanedSetRefigureMode(w, mode)
     Widget w;
     Boolean mode; where:

wSpecifies the widget ID of the Paned widget. 

modeEnables or disables refiguration. 

You should set the mode to False if you add multiple panes to or remove multiple panes from the parent frame after it has been realized, unless you can arrange to manage all the panes at once using XtManageChildren().  After all the panes are added, set the mode to True.  This avoids unnecessary geometry calculations and "window dancing."

•To retrieve the number of panes in a paned widget, use XawPanedGetNumSub(): int XawPanedGetNumSub(w)
     Widget w; where w specifies the widget ID of the Paned widget. 

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.