home *** CD-ROM | disk | FTP | other *** search
/ InfoMagic Source Code 1993 July / THE_SOURCE_CODE_CD_ROM.iso / X / mit / doc / Xaw / Scrollbar < prev    next >
Encoding:
Text File  |  1991-07-29  |  12.9 KB  |  396 lines
  1. .NH 2 
  2. Scrollbar Widget
  3. .LP
  4. .XS
  5.     Scrollbar Widget
  6. .XE
  7. .IN "Scrollbar widget" "" "@DEF@"
  8. .Ds 0
  9. .TA 2.0i
  10. .ta 2.0i
  11. .sp
  12. Application header file    <X11/Xaw/Scrollbar.h>
  13. .IN "Scrollbar.h" ""
  14. Class header file    <X11/Xaw/ScrollbarP.h>
  15. .IN "ScrollbarP.h" ""
  16. Class        scrollbarWidgetClass
  17. .IN "scrollbarWidgetClass" ""
  18. Class Name    Scrollbar
  19. .IN "Scrollbar widget" "class name"
  20. Superclass    Simple
  21. .sp
  22. .De
  23. .LP
  24. The Scrollbar widget is a rectangular area containing a slide region
  25. and a thumb (also known as a slide bar).  A Scrollbar can be used alone,
  26. as a value generator, or it can be used within a composite widget (for
  27. example, a Viewport).  A Scrollbar can be oriented either vertically or
  28. horizontally.
  29. .LP
  30. When a Scrollbar is created, it is drawn with the thumb in a contrasting
  31. color.  The thumb is normally used to scroll client data and to give
  32. visual feedback on the percentage of the client data that is visible.
  33. .LP
  34. Each pointer button invokes a specific action.  That is, given either a
  35. vertical or horizontal orientation, the pointer button actions will
  36. scroll or return data as appropriate for that orientation.  Pointer
  37. buttons 1 and 3 do not move the thumb automatically.  Instead, they
  38. return the pixel position of the cursor on the scroll region.  When
  39. pointer button 2 is clicked, the thumb moves to the current pointer
  40. position.  When pointer button 2 is held down and the pointer is moved,
  41. the thumb follows the pointer.
  42. .LP
  43. The pointer cursor in the scroll region changes depending on the current
  44. action.  When no pointer button is pressed, the cursor appears as a
  45. double-headed arrow that points in the direction that scrolling can
  46. occur.  When pointer button 1 or 3 is pressed, the cursor appears as a
  47. single-headed arrow that points in the logical direction that the client
  48. will move the data.  When pointer button 2 is pressed, the cursor
  49. appears as an arrow that points to the thumb.
  50. .LP
  51. While scrolling is in progress, the application receives notification
  52. through callback procedures.  For both discrete scrolling actions, the
  53. callback returns the Scrollbar widget, the client_data, and the pixel
  54. position of the pointer when the button was released.  For continuous
  55. scrolling, the callback routine returns the scroll bar widget, the
  56. client data, and the current relative position of the thumb.  When the
  57. thumb is moved using pointer button 2, the callback procedure is invoked
  58. continuously.  When either button 1 or 3 is pressed, the callback
  59. procedure is invoked only when the button is released and the client
  60. callback procedure is responsible for moving the thumb.
  61. .NH 3
  62. Resources
  63. .LP
  64. When creating a Scrollbar widget instance, the following resources are
  65. retrieved from the argument list or from the resource database:
  66. .LP
  67. .IN "Scrollbar widget" "resources"
  68. .ps 9
  69. .nr PS 9
  70. .vs 11
  71. .nr VS 11
  72. .TS H
  73. expand;
  74. lw(1i) lw(1i) lw(1i) lw(.5i) lw(2i).
  75. _
  76. .sp 3p
  77. .TB
  78. Name    Class    Type    Notes    Default Value
  79. .sp 3p
  80. _
  81. .TH
  82. .R
  83. .sp 3p
  84. accelerators    Accelerators    AcceleratorTable        NULL
  85. ancestorSensitive    AncestorSensitive    Boolean    D    True
  86. background    Background    Pixel        XtDefaultBackground
  87. backgroundPixmap    Pixmap    Pixmap        XtUnspecifiedPixmap
  88. borderColor    BorderColor    Pixel        XtDefaultForeground
  89. borderPixmap    Pixmap    Pixmap        XtUnspecifiedPixmap
  90. borderWidth    BorderWidth    Dimension        1
  91. colormap    Colormap    Colormap        parent's Colormap
  92. cursor    Cursor    Cursor        None
  93. cursorName    Cursor    String        NULL
  94. depth    Depth    int    C    parent's Depth
  95. destroyCallback    Callback    XtCallbackList        NULL
  96. foreground    Foreground    Pixel        XtDefaultForeground
  97. height    Height    Dimension    A    depends on orientation
  98. insensitiveBorder    Insensitive    Pixmap        GreyPixmap
  99. jumpProc    Callback    XtCallbackList        NULL
  100. length    Length    Dimension        1
  101. mappedWhenManaged    MappedWhenManaged    Boolean        True
  102. minimumThumb    MinimumThumb    Dimension        7
  103. orientation    Orientation    Orientation        XtorientVertical (vertical)
  104. pointerColor    Foreground    Pixel        XtDefaultForeground
  105. pointerColorBackground    Background    Pixel        XtDefaultBackground
  106. screen    Screen    Screen    R    parent's Screen
  107. scrollDCursor    Cursor    Cursor        XC_sb_down_arrow
  108. scrollHCursor    Cursor    Cursor        XC_sb_h_double_arrow
  109. scrollLCursor    Cursor    Cursor        XC_sb_left_arrow
  110. scrollProc    Callback    XtCallbackList        NULL
  111. scrollRCursor    Cursor    Cursor        XC_sb_right_arrow
  112. scrollUCursor    Cursor    Cursor        XC_sb_up_arrow
  113. scrollVCursor    Cursor    Cursor        XC_sb_v_arrow
  114. sensitive    Sensitive    Boolean        True
  115. shown    Shown    Float        0.0
  116. thickness    Thickness    Dimension        14
  117. thumb    Thumb    Bitmap        GreyPixmap
  118. thumbProc    Callback    XtCallbackList        NULL
  119. topOfThumb    TopOfThumb    Float        0.0
  120. translations    Translations    TranslationTable        See below
  121. width    Width    Dimension    A    depends on orientation
  122. x    Position    Position        0
  123. y    Position    Position        0
  124. .sp 3p
  125. _
  126. .TE
  127. .ps 11
  128. .nr PS 11
  129. .vs 13
  130. .nr VS 13
  131. .Ac
  132. .As
  133. .Bg
  134. .Gp
  135. .Bc
  136. .Bp
  137. .Bw
  138. .Cm
  139. .Cu
  140. .Pn
  141. .Pn
  142. .Dp
  143. .Dc
  144. .IP \fBforeground\fP 1.5i
  145. A pixel value which indexes the widget's colormap to derive the color
  146. used to draw the thumb.
  147. .Hw
  148. .Ib
  149. .IP \fBjumpProc\fP 1.5i
  150. All functions on this callback list are called when the
  151. \fBNotifyThumb\fP action is invoked.  See the \fBScrollbar
  152. Actions\fP section for details.
  153. .IP \fBlength\fP 1.5i
  154. The height of a vertical scrollbar or the width of a horizontal scrollbar.
  155. .Mm
  156. .IP \fBminimumThumb\fP 1.5i
  157. The smallest size, in pixels, to which the thumb can shrink.
  158. .IP \fBorientation\fP 1.5i
  159. The orientation is the direction that the thumb will be allowed to move.
  160. This value can be either \fBXtorientVertical\fP or
  161. \fBXtorientHorizontal\fP.
  162. .IN "XtorientVertical" ""
  163. .IN "XtorientHorizontal" ""
  164. .IN "conversions" "Orientation"
  165. .Rs "vertical \fPand\fB horizontal"
  166. .Pf
  167. .Pb
  168. .Sc
  169. .IP \fBscrollDCursor\fP 1.5i
  170. This cursor is used when scrolling backward in a vertical scrollbar.
  171. .IP \fBscrollHCursor\fP 1.5i
  172. This cursor is used when a horizontal scrollbar is inactive.
  173. .IP \fBscrollLCursor\fP 1.5i
  174. This cursor is used when scrolling forward in a horizontal scrollbar.
  175. .IP \fBscrollProc\fP 1.5i
  176. All functions on this callback list may be called when the
  177. \fBNotifyScroll\fP action is invoked.  See the \fBScrollbar
  178. Actions\fP section for details.
  179. .IP \fBscrollRCursor\fP 1.5i
  180. This cursor is used when scrolling backward in a horizontal scrollbar,
  181. or when thumbing a vertical scrollbar.
  182. .IP \fBscrollUCursor\fP 1.5i
  183. This cursor is used when scrolling forward in a vertical scrollbar, or when
  184. thumbing a horizontal scrollbar.
  185. .IP \fBscrollVCursor\fP 1.5i
  186. This cursor is used when a vertical scrollbar is inactive.
  187. .Se
  188. .IP \fBshown\fP 1.5i
  189. This is the size of the thumb, expressed as a percentage (0.0 - 1.0)
  190. of the length of the scrollbar. 
  191. .IP \fBthickness\fP 1.5i
  192. The width of a vertical scrollbar or the height of a horizontal scrollbar.
  193. .IP \fBthumb\fP 1.5i
  194. This pixmap is used to tile (or stipple) the thumb of the scrollbar.  If
  195. no tiling is desired, then set this resource to \fBNone\fP.  This
  196. resource will accept either a bitmap or a pixmap that is the same depth
  197. as the window.  The resource converter for this resource constructs
  198. bitmaps from the contents of files.  (See \fBConverting Bitmaps\fP for
  199. details.)
  200. .IP \fBtopOfThumb\fP 1.5i
  201. The location of the top of the thumb, as a percentage (0.0 - 1.0)
  202. of the length of the scrollbar.  This resource was called \fBtop\fP in 
  203. previous versions of the Athena widget set.  The name collided with the
  204. a Form widget constraint resource, and had to be changed.
  205. .Tr
  206. .Xy
  207. .NH 3 
  208. Scrollbar Actions
  209. .IN "Scrollbar widget" "actions"
  210. .LP
  211. The actions supported by the Scrollbar widget are:
  212. .IP \fBStartScroll\fP(\fIvalue\fP) 1.5i
  213. The possible \fIvalues\fP are Forward, Backward, or Continuous.
  214. This must be the first action to begin a new movement.
  215. .IP \fBNotifyScroll\fP(\fIvalue\fP) 1.5i
  216. The possible \fIvalues\fP are Proportional or FullLength.  If the
  217. argument to StartScroll was Forward or Backward, NotifyScroll executes
  218. the \fBscrollProc\fP callbacks and passes either; the position of the
  219. pointer, if \fIvalue\fP is Proportional, or the full length of the
  220. scroll bar, if \fIvalue\fP is FullLength.  If the argument to
  221. StartScroll was Continuous, NotifyScroll returns without executing any
  222. callbacks.
  223. .IP \fBEndScroll\fP(\^) 1.5i
  224. This must be the last action after a movement is complete.
  225. .IP \fBMoveThumb\fP(\^) 1.5i
  226. Repositions the Scrollbar's thumb to the current pointer location.
  227. .IP \fBNotifyThumb\fP(\^)\ \ \  1.5i
  228. Calls the
  229. .PN jumpProc
  230. callbacks and passes the relative position of the
  231. pointer as a percentage of the scroll bar length.
  232. .LP
  233. .sp
  234. The default bindings for Scrollbar are:
  235. .IN "Scrollbar widget" "default translation table"
  236. .LP
  237. .Ds 0
  238. .TA .5i 1.75i
  239. .ta .5i 1.75i
  240.     <Btn1Down>:    StartScroll(Forward)
  241.     <Btn2Down>:    StartScroll(Continuous) MoveThumb(\|) NotifyThumb(\|)
  242.     <Btn3Down>:    StartScroll(Backward)
  243.     <Btn2Motion>:    MoveThumb(\|) NotifyThumb(\|)
  244.     <BtnUp>:    NotifyScroll(Proportional) EndScroll(\|)
  245. .De
  246. .LP
  247. .sp
  248. Examples of additional bindings a user might wish to specify in a
  249. resource file are:
  250. .LP
  251. .Ds 0
  252. .TA .5i 2.25i
  253. .ta .5i 2.25i
  254. *Scrollbar.Translations: \\
  255.     ~Meta<Key>space:    StartScroll(Forward) NotifyScroll(FullLength) \\n\\
  256.      Meta<Key>space:    StartScroll(Backward) NotifyScroll(FullLength) \\n\\
  257.         EndScroll(\|)
  258. .De
  259. .NH 3
  260. Scrollbar Callbacks
  261. .IN "Scrollbar widget" "callbacks"
  262. .LP
  263. There are two callback lists provided by the Scrollbar widget.
  264. The procedural interface for these functions is described here.
  265. .LP
  266. The calling interface to the \fBscrollProc\fP callback procedure is:
  267. .IN "ScrollProc" "" "@DEF@"
  268. .FD 0
  269. void ScrollProc(\fIscrollbar\fP, \fIclient_data\fP, \fIposition\fP)
  270. .br
  271.      Widget \fIscrollbar\fP;
  272. .br
  273.      XtPointer \fIclient_data\fP;
  274. .br
  275.      XtPointer \fIposition\fP;    /* int */
  276. .FN
  277. .IP \fIscrollbar\fP 1i
  278. Specifies the Scrollbar widget.
  279. .IP \fIclient_data\fP 1i
  280. Specifies the client data.
  281. .IP \fIposition\fP 1i
  282. Specifies a pixel position in integer form.
  283. .LP
  284. The \fBscrollProc\fP callback is used for incremental scrolling 
  285. and is called by the \fBNotifyScroll\fP action.
  286. The position argument is a signed quantity and should be cast to an int
  287. when used. Using the default button bindings, button 1 returns a
  288. positive value, and button 3 returns a negative value. In both cases,
  289. the magnitude of the value is the distance of the pointer in
  290. pixels from the top (or left) of the Scrollbar. The value will never
  291. be greater than the length of the Scrollbar. 
  292. .LP
  293. .sp
  294. The calling interface to the \fBjumpProc\fP callback procedure is:
  295. .IN "jumpProc" "" "@DEF@"
  296. .FD 0
  297. void JumpProc(\fIscrollbar\fP, \fIclient_data\fP, \fIpercent\fP)
  298. .br
  299.      Widget \fIscrollbar\fP;
  300. .br
  301.      XtPointer \fIclient_data\fP;
  302. .br
  303.      XtPointer \fIpercent_ptr\fP;    /* float* */
  304. .FN
  305. .IP \fIscrollbar\fP 1i
  306. Specifies the ID of the scroll bar widget.
  307. .IP \fIclient_data\fP 1i
  308. Specifies the client data.
  309. .IP \fIpercent_ptr\fP 1i
  310. Specifies the floating point position of the thumb (0.0 \- 1.0).
  311. .LP
  312. The \fBjumpProc\fP callback is used to implement smooth scrolling and
  313. is called by the \fBNotifyThumb\fP action.  Percent_ptr must be cast
  314. to a pointer to float before use; i.e.
  315. .LP
  316. .Ds 0
  317. .TA .5i
  318. .ta .5i
  319.     float percent = *(float*)percent_ptr;
  320. .De
  321. .LP
  322. With the default button bindings, button 2 moves the thumb interactively,
  323. and the \fBjumpProc\fP is called on each new position of the pointer,
  324. while the pointer button remains down.  The value specified by
  325. \fIpercent_ptr\fP is the current location of the thumb (from the top or
  326. left of the Scrollbar) expressed as a percentage of the length of the
  327. Scrollbar.
  328. .NH 3
  329. Convenience Routines
  330. .LP
  331. .IN "Scrollbar widget" "setting thumb values"
  332. To set the position and length of a Scrollbar thumb, use 
  333. .PN XawScrollbarSetThumb .
  334. .IN "XawScrollbarSetThumb" "" "@DEF@"
  335. .FD 0
  336. void XawScrollbarSetThumb(\fIw\fP, \fItop\fP, \fIshown\fP)
  337. .br
  338.      Widget \fIw\fP;
  339. .br
  340.      float \fItop\fP;
  341. .br
  342.      float \fIshown\fP;
  343. .FN
  344. .IP \fIw\fP 1i
  345. Specifies the Scrollbar widget.
  346. .IP \fItop\fP 1i
  347. Specifies the position of the top of the thumb as a fraction of the
  348. length of the Scrollbar.
  349. .IP \fIshown\fP 1i
  350. Specifies the length of the thumb as a fraction of the total length
  351. of the Scrollbar.
  352. .LP
  353. .PN XawScrollbarThumb
  354. moves the visible thumb to a new position (0.0 \- 1.0) and length (0.0 \- 1.0).
  355. Either the top or shown arguments can be specified as \-1.0,
  356. in which case the current value is left unchanged.
  357. Values greater than 1.0 are truncated to 1.0.
  358. .LP
  359. If called from \fBjumpProc\fP, \fBXawScrollbarSetThumb\fP has no effect.
  360. .NH 3
  361. Setting Float Resources
  362. .IN "float resources" "setting"
  363. .LP
  364. The \fBshown\fP and \fBtopOfThumb\fP resources are of type
  365. \fIfloat\fP.  These resources can be difficult to get into an
  366. argument list.  The reason is that C performs an automatic cast of
  367. the float value to an integer value, usually truncating the important
  368. information.  The following code fragment is one portable method of
  369. getting a float into an argument list.
  370. .sp
  371. .ps 9
  372. .nr PS 9
  373. .Ds 0
  374. .TA 1i 2i
  375. .ta 1i 2i
  376.     top = 0.5;
  377.     if (sizeof(float) > sizeof(XtArgVal)) {
  378.     /*
  379.     \ * If a float is larger than an XtArgVal then pass this 
  380.     \ * resource value by reference.
  381.     \ */
  382.         XtSetArg(args[0], XtNshown, &top);
  383.     }
  384.     else {
  385.     /*
  386.     \ * Convince C not to perform an automatic conversion, which
  387.     \ * would truncate 0.5 to 0. 
  388.     \ */
  389.         XtArgVal * l_top = (XtArgVal *) ⊤
  390.         XtSetArg(args[0], XtNshown, *l_top);
  391.     }
  392. .De
  393. .ps 11
  394. .nr PS 11
  395. .sp
  396.