Added libXaw

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.