diff options
Diffstat (limited to 'libXaw/spec/Scrollbar')
| -rw-r--r-- | libXaw/spec/Scrollbar | 386 |
1 files changed, 0 insertions, 386 deletions
diff --git a/libXaw/spec/Scrollbar b/libXaw/spec/Scrollbar deleted file mode 100644 index faf693a3b..000000000 --- a/libXaw/spec/Scrollbar +++ /dev/null @@ -1,386 +0,0 @@ -.\" $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 *) ⊤ - XtSetArg(args[0], XtNshown, *l_top); - } -.NL -.De -.sp |