http://invisible-island.net/athena_widgets/XawPlus
| Application Header file Class Header file Class Class Name Superclass |
<X11/XawPlus/Paned.h> <X11/XawPlus/PanedP.h> panedWidgetClass Paned 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.
The Paned widget uses the new color resources intBorderHighlight and intBorderShadow to draw a 3D styled separator line between the managed children. The resource internalBorderColor is not longer supported.
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:
| Pane to Resize | Pane to Resize | |
| Mouse button 1 (left) 2 (middle) 3 (right) |
Vertical above the grip adjust border below the grip |
Horizontal left of the grip adjust border right of the grip |
When creating a Form widget instance, the following resources are retrieved from the argument list of XtSetValues() or XtVaSetValues() or from the resource database:
| Name | Class | Type | Default Value |
| OBJECT: | |||
| destroyCallback | Callback | Pointer | NULL |
| RECTANGLE: | |||
| borderWidth height sensitive width x y |
BorderWidth Height Sensitive Width Position Position |
Dimension Dimension Boolean Dimension Position Position |
1 Space for all children True Space for all children 0 0 |
| CORE: | |||
| border background mappedWhenManaged |
BorderColor Background MappedWhenManaged |
Pixel Pixel Boolean |
XtDefaultForeground grey75 True |
| PANED: | |||
| orientation refigureMode intBorderHighlight intBorderShadow gripIndent betweenCursor cursor gripCursor leftCursor lowerCursor rightCursor upperCursor verticalGripCursor verticalBetweenCursor horizontalGripCursor horizontalBetweencursor |
Orientation Boolean BorderColor BorderColor GripIndent Cursor Cursor Cursor Cursor Cursor Cursor Cursor Cursor Cursor Cursor Cursor |
XtOrientation Boolean Pixel Pixel Position Cursor Cursor Cursor Cursor Cursor Cursor Cursor Cursor Cursor Cursor Cursor |
XtorientVertical On grey90 grey40 10 ** None ** sb_left_arrow sb_down_arrow sb_right_arrow sb_up_arrow sb_v_double_arrow sb_left_arrow sb_h_double_arrow sb_up_arrow |
** These resources now are set to the vertical or horizontal cursor depending upon orientation, by default. If a value is specified here then that cursor will be used reguardless of orientation.
| orientation | The orientation to stack the panes. This value can be either XtorientVertical or XtorientHorizontal. |
| 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. |
| internalBorderWidth | The width of each line 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 total internal border width to 6 for the Paned widget. |
| intBorderHighlight intBorderShadow |
A pixel value which indexes the widget's colormap to derive the internal border colors of the widget's window. The class name of this resource allows to set the internal border colors for the Paned widget. |
| gripIndent | The amount of space left between the right (or bottom) edge of the Paned widget and all the grips. |
| 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. |
| 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. |
| gripTranslation | Translation table that will be applied to all grips. |
| 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. |
| 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. 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. |
Each child of the Paned widget may request special layout resources be applied to it. These constraint resources allow the Form widget's children to specify individual layout requirements.
| Name | Class | RepType | Default Value |
| allowResize max min preferredPaneSize resizeToPreferred showGrip skipAdjust |
Boolean Max Min PerferredPaneSize Boolean ShowGrip Boolean |
Boolean Dimension Dimension Dimension Boolean Boolean Boolean |
False unlimited Grip Size PANED_ASK_CHILD False True False |
| 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. |
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.
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.
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.
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 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 then it will hunt through the children, from bottom to top (right to left), for a pane to resize.
When a user resizes a pane with the grips, the Paned widget assumes that this new size is the preferred size of the pane.
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> <Btn2Down> <Btn3Down> <Btn1Motion> <Btn2Motion> <Btn3Motion> <AnyBtnUp> |
GripAction(Start, UpLeftPane) GripAction(Start, ThisBorderOnly) GripAction(Start, LowRightPane) GripAction(Move, UpLeftPane) GripAction(Move, ThisBorderOnly) GripAction(Move, LowRightPane) 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. |
To enable or disable a child's request for pane resizing, use XawPanedAllowResize():
void XawPanedAllowResize(w, allow_resize)
Widget w;
Boolean allow_resize;
w Specifies the child pane. allow_resize Specifies whether or not resizing requests for this child will be granted by the Paned widget.
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;
w Specifies the child pane. min Specifies the new minimum height of the child, expressed in pixels. max Specifies new maximum height of the child, expressed in pixels.
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, max_return)
Widget w;
int *min_return, *max_return;
w Specifies the child pane. min_return Returns the minimum height of the child, expressed in pixels. max_return Returns 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;
w Specifies the Paned widget. mode Specifies whether the layout of the Paned widget is enabled (True) or disabled (False).
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;
w Specifies 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.