aboutsummaryrefslogtreecommitdiff
path: root/libXaw/spec/Scrollbar
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/Scrollbar
parentc9179017c7e70703b7cac46c2df8b950506319e0 (diff)
downloadvcxsrv-ace7902333b6f61aab5a6035dbcb222763bff186.tar.gz
vcxsrv-ace7902333b6f61aab5a6035dbcb222763bff186.tar.bz2
vcxsrv-ace7902333b6f61aab5a6035dbcb222763bff186.zip
Added libXaw-1.0.7
Diffstat (limited to 'libXaw/spec/Scrollbar')
-rw-r--r--libXaw/spec/Scrollbar386
1 files changed, 386 insertions, 0 deletions
diff --git a/libXaw/spec/Scrollbar b/libXaw/spec/Scrollbar
new file mode 100644
index 000000000..faf693a3b
--- /dev/null
+++ b/libXaw/spec/Scrollbar
@@ -0,0 +1,386 @@
+.\" $Xorg: Scrollbar,v 1.3 2000/08/17 19:42:27 cpqbld Exp $
+.NH 2
+Scrollbar Widget
+.LP
+.XS
+ Scrollbar Widget
+.XE
+.IN "Scrollbar widget" "" "@DEF@"
+.Ds 0
+.TA 2.0i
+.ta 2.0i
+.sp
+Application header file <X11/Xaw/Scrollbar.h>
+.IN "Scrollbar.h" ""
+Class header file <X11/Xaw/ScrollbarP.h>
+.IN "ScrollbarP.h" ""
+Class scrollbarWidgetClass
+.IN "scrollbarWidgetClass" ""
+Class Name Scrollbar
+.IN "Scrollbar widget" "class name"
+Superclass Simple
+.sp
+.De
+.LP
+A Scrollbar widget is a rectangle, called the ``canvas,'' on
+which another rectangle, the ``thumb,'' moves in one
+dimension, either vertically or horizontally. A Scrollbar
+can be used alone, as a value generator, or it can be used
+within a composite widget (for example, a Viewport). When a
+Scrollbar is used to move, or ``scroll,'' the contents of
+another widget, the size and the position of the thumb usually give
+feedback as to what portion of the other widget's contents
+are visible.
+.LP
+Each pointer button invokes a specific action. Pointer
+buttons 1 and 3 do not move the thumb automatically.
+Instead, they return the pixel position of the cursor on the
+scroll region. When pointer button 2 is clicked, the thumb
+moves to the current pointer position. When pointer button
+2 is held down and the pointer is moved, the thumb follows
+the pointer.
+.LP
+The pointer cursor in the scroll region changes depending on the current
+action. When no pointer button is pressed, the cursor appears as a
+double-headed arrow that points in the direction that scrolling can
+occur. When pointer button 1 or 3 is pressed, the cursor appears as a
+single-headed arrow that points in the logical direction that the thumb
+will move. When pointer button 2 is pressed, the cursor
+appears as an arrow that points to the top or the left of the thumb.
+.LP
+When the user scrolls, the application receives notification
+through callback procedures. For both discrete scrolling actions, the
+callback returns the Scrollbar widget, the client_data, and the pixel
+position of the pointer when the button was released. For continuous
+scrolling, the callback routine returns the scroll bar widget, the
+client data, and the current relative position of the thumb. When the
+thumb is moved using pointer button 2, the callback procedure is invoked
+continuously. When either button 1 or 3 is pressed, the callback
+procedure is invoked only when the button is released and the client
+callback procedure is responsible for moving the thumb.
+.NH 3
+Resources
+.LP
+When creating a Scrollbar widget instance, the following resources are
+retrieved from the argument list or from the resource database:
+.LP
+.IN "Scrollbar widget" "resources"
+.TS H
+expand;
+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
+accelerators Accelerators AcceleratorTable NULL
+ancestorSensitive AncestorSensitive Boolean D True
+background Background Pixel XtDefaultBackground
+backgroundPixmap Pixmap Pixmap XtUnspecifiedPixmap
+borderColor BorderColor Pixel XtDefaultForeground
+borderPixmap Pixmap Pixmap XtUnspecifiedPixmap
+borderWidth BorderWidth Dimension 1
+colormap Colormap Colormap parent's Colormap
+cursor Cursor Cursor None
+cursorName Cursor String NULL
+depth Depth int C parent's Depth
+destroyCallback Callback XtCallbackList NULL
+foreground Foreground Pixel XtDefaultForeground
+height Height Dimension A depends on orientation
+insensitiveBorder Insensitive Pixmap GreyPixmap
+international International Boolean C False
+jumpProc Callback XtCallbackList NULL
+length Length Dimension 1
+mappedWhenManaged MappedWhenManaged Boolean True
+minimumThumb MinimumThumb Dimension 7
+orientation Orientation Orientation XtorientVertical (vertical)
+pointerColor Foreground Pixel XtDefaultForeground
+pointerColorBackground Background Pixel XtDefaultBackground
+screen Screen Screen R parent's Screen
+scrollDCursor Cursor Cursor XC_sb_down_arrow
+scrollHCursor Cursor Cursor XC_sb_h_double_arrow
+scrollLCursor Cursor Cursor XC_sb_left_arrow
+scrollProc Callback XtCallbackList NULL
+scrollRCursor Cursor Cursor XC_sb_right_arrow
+scrollUCursor Cursor Cursor XC_sb_up_arrow
+scrollVCursor Cursor Cursor XC_sb_v_arrow
+sensitive Sensitive Boolean True
+shown Shown Float 0.0
+thickness Thickness Dimension 14
+thumb Thumb Bitmap GreyPixmap
+thumbProc Callback XtCallbackList NULL
+topOfThumb TopOfThumb Float 0.0
+translations Translations TranslationTable See below
+width Width Dimension A depends on orientation
+x Position Position 0
+y Position Position 0
+.sp 3p
+_
+.TE
+.Ac
+.As
+.Bg
+.Gp
+.Bc
+.Bp
+.Bw
+.Cm
+.Cu
+.Cn
+.Dp
+.Dc
+.IP \fBforeground\fP 1.5i
+A pixel value which indexes the widget's colormap to derive the color
+used to draw the thumb.
+.Hw
+.Ib
+.Ix
+.IP \fBjumpProc\fP 1.5i
+All functions on this callback list are called when the
+\fBNotifyThumb\fP action is invoked. See the \fBScrollbar
+Actions\fP section for details.
+.IP \fBlength\fP 1.5i
+The height of a vertical scrollbar or the width of a horizontal scrollbar.
+.Mm
+.IP \fBminimumThumb\fP 1.5i
+The smallest size, in pixels, to which the thumb can shrink.
+.IP \fBorientation\fP 1.5i
+The orientation is the direction that the thumb will be allowed to move.
+This value can be either \fBXtorientVertical\fP or
+\fBXtorientHorizontal\fP.
+.IN "XtorientVertical" ""
+.IN "XtorientHorizontal" ""
+.IN "conversions" "Orientation"
+.Rs "vertical \fPand\fB horizontal"
+.Pf
+.Pb
+.Sc
+.IP \fBscrollDCursor\fP 1.5i
+This cursor is used when scrolling backward in a vertical scrollbar.
+.IP \fBscrollHCursor\fP 1.5i
+This cursor is used when a horizontal scrollbar is inactive.
+.IP \fBscrollLCursor\fP 1.5i
+This cursor is used when scrolling forward in a horizontal scrollbar.
+.IP \fBscrollProc\fP 1.5i
+All functions on this callback list may be called when the
+\fBNotifyScroll\fP action is invoked. See the \fBScrollbar
+Actions\fP section for details.
+.IP \fBscrollRCursor\fP 1.5i
+This cursor is used when scrolling backward in a horizontal scrollbar,
+or when thumbing a vertical scrollbar.
+.IP \fBscrollUCursor\fP 1.5i
+This cursor is used when scrolling forward in a vertical scrollbar, or when
+thumbing a horizontal scrollbar.
+.IP \fBscrollVCursor\fP 1.5i
+This cursor is used when a vertical scrollbar is inactive.
+.Se
+.IP \fBshown\fP 1.5i
+This is the size of the thumb, expressed as a percentage (0.0 - 1.0)
+of the length of the scrollbar.
+.IP \fBthickness\fP 1.5i
+The width of a vertical scrollbar or the height of a horizontal scrollbar.
+.IP \fBthumb\fP 1.5i
+This pixmap is used to tile (or stipple) the thumb of the scrollbar. If
+no tiling is desired, then set this resource to \fBNone\fP. This
+resource will accept either a bitmap or a pixmap that is the same depth
+as the window. The resource converter for this resource constructs
+bitmaps from the contents of files. (See \fBConverting Bitmaps\fP for
+details.)
+.IP \fBtopOfThumb\fP 1.5i
+The location of the top of the thumb, as a percentage (0.0 - 1.0)
+of the length of the scrollbar. This resource was called \fBtop\fP in
+previous versions of the Athena widget set. The name collided with the
+a Form widget constraint resource, and had to be changed.
+.Tr
+.Xy
+.NH 3
+Scrollbar Actions
+.IN "Scrollbar widget" "actions"
+.LP
+The actions supported by the Scrollbar widget are:
+.IP \fBStartScroll\fP(\fIvalue\fP) 1.5i
+The possible \fIvalues\fP are Forward, Backward, or Continuous.
+This must be the first action to begin a new movement.
+.IP \fBNotifyScroll\fP(\fIvalue\fP) 1.5i
+The possible \fIvalues\fP are Proportional or FullLength. If the
+argument to StartScroll was Forward or Backward, NotifyScroll executes
+the \fBscrollProc\fP callbacks and passes either; the position of the
+pointer, if \fIvalue\fP is Proportional, or the full length of the
+scroll bar, if \fIvalue\fP is FullLength. If the argument to
+StartScroll was Continuous, NotifyScroll returns without executing any
+callbacks.
+.IP \fBEndScroll\fP(\^) 1.5i
+This must be the last action after a movement is complete.
+.IP \fBMoveThumb\fP(\^) 1.5i
+Repositions the Scrollbar's thumb to the current pointer location.
+.IP \fBNotifyThumb\fP(\^)\ \ \ 1.5i
+Calls the
+.PN jumpProc
+callbacks and passes the relative position of the
+pointer as a percentage of the scroll bar length.
+.LP
+.sp
+The default bindings for Scrollbar are:
+.IN "Scrollbar widget" "default translation table"
+.LP
+.Ds 0
+.TA .5i 1.75i
+.ta .5i 1.75i
+ <Btn1Down>: StartScroll(Forward)
+ <Btn2Down>: StartScroll(Continuous) MoveThumb(\|) NotifyThumb(\|)
+ <Btn3Down>: StartScroll(Backward)
+ <Btn2Motion>: MoveThumb(\|) NotifyThumb(\|)
+ <BtnUp>: NotifyScroll(Proportional) EndScroll(\|)
+.De
+.LP
+.sp
+Examples of additional bindings a user might wish to specify in a
+resource file are:
+.LP
+.Ds 0
+.TA .5i 2.25i
+.ta .5i 2.25i
+*Scrollbar.Translations: \\
+ ~Meta<Key>space: StartScroll(Forward) NotifyScroll(FullLength) \\n\\
+ Meta<Key>space: StartScroll(Backward) NotifyScroll(FullLength) \\n\\
+ EndScroll(\|)
+.De
+.NH 3
+Scrollbar Callbacks
+.IN "Scrollbar widget" "callbacks"
+.LP
+There are two callback lists provided by the Scrollbar widget.
+The procedural interface for these functions is described here.
+.LP
+The calling interface to the \fBscrollProc\fP callback procedure is:
+.IN "ScrollProc" "" "@DEF@"
+.FD 0
+void ScrollProc(\fIscrollbar\fP, \fIclient_data\fP, \fIposition\fP)
+.br
+ Widget \fIscrollbar\fP;
+.br
+ XtPointer \fIclient_data\fP;
+.br
+ XtPointer \fIposition\fP; /* int */
+.FN
+.IP \fIscrollbar\fP 1i
+Specifies the Scrollbar widget.
+.IP \fIclient_data\fP 1i
+Specifies the client data.
+.IP \fIposition\fP 1i
+Specifies a pixel position in integer form.
+.LP
+The \fBscrollProc\fP callback is used for incremental scrolling
+and is called by the \fBNotifyScroll\fP action.
+The position argument is a signed quantity and should be cast to an int
+when used. Using the default button bindings, button 1 returns a
+positive value, and button 3 returns a negative value. In both cases,
+the magnitude of the value is the distance of the pointer in
+pixels from the top (or left) of the Scrollbar. The value will never
+be greater than the length of the Scrollbar.
+.LP
+.sp
+The calling interface to the \fBjumpProc\fP callback procedure is:
+.IN "jumpProc" "" "@DEF@"
+.FD 0
+void JumpProc(\fIscrollbar\fP, \fIclient_data\fP, \fIpercent\fP)
+.br
+ Widget \fIscrollbar\fP;
+.br
+ XtPointer \fIclient_data\fP;
+.br
+ XtPointer \fIpercent_ptr\fP; /* float* */
+.FN
+.IP \fIscrollbar\fP 1i
+Specifies the ID of the scroll bar widget.
+.IP \fIclient_data\fP 1i
+Specifies the client data.
+.IP \fIpercent_ptr\fP 1i
+Specifies the floating point position of the thumb (0.0 \- 1.0).
+.LP
+The \fBjumpProc\fP callback is used to implement smooth scrolling and
+is called by the \fBNotifyThumb\fP action. Percent_ptr must be cast
+to a pointer to float before use; i.e.
+.LP
+.Ds 0
+.TA .5i
+.ta .5i
+ float percent = *(float*)percent_ptr;
+.De
+.LP
+With the default button bindings, button 2 moves the thumb interactively,
+and the \fBjumpProc\fP is called on each new position of the pointer,
+while the pointer button remains down. The value specified by
+\fIpercent_ptr\fP is the current location of the thumb (from the top or
+left of the Scrollbar) expressed as a percentage of the length of the
+Scrollbar.
+.NH 3
+Convenience Routines
+.LP
+.IN "Scrollbar widget" "setting thumb values"
+To set the position and length of a Scrollbar thumb, use
+.PN XawScrollbarSetThumb .
+.IN "XawScrollbarSetThumb" "" "@DEF@"
+.FD 0
+void XawScrollbarSetThumb(\fIw\fP, \fItop\fP, \fIshown\fP)
+.br
+ Widget \fIw\fP;
+.br
+ float \fItop\fP;
+.br
+ float \fIshown\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the Scrollbar widget.
+.IP \fItop\fP 1i
+Specifies the position of the top of the thumb as a fraction of the
+length of the Scrollbar.
+.IP \fIshown\fP 1i
+Specifies the length of the thumb as a fraction of the total length
+of the Scrollbar.
+.LP
+.PN XawScrollbarThumb
+moves the visible thumb to a new position (0.0 \- 1.0) and length (0.0 \- 1.0).
+Either the top or shown arguments can be specified as \-1.0,
+in which case the current value is left unchanged.
+Values greater than 1.0 are truncated to 1.0.
+.LP
+If called from \fBjumpProc\fP, \fBXawScrollbarSetThumb\fP has no effect.
+.NH 3
+Setting Float Resources
+.IN "float resources" "setting"
+.LP
+The \fBshown\fP and \fBtopOfThumb\fP resources are of type
+\fIfloat\fP. These resources can be difficult to get into an
+argument list. The reason is that C performs an automatic cast of
+the float value to an integer value, usually truncating the important
+information. The following code fragment is one portable method of
+getting a float into an argument list.
+.sp
+.Ds 0
+.SM
+.TA 1i 2i
+.ta 1i 2i
+ top = 0.5;
+ if (sizeof(float) > sizeof(XtArgVal)) {
+ /*
+ \ * If a float is larger than an XtArgVal then pass this
+ \ * resource value by reference.
+ \ */
+ XtSetArg(args[0], XtNshown, &top);
+ }
+ else {
+ /*
+ \ * Convince C not to perform an automatic conversion, which
+ \ * would truncate 0.5 to 0.
+ \ */
+ XtArgVal * l_top = (XtArgVal *) &top;
+ XtSetArg(args[0], XtNshown, *l_top);
+ }
+.NL
+.De
+.sp