diff options
Diffstat (limited to 'libXaw/spec/Scrollbar')
| -rw-r--r-- | libXaw/spec/Scrollbar | 386 |
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 *) ⊤ + XtSetArg(args[0], XtNshown, *l_top); + } +.NL +.De +.sp |