specs/Scrollbar.xml

   1 <sect1 id="Scrollbar_Widget">
   2 <title>Scrollbar Widget</title>
   3
   4 <literallayout class="monospaced">
   5 Application header file     &lt;X11/Xaw/Scrollbar.h&gt;
   6 Class header file           &lt;X11/Xaw/ScrollbarP.h&gt;
   7 Class                       scrollbarWidgetClass
   8 Class Name                  Scrollbar
   9 Superclass                  Simple
  10 </literallayout>
  11
  12 <para>
  13 A Scrollbar widget is a rectangle, called the ``canvas,'' on
  14 which another rectangle, the ``thumb,'' moves in one
  15 dimension, either vertically or horizontally.  A Scrollbar
  16 can be used alone, as a value generator, or it can be used
  17 within a composite widget (for example, a Viewport).  When a
  18 Scrollbar is used to move, or ``scroll,'' the contents of
  19 another widget, the size and the position of the thumb usually give
  20 feedback as to what portion of the other widget's contents
  21 are visible.
  22 </para>
  23
  24 <para>
  25 Each pointer button invokes a specific action.  Pointer
  26 buttons 1 and 3 do not move the thumb automatically.
  27 Instead, they return the pixel position of the cursor on the
  28 scroll region.  When pointer button 2 is clicked, the thumb
  29 moves to the current pointer position.  When pointer button
  30 2 is held down and the pointer is moved, the thumb follows
  31 the pointer.
  32 </para>
  33
  34 <para>
  35 The pointer cursor in the scroll region changes depending on the current
  36 action.  When no pointer button is pressed, the cursor appears as a
  37 double-headed arrow that points in the direction that scrolling can
  38 occur.  When pointer button 1 or 3 is pressed, the cursor appears as a
  39 single-headed arrow that points in the logical direction that the thumb
  40 will move.  When pointer button 2 is pressed, the cursor
  41 appears as an arrow that points to the top or the left of the thumb.
  42 </para>
  43
  44 <para>
  45 When the user scrolls, the application receives notification
  46 through callback procedures.  For both discrete scrolling actions, the
  47 callback returns the Scrollbar widget, the client_data, and the pixel
  48 position of the pointer when the button was released.  For continuous
  49 scrolling, the callback routine returns the scroll bar widget, the
  50 client data, and the current relative position of the thumb.  When the
  51 thumb is moved using pointer button 2, the callback procedure is invoked
  52 continuously.  When either button 1 or 3 is pressed, the callback
  53 procedure is invoked only when the button is released and the client
  54 callback procedure is responsible for moving the thumb.
  55 </para>
  56
  57 <sect2 id="scrollbar_resources">
  58 <title>Resources</title>
  59
  60 <para>
  61 When creating a Scrollbar widget instance, the following resources are
  62 retrieved from the argument list or from the resource database:
  63 </para>
  64
  65 <informaltable>
  66   <tgroup cols='5' align='center'>
  67   <colspec colname='c1'/>
  68   <colspec colname='c2'/>
  69   <colspec colname='c3'/>
  70   <colspec colname='c4'/>
  71   <colspec colname='c5'/>
  72   <thead>
  73     <row>
  74       <entry>Name</entry>
  75       <entry>Class</entry>
  76       <entry>Type</entry>
  77       <entry>Notes</entry>
  78       <entry>Default Value</entry>
  79     </row>
  80   </thead>
  81   <tbody>
  82     <row>
  83       <entry>accelerators</entry>
  84       <entry>Accelerators</entry>
  85       <entry>AcceleratorTable</entry>
  86       <entry></entry>
  87       <entry>NULL</entry>
  88     </row>
  89     <row>
  90       <entry>ancestorSensitive</entry>
  91       <entry>AncestorSensitive</entry>
  92       <entry>Boolean</entry>
  93       <entry>D</entry>
  94       <entry>True</entry>
  95     </row>
  96     <row>
  97       <entry>background</entry>
  98       <entry>Background</entry>
  99       <entry>Pixel</entry>
 100       <entry></entry>
 101       <entry>XtDefaultBackground</entry>
 102     </row>
 103     <row>
 104       <entry>backgroundPixmap</entry>
 105       <entry>Pixmap</entry>
 106       <entry>Pixmap</entry>
 107       <entry></entry>
 108       <entry>XtUnspecifiedPixmap</entry>
 109     </row>
 110     <row>
 111       <entry>borderColor</entry>
 112       <entry>BorderColor</entry>
 113       <entry>Pixel</entry>
 114       <entry></entry>
 115       <entry>XtDefaultForeground</entry>
 116     </row>
 117     <row>
 118       <entry>borderPixmap</entry>
 119       <entry>Pixmap</entry>
 120       <entry>Pixmap</entry>
 121       <entry></entry>
 122       <entry>XtUnspecifiedPixmap</entry>
 123     </row>
 124     <row>
 125       <entry>borderWidth</entry>
 126       <entry>BorderWidth</entry>
 127       <entry>Dimension</entry>
 128       <entry></entry>
 129       <entry>1</entry>
 130     </row>
 131     <row>
 132       <entry>colormap</entry>
 133       <entry>Colormap</entry>
 134       <entry>Colormap</entry>
 135       <entry></entry>
 136       <entry>parent's Colormap</entry>
 137     </row>
 138     <row>
 139       <entry>cursor</entry>
 140       <entry>Cursor</entry>
 141       <entry>Cursor</entry>
 142       <entry></entry>
 143       <entry>None</entry>
 144     </row>
 145     <row>
 146       <entry>cursorName</entry>
 147       <entry>Cursor</entry>
 148       <entry>String</entry>
 149       <entry></entry>
 150       <entry>NULL</entry>
 151     </row>
 152     <row>
 153       <entry>depth</entry>
 154       <entry>Depth</entry>
 155       <entry>int</entry>
 156       <entry>C</entry>
 157       <entry>parent's Depth</entry>
 158     </row>
 159     <row>
 160       <entry>destroyCallback</entry>
 161       <entry>Callback</entry>
 162       <entry>XtCallbackList</entry>
 163       <entry></entry>
 164       <entry>NULL</entry>
 165     </row>
 166     <row>
 167       <entry>foreground</entry>
 168       <entry>Foreground</entry>
 169       <entry>Pixel</entry>
 170       <entry></entry>
 171       <entry>XtDefaultForeground</entry>
 172     </row>
 173     <row>
 174       <entry>height</entry>
 175       <entry>Height</entry>
 176       <entry>Dimension</entry>
 177       <entry>A</entry>
 178       <entry>depends on orientation</entry>
 179     </row>
 180     <row>
 181       <entry>insensitiveBorder</entry>
 182       <entry>Insensitive</entry>
 183       <entry>Pixmap</entry>
 184       <entry></entry>
 185       <entry>GreyPixmap</entry>
 186     </row>
 187     <row>
 188       <entry>international</entry>
 189       <entry>International</entry>
 190       <entry>Boolean</entry>
 191       <entry>C</entry>
 192       <entry>False</entry>
 193     </row>
 194     <row>
 195       <entry>jumpProc</entry>
 196       <entry>Callback</entry>
 197       <entry>XtCallbackList</entry>
 198       <entry></entry>
 199       <entry>NULL</entry>
 200     </row>
 201     <row>
 202       <entry>length</entry>
 203       <entry>Length</entry>
 204       <entry>Dimension</entry>
 205       <entry></entry>
 206       <entry>1</entry>
 207     </row>
 208     <row>
 209       <entry>mappedWhenManaged</entry>
 210       <entry>MappedWhenManaged</entry>
 211       <entry>Boolean</entry>
 212       <entry></entry>
 213       <entry>True</entry>
 214     </row>
 215     <row>
 216       <entry>minimumThumb</entry>
 217       <entry>MinimumThumb</entry>
 218       <entry>Dimension</entry>
 219       <entry></entry>
 220       <entry>7</entry>
 221     </row>
 222     <row>
 223       <entry>orientation</entry>
 224       <entry>Orientation</entry>
 225       <entry>Orientation</entry>
 226       <entry></entry>
 227       <entry>XtorientVertical (vertical)</entry>
 228     </row>
 229     <row>
 230       <entry>pointerColor</entry>
 231       <entry>Foreground</entry>
 232       <entry>Pixel</entry>
 233       <entry></entry>
 234       <entry>XtDefaultForeground</entry>
 235     </row>
 236     <row>
 237       <entry>pointerColorBackground</entry>
 238       <entry>Background</entry>
 239       <entry>Pixel</entry>
 240       <entry></entry>
 241       <entry>XtDefaultBackground</entry>
 242     </row>
 243     <row>
 244       <entry>screen</entry>
 245       <entry>Screen</entry>
 246       <entry>Screen</entry>
 247       <entry>R</entry>
 248       <entry>parent's Screen</entry>
 249     </row>
 250     <row>
 251       <entry>scrollDCursor</entry>
 252       <entry>Cursor</entry>
 253       <entry>Cursor</entry>
 254       <entry></entry>
 255       <entry>XC_sb_down_arrow</entry>
 256     </row>
 257     <row>
 258       <entry>scrollHCursor</entry>
 259       <entry>Cursor</entry>
 260       <entry>Cursor</entry>
 261       <entry></entry>
 262       <entry>XC_sb_h_double_arrow</entry>
 263     </row>
 264     <row>
 265       <entry>scrollLCursor</entry>
 266       <entry>Cursor</entry>
 267       <entry>Cursor</entry>
 268       <entry></entry>
 269       <entry>XC_sb_left_arrow</entry>
 270     </row>
 271     <row>
 272       <entry>scrollProc</entry>
 273       <entry>Callback</entry>
 274       <entry>XtCallbackList</entry>
 275       <entry></entry>
 276       <entry>NULL</entry>
 277     </row>
 278     <row>
 279       <entry>scrollRCursor</entry>
 280       <entry>Cursor</entry>
 281       <entry>Cursor</entry>
 282       <entry></entry>
 283       <entry>XC_sb_right_arrow</entry>
 284     </row>
 285     <row>
 286       <entry>scrollUCursor</entry>
 287       <entry>Cursor</entry>
 288       <entry>Cursor</entry>
 289       <entry></entry>
 290       <entry>XC_sb_up_arrow</entry>
 291     </row>
 292     <row>
 293       <entry>scrollVCursor</entry>
 294       <entry>Cursor</entry>
 295       <entry>Cursor</entry>
 296       <entry></entry>
 297       <entry>XC_sb_v_arrow</entry>
 298     </row>
 299     <row>
 300       <entry>sensitive</entry>
 301       <entry>Sensitive</entry>
 302       <entry>Boolean</entry>
 303       <entry></entry>
 304       <entry>True</entry>
 305     </row>
 306     <row>
 307       <entry>shown</entry>
 308       <entry>Shown</entry>
 309       <entry>Float</entry>
 310       <entry></entry>
 311       <entry>0.0</entry>
 312     </row>
 313     <row>
 314       <entry>thickness</entry>
 315       <entry>Thickness</entry>
 316       <entry>Dimension</entry>
 317       <entry></entry>
 318       <entry>14</entry>
 319     </row>
 320     <row>
 321       <entry>thumb</entry>
 322       <entry>Thumb</entry>
 323       <entry>Bitmap</entry>
 324       <entry></entry>
 325       <entry>GreyPixmap</entry>
 326     </row>
 327     <row>
 328       <entry>thumbProc</entry>
 329       <entry>Callback</entry>
 330       <entry>XtCallbackList</entry>
 331       <entry></entry>
 332       <entry>NULL</entry>
 333     </row>
 334     <row>
 335       <entry>topOfThumb</entry>
 336       <entry>TopOfThumb</entry>
 337       <entry>Float</entry>
 338       <entry></entry>
 339       <entry>0.0</entry>
 340     </row>
 341     <row>
 342       <entry>translations</entry>
 343       <entry>Translations</entry>
 344       <entry>TranslationTable</entry>
 345       <entry></entry>
 346       <entry>See below</entry>
 347     </row>
 348     <row>
 349       <entry>width</entry>
 350       <entry>Width</entry>
 351       <entry>Dimension</entry>
 352       <entry>A</entry>
 353       <entry>depends on orientation</entry>
 354     </row>
 355     <row>
 356       <entry>x</entry>
 357       <entry>Position</entry>
 358       <entry>Position</entry>
 359       <entry></entry>
 360       <entry>0</entry>
 361     </row>
 362     <row>
 363       <entry>y</entry>
 364       <entry>Position</entry>
 365       <entry>Position</entry>
 366       <entry></entry>
 367       <entry>0</entry>
 368     </row>
 369   </tbody>
 370   </tgroup>
 371 </informaltable>
 372
 373 <variablelist>
 374   <varlistentry>
 375     <term>
 376       <function>foreground</function>
 377     </term>
 378     <listitem>
 379       <para>
 380 A pixel value which indexes the widget's colormap to derive the color
 381 used to draw the thumb.
 382       </para>
 383     </listitem>
 384   </varlistentry>
 385   <varlistentry>
 386     <term>
 387       <function>jumpProc</function>
 388     </term>
 389     <listitem>
 390       <para>
 391 All functions on this callback list are called when the
 392 <function>NotifyThumb</function> action is invoked.  See the <function>Scrollbar
 393 Actions</function> section for details.
 394       </para>
 395     </listitem>
 396   </varlistentry>
 397   <varlistentry>
 398     <term>
 399       <function>length</function>
 400     </term>
 401     <listitem>
 402       <para>
 403 The height of a vertical scrollbar or the width of a horizontal scrollbar.
 404       </para>
 405     </listitem>
 406   </varlistentry>
 407   <varlistentry>
 408     <term>
 409       <function>minimumThumb</function>
 410     </term>
 411     <listitem>
 412       <para>
 413 The smallest size, in pixels, to which the thumb can shrink.
 414       </para>
 415     </listitem>
 416   </varlistentry>
 417   <varlistentry>
 418     <term>
 419       <function>orientation</function>
 420     </term>
 421     <listitem>
 422       <para>
 423 The orientation is the direction that the thumb will be allowed to move.
 424 This value can be either <function>XtorientVertical</function> or
 425 <function>XtorientHorizontal</function>.
 426       </para>
 427     </listitem>
 428   </varlistentry>
 429   <varlistentry>
 430     <term>
 431       <function>scrollDCursor</function>
 432     </term>
 433     <listitem>
 434       <para>
 435 This cursor is used when scrolling backward in a vertical scrollbar.
 436       </para>
 437     </listitem>
 438   </varlistentry>
 439   <varlistentry>
 440     <term>
 441       <function>scrollHCursor</function>
 442     </term>
 443     <listitem>
 444       <para>
 445 This cursor is used when a horizontal scrollbar is inactive.
 446       </para>
 447     </listitem>
 448   </varlistentry>
 449   <varlistentry>
 450     <term>
 451       <function>scrollLCursor</function>
 452     </term>
 453     <listitem>
 454       <para>
 455 This cursor is used when scrolling forward in a horizontal scrollbar.
 456       </para>
 457     </listitem>
 458   </varlistentry>
 459   <varlistentry>
 460     <term>
 461       <function>scrollProc</function>
 462     </term>
 463     <listitem>
 464       <para>
 465 All functions on this callback list may be called when the
 466 <function>NotifyScroll</function> action is invoked.  See the \fBScrollbar
 467 Actions\fP section for details.
 468       </para>
 469     </listitem>
 470   </varlistentry>
 471   <varlistentry>
 472     <term>
 473       <function>scrollRCursor</function>
 474     </term>
 475     <listitem>
 476       <para>
 477 This cursor is used when scrolling backward in a horizontal scrollbar,
 478 or when thumbing a vertical scrollbar.
 479       </para>
 480     </listitem>
 481   </varlistentry>
 482   <varlistentry>
 483     <term>
 484       <function>scrollUCursor</function>
 485     </term>
 486     <listitem>
 487       <para>
 488 This cursor is used when scrolling forward in a vertical scrollbar, or when
 489 thumbing a horizontal scrollbar.
 490       </para>
 491     </listitem>
 492   </varlistentry>
 493   <varlistentry>
 494     <term>
 495       <function>scrollVCursor</function>
 496     </term>
 497     <listitem>
 498       <para>
 499 This cursor is used when a vertical scrollbar is inactive.
 500 <!-- .Se -->
 501       </para>
 502     </listitem>
 503   </varlistentry>
 504   <varlistentry>
 505     <term>
 506       <function>shown</function>
 507     </term>
 508     <listitem>
 509       <para>
 510 This is the size of the thumb, expressed as a percentage (0.0 - 1.0)
 511 of the length of the scrollbar.
 512       </para>
 513     </listitem>
 514   </varlistentry>
 515   <varlistentry>
 516     <term>
 517       <function>thickness</function>
 518     </term>
 519     <listitem>
 520       <para>
 521 The width of a vertical scrollbar or the height of a horizontal scrollbar.
 522       </para>
 523     </listitem>
 524   </varlistentry>
 525   <varlistentry>
 526     <term>
 527       <function>thumb</function>
 528     </term>
 529     <listitem>
 530       <para>
 531 This pixmap is used to tile (or stipple) the thumb of the scrollbar.  If
 532 no tiling is desired, then set this resource to <function>None</function>.  This
 533 resource will accept either a bitmap or a pixmap that is the same depth
 534 as the window.  The resource converter for this resource constructs
 535 bitmaps from the contents of files.  (See <function>Converting Bitmaps</function> for
 536 details.)
 537       </para>
 538     </listitem>
 539   </varlistentry>
 540   <varlistentry>
 541     <term>
 542       <function>topOfThumb</function>
 543     </term>
 544     <listitem>
 545       <para>
 546 The location of the top of the thumb, as a percentage (0.0 - 1.0)
 547 of the length of the scrollbar.  This resource was called <function>top</function> in
 548 previous versions of the Athena widget set.  The name collided with the
 549 a Form widget constraint resource, and had to be changed.
 550     </para>
 551   </listitem>
 552   </varlistentry>
 553 </variablelist>
 554
 555 </sect2>
 556
 557 <sect2 id="Scrollbar_Actions">
 558 <title>Scrollbar Actions</title>
 559 <para>
 560 <!-- .LP -->
 561 The actions supported by the Scrollbar widget are:
 562 </para>
 563 <variablelist>
 564   <varlistentry>
 565     <term>
 566       <function>StartScroll</function>(<emphasis remap='I'>value</emphasis>)
 567     </term>
 568     <listitem>
 569       <para>
 570 The possible <emphasis remap='I'>values</emphasis> are Forward, Backward, or Continuous.
 571 This must be the first action to begin a new movement.
 572       </para>
 573     </listitem>
 574   </varlistentry>
 575   <varlistentry>
 576     <term>
 577       <function>NotifyScroll</function>(<emphasis remap='I'>value</emphasis>)
 578     </term>
 579     <listitem>
 580       <para>
 581 The possible <emphasis remap='I'>values</emphasis> are Proportional or FullLength.  If the
 582 argument to StartScroll was Forward or Backward, NotifyScroll executes
 583 the <function>scrollProc</function> callbacks and passes either; the position of the
 584 pointer, if <emphasis remap='I'>value</emphasis> is Proportional, or the full length of the
 585 scroll bar, if <emphasis remap='I'>value</emphasis> is FullLength.  If the argument to
 586 StartScroll was Continuous, NotifyScroll returns without executing any
 587 callbacks.
 588       </para>
 589     </listitem>
 590   </varlistentry>
 591   <varlistentry>
 592     <term>
 593       <function>EndScroll</function>(\^)
 594     </term>
 595     <listitem>
 596       <para>
 597 This must be the last action after a movement is complete.
 598       </para>
 599     </listitem>
 600   </varlistentry>
 601   <varlistentry>
 602     <term>
 603       <function>MoveThumb</function>(\^)
 604     </term>
 605     <listitem>
 606       <para>
 607 Repositions the Scrollbar's thumb to the current pointer location.
 608       </para>
 609     </listitem>
 610   </varlistentry>
 611   <varlistentry>
 612     <term>
 613       <function>NotifyThumb</function>(\^)\
 614     </term>
 615     <listitem>
 616       <para>
 617 Calls the
 618 <!-- .PN jumpProc -->
 619 callbacks and passes the relative position of the
 620 pointer as a percentage of the scroll bar length.
 621     </para>
 622   </listitem>
 623   </varlistentry>
 624 </variablelist>
 625 <para>
 626 The default bindings for Scrollbar are:
 627 <!-- .IN "Scrollbar widget" "default translation table" -->
 628 </para>
 629
 630 <literallayout class="monospaced">
 631      &lt;Btn1Down&gt;:     StartScroll(Forward)
 632      &lt;Btn2Down&gt;:     StartScroll(Continuous) MoveThumb(\|) NotifyThumb(\|)
 633      &lt;Btn3Down&gt;:     StartScroll(Backward)
 634      &lt;Btn2Motion&gt;:     MoveThumb(\|) NotifyThumb(\|)
 635      &lt;BtnUp&gt;:     NotifyScroll(Proportional) EndScroll(\|)
 636 </literallayout>
 637
 638 <para>
 639 Examples of additional bindings a user might wish to specify in a
 640 resource file are:
 641 </para>
 642
 643 <literallayout class="monospaced">
 644 *Scrollbar.Translations: \\
 645      ~Meta&lt;Key&gt;space:     StartScroll(Forward) NotifyScroll(FullLength) \\n\\
 646       Meta&lt;Key&gt;space:     StartScroll(Backward) NotifyScroll(FullLength) \\n\\
 647           EndScroll(\|)
 648 </literallayout>
 649
 650 </sect2>
 651
 652 <sect2 id="Scrollbar_Callbacks">
 653 <title>Scrollbar Callbacks</title>
 654 <!-- .IN "Scrollbar widget" "callbacks" -->
 655 <para>
 656 <!-- .LP -->
 657 There are two callback lists provided by the Scrollbar widget.
 658 The procedural interface for these functions is described here.
 659 </para>
 660
 661 <para>
 662 <!-- .LP -->
 663 The calling interface to the <function>scrollProc</function> callback procedure is:
 664 <!-- .IN "ScrollProc" "" "@DEF@" -->
 665 </para>
 666 <funcsynopsis>
 667 <funcprototype>
 668   <funcdef>void<function> ScrollProc</function></funcdef>
 669   <paramdef>Widget<parameter> scrollbar</parameter></paramdef>
 670   <paramdef>XtPointer<parameter> client_data</parameter></paramdef>
 671   <paramdef>XtPointer<parameter> position</parameter></paramdef>
 672 </funcprototype>
 673 </funcsynopsis>
 674
 675 <variablelist>
 676   <varlistentry>
 677     <term>
 678       <emphasis remap='I'>scrollbar</emphasis>
 679     </term>
 680     <listitem>
 681       <para>
 682 Specifies the Scrollbar widget.
 683       </para>
 684     </listitem>
 685   </varlistentry>
 686   <varlistentry>
 687     <term>
 688       <emphasis remap='I'>client_data</emphasis>
 689     </term>
 690     <listitem>
 691       <para>
 692 Specifies the client data.
 693       </para>
 694     </listitem>
 695   </varlistentry>
 696   <varlistentry>
 697     <term>
 698       <emphasis remap='I'>position</emphasis>
 699     </term>
 700     <listitem>
 701       <para>
 702 Specifies a pixel position in integer form.
 703     </para>
 704   </listitem>
 705   </varlistentry>
 706 </variablelist>
 707
 708 <para>
 709 The <function>scrollProc</function> callback is used for incremental scrolling
 710 and is called by the <function>NotifyScroll</function> action.
 711 The position argument is a signed quantity and should be cast to an int
 712 when used. Using the default button bindings, button 1 returns a
 713 positive value, and button 3 returns a negative value. In both cases,
 714 the magnitude of the value is the distance of the pointer in
 715 pixels from the top (or left) of the Scrollbar. The value will never
 716 be greater than the length of the Scrollbar.
 717 </para>
 718
 719 <para>
 720 The calling interface to the <function>jumpProc</function> callback procedure is:
 721 </para>
 722 <!-- .IN "jumpProc" "" "@DEF@" -->
 723 <funcsynopsis>
 724 <funcprototype>
 725   <funcdef>void<function> JumpProc</function></funcdef>
 726   <paramdef>Widget<parameter> scrollbar</parameter></paramdef>
 727   <paramdef>XtPointer<parameter> client_data</parameter></paramdef>
 728   <paramdef>XtPointer<parameter> percent_ptr</parameter></paramdef>
 729 </funcprototype>
 730 </funcsynopsis>
 731
 732 <!-- .FN -->
 733 <variablelist>
 734   <varlistentry>
 735     <term>
 736       <emphasis remap='I'>scrollbar</emphasis>
 737     </term>
 738     <listitem>
 739       <para>
 740 Specifies the ID of the scroll bar widget.
 741       </para>
 742     </listitem>
 743   </varlistentry>
 744   <varlistentry>
 745     <term>
 746       <emphasis remap='I'>client_data</emphasis>
 747     </term>
 748     <listitem>
 749       <para>
 750 Specifies the client data.
 751       </para>
 752     </listitem>
 753   </varlistentry>
 754   <varlistentry>
 755     <term>
 756       <emphasis remap='I'>percent_ptr</emphasis>
 757     </term>
 758     <listitem>
 759       <para>
 760 Specifies the floating point position of the thumb (0.0 \- 1.0).
 761     </para>
 762   </listitem>
 763   </varlistentry>
 764 </variablelist>
 765
 766 <para>
 767 The <function>jumpProc</function> callback is used to implement smooth scrolling and
 768 is called by the <function>NotifyThumb</function> action.  Percent_ptr must be cast
 769 to a pointer to float before use; i.e.
 770 </para>
 771
 772 <literallayout class="monospaced">
 773      float percent = *(float*)percent_ptr;
 774 </literallayout>
 775
 776 <para>
 777 With the default button bindings, button 2 moves the thumb interactively,
 778 and the <function>jumpProc</function> is called on each new position of the pointer,
 779 while the pointer button remains down.  The value specified by
 780 <emphasis remap='I'>percent_ptr</emphasis> is the current location of the thumb (from the top or
 781 left of the Scrollbar) expressed as a percentage of the length of the
 782 Scrollbar.
 783 </para>
 784
 785 </sect2>
 786
 787 <sect2 id="Convenience_Routines">
 788 <title>Convenience Routines</title>
 789 <para>
 790 <!-- .IN "Scrollbar widget" "setting thumb values" -->
 791 To set the position and length of a Scrollbar thumb, use
 792 <!-- .PN XawScrollbarSetThumb . -->
 793 <!-- .IN "XawScrollbarSetThumb" "" "@DEF@" -->
 794 </para>
 795 <funcsynopsis>
 796 <funcprototype>
 797   <funcdef>void<function> XawScrollbarSetThumb</function></funcdef>
 798   <paramdef>Widget<parameter> w</parameter></paramdef>
 799   <paramdef>float<parameter> top</parameter></paramdef>
 800   <paramdef>float<parameter> shown</parameter></paramdef>
 801 </funcprototype>
 802 </funcsynopsis>
 803
 804 <variablelist>
 805   <varlistentry>
 806     <term>
 807       <emphasis remap='I'>w</emphasis>
 808     </term>
 809     <listitem>
 810       <para>
 811 Specifies the Scrollbar widget.
 812       </para>
 813     </listitem>
 814   </varlistentry>
 815   <varlistentry>
 816     <term>
 817       <emphasis remap='I'>top</emphasis>
 818     </term>
 819     <listitem>
 820       <para>
 821 Specifies the position of the top of the thumb as a fraction of the
 822 length of the Scrollbar.
 823       </para>
 824     </listitem>
 825   </varlistentry>
 826   <varlistentry>
 827     <term>
 828       <emphasis remap='I'>shown</emphasis>
 829     </term>
 830     <listitem>
 831       <para>
 832 Specifies the length of the thumb as a fraction of the total length
 833 of the Scrollbar.
 834     </para>
 835   </listitem>
 836   </varlistentry>
 837 </variablelist>
 838
 839 <para>
 840 <function>XawScrollbarThumb</function>
 841 moves the visible thumb to a new position (0.0 \- 1.0) and length (0.0 \- 1.0).
 842 Either the top or shown arguments can be specified as \-1.0,
 843 in which case the current value is left unchanged.
 844 Values greater than 1.0 are truncated to 1.0.
 845 </para>
 846
 847 <para>
 848 If called from <function>jumpProc</function>, <function>XawScrollbarSetThumb</function> has no effect.
 849 </para>
 850
 851 </sect2>
 852
 853 <sect2 id="Setting_Float_Resources">
 854 <title>Setting Float Resources</title>
 855 <!-- .IN "float resources" "setting" -->
 856 <para>
 857 The <function>shown</function> and <function>topOfThumb</function> resources are of type
 858 <emphasis remap='I'>float</emphasis>.  These resources can be difficult to get into an
 859 argument list.  The reason is that C performs an automatic cast of
 860 the float value to an integer value, usually truncating the important
 861 information.  The following code fragment is one portable method of
 862 getting a float into an argument list.
 863 </para>
 864 <literallayout class="monospaced">
 865      top = 0.5;
 866      if (sizeof(float) &gt; sizeof(XtArgVal)) {
 867      /*
 868      \ * If a float is larger than an XtArgVal then pass this
 869      \ * resource value by reference.
 870      \ */
 871           XtSetArg(args[0], XtNshown, &amp;top);
 872      }
 873      else {
 874      /*
 875      \ * Convince C not to perform an automatic conversion, which
 876      \ * would truncate 0.5 to 0.
 877      \ */
 878           XtArgVal * l_top = (XtArgVal *) &amp;top;
 879           XtSetArg(args[0], XtNshown, *l_top);
 880      }
 881 </literallayout>
 882
 883 </sect2>
 884 </sect1>