493 lines
17 KiB
Plaintext
493 lines
17 KiB
Plaintext
.\" $Xorg: Paned,v 1.3 2000/08/17 19:42:27 cpqbld Exp $
|
|
.NH 2
|
|
Paned Widget
|
|
.LP
|
|
.XS
|
|
Paned Widget
|
|
.XE
|
|
.IN "Paned widget" "" "@DEF@"
|
|
.Ds 0
|
|
.TA 2.0i
|
|
.ta 2.0i
|
|
.sp
|
|
Application Header file <X11/Xaw/Paned.h>
|
|
.IN "Paned.h" ""
|
|
Class Header file <X11/Xaw/PanedP.h>
|
|
.IN "PanedP.h" ""
|
|
Class panedWidgetClass
|
|
.IN "panedWidgetClass" ""
|
|
Class Name Paned
|
|
.IN "Paned widget" "class name"
|
|
Superclass Constraint
|
|
.sp
|
|
.De
|
|
.LP
|
|
The Paned widget manages children in a vertically or horizontally
|
|
tiled fashion. The panes may be dynamically resized by the user by
|
|
using the \fIgrips\fP that appear near the right or bottom edge of the
|
|
border between two panes.
|
|
.LP
|
|
The Paned widget may accept any widget class as a pane \fBexcept\fP
|
|
Grip. Grip widgets have a special meaning for the Paned widget, and
|
|
adding a Grip as its own pane will confuse the Paned widget.
|
|
.NH 3
|
|
Using the Paned Widget
|
|
.IN "Paned widget" "using"
|
|
.LP
|
|
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 \fBLayout Semantics\fP.
|
|
.LP
|
|
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.
|
|
.LP
|
|
The default bindings for the Paned widget's grips are:
|
|
.TS H
|
|
lw(1i) lw(2i) lw(2i).
|
|
_
|
|
.sp 3p
|
|
.TB
|
|
Mouse button Pane to Resize - Vertical Pane to Resize - Horizontal
|
|
.sp 3p
|
|
_
|
|
.TH
|
|
.R
|
|
.sp 3p
|
|
1 (left) above the grip left of the grip
|
|
2 (middle) adjust border adjust border
|
|
3 (right) below the grip right of the grip
|
|
.sp 3p
|
|
_
|
|
.TE
|
|
.NH 3
|
|
Resources
|
|
.LP
|
|
When creating a Paned widget instance, the following resources are
|
|
retrieved from the argument list or the resource database:
|
|
.LP
|
|
.IN "Paned widget" "resources"
|
|
.TS H
|
|
expand;
|
|
lw(1i) lw(1i) lw(1i) lw(.4i) lw(2i).
|
|
_
|
|
.sp 3p
|
|
.TB
|
|
Name Class Type Notes Default Value
|
|
.sp 3p
|
|
_
|
|
.TH
|
|
.R
|
|
.sp 3p
|
|
accelerators Accelerators AcceleratorTable NULL
|
|
ancestorSensitive AncestorSensitive Boolean D True
|
|
background Background Pixel XtDefaultBackground
|
|
backgroundPixmap Pixmap Pixmap XtUnspecifiedPixmap
|
|
betweenCursor Cursor Cursor A Depends on orientation
|
|
borderColor BorderColor Pixel XtDefaultForeground
|
|
borderPixmap Pixmap Pixmap XtUnspecifiedPixmap
|
|
borderWidth BorderWidth Dimension 1
|
|
children ReadOnly WidgetList R NULL
|
|
colormap Colormap Colormap Parent's Colormap
|
|
cursor Cursor Cursor None
|
|
depth Depth int C Parent's Depth
|
|
destroyCallback Callback XtCallbackList NULL
|
|
gripCursor Cursor Cursor A Depends on orientation
|
|
gripIndent GripIndent Position 10
|
|
gripTranslations Translations TranslationTable see below
|
|
height Height Dimension A Depends on orientation
|
|
horizontalBetweenCursor Cursor Cursor sb_up_arrow
|
|
horizontalGripCursor Cursor Cursor sb_h_double_arrow
|
|
internalBorderColor BorderColor Pixel XtDefaultForeground
|
|
internalBorderWidth BorderWidth Dimension 1
|
|
leftCursor Cursor Cursor sb_left_arrow
|
|
lowerCursor Cursor Cursor sb_down_arrow
|
|
mappedWhenManaged MappedWhenManaged Boolean True
|
|
numChildren ReadOnly Cardinal R 0
|
|
orientation Orientation Orientation XtorientVertical
|
|
refigureMode Boolean Boolean True
|
|
rightCursor Cursor Cursor sb_right_arrow
|
|
screen Screen Screen R Parent's Screen
|
|
sensitive Sensitive Boolean True
|
|
translations Translations TranslationTable NULL
|
|
upperCursor Cursor Cursor sb_up_arrow
|
|
verticalBetweenCursor Cursor Cursor sb_left_arrow
|
|
verticalGripCursor Cursor Cursor sb_v_double_arrow
|
|
width Width Dimension A Depends on orientation
|
|
x Paned Position 0
|
|
y Paned Position 0
|
|
.sp 3p
|
|
_
|
|
.TE
|
|
.Ac
|
|
.As
|
|
.Bg
|
|
.Gp
|
|
.Bc
|
|
.Bp
|
|
.Bw
|
|
.Ch
|
|
.Cm
|
|
.IP \fBcursor\fP 1.5i
|
|
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.
|
|
.Dp
|
|
.Dc
|
|
.IP \fBgripCursor\fP 1.5i
|
|
The cursor to use when the grips are not active. The default value is
|
|
\fBverticalGripCursor\fP or \fBhorizontalGripCursor\fP depending on
|
|
the orientation of the Paned widget.
|
|
.IP \fBgripIndent\fP 1.5i
|
|
The amount of space left between the right (or bottom) edge of the
|
|
Paned widget and all the grips.
|
|
.IP \fBgripTranslation\fP 1.5i
|
|
Translation table that will be applied to all grips.
|
|
.Hw
|
|
.IP \fBhorizontalBetweenCursor\fP 1.5i
|
|
.br
|
|
.ns
|
|
.IP \fBverticalBetweenCursor\fP 1.5i
|
|
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.
|
|
.IP \fBhorizontalGripCursor\fP 1.5i
|
|
.br
|
|
.ns
|
|
.IP \fBverticalGripCursor\fP 1.5i
|
|
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.
|
|
.IP \fBinternalBorderColor\fP 1.5i
|
|
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 \fIPaned*BorderColor: blue\fP to set the internal border color
|
|
for the Paned widget. An optimization is invoked if
|
|
\fBinternalBorderColor\fP and \fBbackground\fP are the same, and the
|
|
internal borders are not drawn. \fBinternalBorderWidth\fP is still left
|
|
between the panes, however.
|
|
.IP \fBinternalBorderWidth\fP 1.5i
|
|
The width of the internal borders. This is the amount of space left
|
|
between the panes. The class name of this resource allows
|
|
\fIPaned*BorderWidth: 3\fP to set the internal border width for the
|
|
Paned widget.
|
|
.IP \fBleftCursor\fP 1.5i
|
|
.br
|
|
.ns
|
|
.IP \fBrightCursor\fP 1.5i
|
|
The cursor used to indicate which is the \fIimportant\fP pane to resize
|
|
when the Paned widget is oriented horizontally.
|
|
.IP \fBlowerCursor\fP 1.5i
|
|
.br
|
|
.ns
|
|
.IP \fBupperCursor\fP 1.5i
|
|
The cursor used to indicate which is the \fIimportant\fP pane to resize
|
|
when the Paned widget is oriented vertically.
|
|
.Mm
|
|
.Nc
|
|
This is not the same as the number of panes, since this also contains a
|
|
grip for some of the panes, use \fBXawPanedGetNumSub\fP to retrieve the
|
|
number of panes.
|
|
.IP \fBorientation\fP 1.5i
|
|
The orientation to stack the panes. This value can be either
|
|
\fBXtorientVertical\fP or \fBXtorientHorizontal\fP.
|
|
.IN "XtorientVertical" ""
|
|
.IN "XtorientHorizontal" ""
|
|
.IN "conversions" "Orientation"
|
|
.Rs "vertical \fPand\fB horizontal"
|
|
.IP \fBrefigureMode\fP 1.5i
|
|
This resource allows pane layout to be suspended. If this value is
|
|
\fBFalse\fP, then no layout actions will be taken. This may improve
|
|
efficiency when adding or removing more than one pane from the Paned
|
|
widget.
|
|
.Sc
|
|
.Se
|
|
.Tr
|
|
.Xy
|
|
.NH 3
|
|
Constraint Resources
|
|
.LP
|
|
.IN "Paned widget" "constraint resources"
|
|
Each child of the Paned widget may request special layout resources
|
|
be applied to it. These \fIconstraint\fP resources allow the Paned
|
|
widget's children to specify individual layout requirements.
|
|
.LP
|
|
.TS H
|
|
lw(1i) lw(1i) lw(1i) lw(.5i) lw(2i).
|
|
_
|
|
.sp 3p
|
|
.TB
|
|
Name Class Type Notes Default Value
|
|
.sp 3p
|
|
_
|
|
.TH
|
|
.R
|
|
.sp 3p
|
|
allowResize Boolean Boolean False
|
|
max Max Dimension Infinity
|
|
min Min Dimension Height of Grips
|
|
preferredPaneSize PreferredPaneSize Dimension ask child
|
|
resizeToPreferred Boolean Boolean False
|
|
showGrip ShowGrip Boolean True
|
|
skipAdjust Boolean Boolean False
|
|
.sp 3p
|
|
_
|
|
.TE
|
|
.IP \fBallowResize\fP 1.5i
|
|
If this value is \fBFalse\fP the the Paned widget will disallow all
|
|
geometry requests from this child.
|
|
.IP \fBmax\fP 1.5i
|
|
.br
|
|
.ns
|
|
.IP \fBmin\fP 1.5i
|
|
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.
|
|
.IP \fBpreferredPaneSize\fP 1.5i
|
|
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.
|
|
.IP \fBresizeToPreferred\fP 1.5i
|
|
Determines whether or not to resize each pane to its preferred size
|
|
when the Paned widget is resized. See \fBLayout Semantics\fP for details.
|
|
.IP \fBshowGrip\fP 1.5i
|
|
If \fBTrue\fP 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.
|
|
.IP \fBskipAdjust\fP 1.5i
|
|
This resource is used to determine which pane is forced to be resized.
|
|
Setting this value to \fBTrue\fP makes this pane less likely to be
|
|
forced to be resized. See \fBLayout Semantics\fP for details.
|
|
.NH 3
|
|
Layout Semantics
|
|
.LP
|
|
.IN "Paned widget" "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.
|
|
.LP
|
|
.sp
|
|
\fBLayout Rules\fP
|
|
.IP \fB1\fP .5i
|
|
Do not let a pane grow larger than its \fBmax\fP or smaller than its
|
|
\fBmin\fP.
|
|
.IP \fB2\fP .5i
|
|
Do not adjust panes with \fBskipAdjust\fP set.
|
|
.IP \fB3\fP .5i
|
|
Do not adjust panes away from their preferred size, although moving one
|
|
closer to its preferred size is fine.
|
|
.LP
|
|
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.
|
|
.LP
|
|
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.
|
|
.NH 4
|
|
Resizing Panes from a Grip Action
|
|
.LP
|
|
The pane above the grip is resized by invoking the GripAction with
|
|
\fBUpLeftPane\fP 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.
|
|
.LP
|
|
The pane below the grip is resized by invoking the GripAction with
|
|
\fBLowRightPane\fP specified. The panes above the grip are each
|
|
checked in this case. No pane below the chosen pane will ever be resized.
|
|
.LP
|
|
Invoking GripAction with \fBThisBorderOnly\fP specified just moves the
|
|
border between the panes. No other panes are ever resized.
|
|
.NH 4
|
|
Resizing Panes after the Paned widget is resized.
|
|
.LP
|
|
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
|
|
\fBresizeToPreferred\fP resource allows the application to tell the
|
|
Paned widget whether to query the child about its preferred size
|
|
(subject to the the \fBpreferredPaneSize\fP) or to use the current size
|
|
when refiguring the pane locations after the pane has been resized.
|
|
.LP
|
|
There is one special case. All panes assume they should resize to
|
|
their preferred size until the Paned widget becomes visible to the user.
|
|
.NH 4
|
|
Managing Children and Geometry Management
|
|
.LP
|
|
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.
|
|
.NH 4
|
|
Special Considerations
|
|
.LP
|
|
When a user resizes a pane with the grips, the Paned widget assumes that
|
|
this new size is the preferred size of the pane.
|
|
.NH 3
|
|
Grip Translations
|
|
.LP
|
|
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.
|
|
.LP
|
|
.sp
|
|
.Ds 0
|
|
.TA .5i 2.25i
|
|
.ta .5i 2.25i
|
|
<Btn1Down>: GripAction(Start, UpLeftPane)
|
|
.IN "GripAction" ""
|
|
<Btn2Down>: GripAction(Start, ThisBorderOnly)
|
|
<Btn3Down>: GripAction(Start, LowRightPane)
|
|
<Btn1Motion>: GripAction(Move, UpLeftPane)
|
|
<Btn2Motion>: GripAction(Move, ThisBorderOnly)
|
|
<Btn3Motion>: GripAction(Move, LowRightPane)
|
|
Any<BtnUp>: GripAction(Commit)
|
|
.De
|
|
.sp
|
|
.LP
|
|
The Paned widget interprets the \fBGripAction\fP as taking two arguments.
|
|
.IN "GripAction" ""
|
|
The first argument may be any of the following:
|
|
.IP \fBStart\fP 1i
|
|
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.
|
|
.IP \fBMove\fP 1i
|
|
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 \fBStart\fP action, that began this process. If
|
|
these arguments are not passed, the behavior is undefined.
|
|
.IP \fBCommit\fP 1i
|
|
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.
|
|
.NH 3
|
|
Convenience Routines
|
|
.LP
|
|
.IN "Paned widget" "enable pane resizing"
|
|
.IN "Paned widget" "disable pane resizing"
|
|
To enable or disable a child's request for pane resizing,
|
|
use
|
|
.PN XawPanedAllowResize :
|
|
.IN "XawPanedAllowResize" "" "@DEF@"
|
|
.FD 0
|
|
void XawPanedAllowResize(\fIw\fP, \fIallow_resize\fP)
|
|
.br
|
|
Widget \fIw\fP;
|
|
.br
|
|
Boolean \fIallow_resize\fP;
|
|
.FN
|
|
.IP \fIw\fP 1i
|
|
Specifies the child pane.
|
|
.IP \fIallow_resize\fP
|
|
Specifies whether or not resizing requests for this child will be
|
|
granted by the Paned widget.
|
|
.LP
|
|
If allow_resize is \fBTrue\fP, the Paned widget allows geometry
|
|
requests from the child to change the pane's height. If allow_resize
|
|
is \fBFalse\fP, the Paned widget ignores geometry requests from the
|
|
child to change the pane's height. The default state is \fBTrue\fP
|
|
before the Pane is realized and \fBFalse\fP after it is realized.
|
|
This procedure is equivalent to changing the \fBallowResize\fP
|
|
constraint resource for the child.
|
|
.LP
|
|
.sp
|
|
.IN "Paned widget" "change height settings"
|
|
To change the minimum and maximum height settings for a pane, use
|
|
.PN XawPanedSetMinMax :
|
|
.IN "XawPanedSetMinMax" "" "@DEF@"
|
|
.FD 0
|
|
void XawPanedSetMinMax(\fIw\fP, \fImin\fP, \fImax\fP)
|
|
.br
|
|
Widget \fIw\fP;
|
|
.br
|
|
int \fImin\fP, \fImax\fP;
|
|
.FN
|
|
.IP \fIw\fP 1i
|
|
Specifies the child pane.
|
|
.IP \fImin\fP 1i
|
|
Specifies the new minimum height of the child, expressed in pixels.
|
|
.IP \fImax\fP 1i
|
|
Specifies new maximum height of the child, expressed in pixels.
|
|
.LP
|
|
This procedure is equivalent to setting the \fBmin\fP and \fBmax\fP
|
|
constraint resources for the child.
|
|
.LP
|
|
.sp
|
|
.IN "Paned widget" "get height settings"
|
|
To retrieve the minimum and maximum height settings for a pane, use
|
|
.PN XawPanedGetMinMax :
|
|
.IN "XawPanedGetMinMax" "" "@DEF@"
|
|
.FD 0
|
|
void XawPanedGetMinMax(\fIw\fP, \fImin_return\fP, \fImax_return\fP)
|
|
.br
|
|
Widget \fIw\fP;
|
|
.br
|
|
int \fI*min_return\fP, \fI*max_return\fP;
|
|
.FN
|
|
.IP \fIw\fP 1i
|
|
Specifies the child pane.
|
|
.IP \fImin_return\fP 1i
|
|
Returns the minimum height of the child, expressed in pixels.
|
|
.IP \fImax_return\fP 1i
|
|
Returns the maximum height of the child, expressed in pixels.
|
|
.LP
|
|
This procedure is equivalent to getting the \fBmin\fP and \fBmax\fP
|
|
resources for this child child.
|
|
.LP
|
|
.sp
|
|
.IN "Paned widget" "enable auto-reconfiguring"
|
|
.IN "Paned widget" "disable auto-reconfiguring"
|
|
To enable or disable automatic recalculation of pane sizes and positions,
|
|
use
|
|
.PN XawPanedSetRefigureMode :
|
|
.IN "XawPanedSetRefigureMode" "" "@DEF@"
|
|
.FD 0
|
|
void XawPanedSetRefigureMode(\fIw\fP, \fImode\fP)
|
|
.br
|
|
Widget \fIw\fP;
|
|
.br
|
|
Boolean \fImode\fP;
|
|
.FN
|
|
.IP \fIw\fP 1i
|
|
Specifies the Paned widget.
|
|
.IP \fImode\fP 1i
|
|
Specifies whether the layout of the Paned widget is enabled (\fBTrue\fP)
|
|
or disabled (\fBFalse\fP).
|
|
.LP
|
|
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.
|
|
.LP
|
|
.sp
|
|
.IN "Paned widget" "getting the number of children"
|
|
To retrieve the number of panes in a paned widget use
|
|
\fBXawPanedGetNumSub\fP:
|
|
.IN "XawPanedGetNumSub" "" "@DEF@"
|
|
.FD 0
|
|
int XawPanedGetNumSub(\fIw\fP)
|
|
.br
|
|
Widget \fIw\fP;
|
|
.FN
|
|
.IP \fIw\fP 1i
|
|
Specifies the Paned widget.
|
|
.LP
|
|
This function returns the number of panes in the Paned widget. This is
|
|
\fBnot\fP the same as the number of children, since the grips are also
|
|
children of the Paned widget.
|