diff options
Diffstat (limited to 'libXaw/spec/Paned')
| -rw-r--r-- | libXaw/spec/Paned | 492 |
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. |