aboutsummaryrefslogtreecommitdiff
path: root/libXaw/spec/Paned
diff options
context:
space:
mode:
authormarha <marha@users.sourceforge.net>2009-11-06 06:59:46 +0000
committermarha <marha@users.sourceforge.net>2009-11-06 06:59:46 +0000
commitace7902333b6f61aab5a6035dbcb222763bff186 (patch)
tree28445e829d5f04c8d79bda2514be37d5fb29738e /libXaw/spec/Paned
parentc9179017c7e70703b7cac46c2df8b950506319e0 (diff)
downloadvcxsrv-ace7902333b6f61aab5a6035dbcb222763bff186.tar.gz
vcxsrv-ace7902333b6f61aab5a6035dbcb222763bff186.tar.bz2
vcxsrv-ace7902333b6f61aab5a6035dbcb222763bff186.zip
Added libXaw-1.0.7
Diffstat (limited to 'libXaw/spec/Paned')
-rw-r--r--libXaw/spec/Paned492
1 files changed, 492 insertions, 0 deletions
diff --git a/libXaw/spec/Paned b/libXaw/spec/Paned
new file mode 100644
index 000000000..a6b8f0089
--- /dev/null
+++ b/libXaw/spec/Paned
@@ -0,0 +1,492 @@
+.\" $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.