1<sect1 id="Scrollbar_Widget"> 2<title>Scrollbar Widget</title> 3 4<literallayout class="monospaced"> 5Application header file <X11/Xaw/Scrollbar.h> 6Class header file <X11/Xaw/ScrollbarP.h> 7Class scrollbarWidgetClass 8Class Name Scrollbar 9Superclass Simple 10</literallayout> 11 12<para> 13A Scrollbar widget is a rectangle, called the <quote>canvas,</quote> on 14which another rectangle, the <quote>thumb,</quote> moves in one 15dimension, either vertically or horizontally. A Scrollbar 16can be used alone, as a value generator, or it can be used 17within a composite widget (for example, a Viewport). When a 18Scrollbar is used to move, or <quote>scroll,</quote> the contents of 19another widget, the size and the position of the thumb usually give 20feedback as to what portion of the other widget's contents 21are visible. 22</para> 23 24<para> 25Each pointer button invokes a specific action. Pointer 26buttons 1 and 3 do not move the thumb automatically. 27Instead, they return the pixel position of the cursor on the 28scroll region. When pointer button 2 is clicked, the thumb 29moves to the current pointer position. When pointer button 302 is held down and the pointer is moved, the thumb follows 31the pointer. 32</para> 33 34<para> 35The pointer cursor in the scroll region changes depending on the current 36action. When no pointer button is pressed, the cursor appears as a 37double-headed arrow that points in the direction that scrolling can 38occur. When pointer button 1 or 3 is pressed, the cursor appears as a 39single-headed arrow that points in the logical direction that the thumb 40will move. When pointer button 2 is pressed, the cursor 41appears as an arrow that points to the top or the left of the thumb. 42</para> 43 44<para> 45When the user scrolls, the application receives notification 46through callback procedures. For both discrete scrolling actions, the 47callback returns the Scrollbar widget, the client_data, and the pixel 48position of the pointer when the button was released. For continuous 49scrolling, the callback routine returns the scroll bar widget, the 50client data, and the current relative position of the thumb. When the 51thumb is moved using pointer button 2, the callback procedure is invoked 52continuously. When either button 1 or 3 is pressed, the callback 53procedure is invoked only when the button is released and the client 54callback procedure is responsible for moving the thumb. 55</para> 56 57<sect2 id='Scrollbar::Resources'> 58<title>Resources</title> 59 60<para> 61When creating a Scrollbar widget instance, the following resources are 62retrieved 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> 380A pixel value which indexes the widget's colormap to derive the color 381used to draw the thumb. 382 </para> 383 </listitem> 384 </varlistentry> 385 <varlistentry> 386 <term> 387 <function>jumpProc</function> 388 </term> 389 <listitem> 390 <para> 391All functions on this callback list are called when the 392<function>NotifyThumb</function> action is invoked. See 393<xref linkend="Scrollbar_Actions" /> for details. 394 </para> 395 </listitem> 396 </varlistentry> 397 <varlistentry> 398 <term> 399 <function>length</function> 400 </term> 401 <listitem> 402 <para> 403The 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> 413The 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> 423The orientation is the direction that the thumb will be allowed to move. 424This 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> 435This 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> 445This 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> 455This 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> 465All functions on this callback list may be called when the 466<function>NotifyScroll</function> action is invoked. See 467<xref linkend="Scrollbar_Actions" /> for details. 468 </para> 469 </listitem> 470 </varlistentry> 471 <varlistentry> 472 <term> 473 <function>scrollRCursor</function> 474 </term> 475 <listitem> 476 <para> 477This cursor is used when scrolling backward in a horizontal scrollbar, 478or 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> 488This cursor is used when scrolling forward in a vertical scrollbar, or when 489thumbing a horizontal scrollbar. 490 </para> 491 </listitem> 492 </varlistentry> 493 <varlistentry> 494 <term> 495 <function>scrollVCursor</function> 496 </term> 497 <listitem> 498 <para> 499This 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> 510This is the size of the thumb, expressed as a percentage (0.0 - 1.0) 511of 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> 521The 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> 531This pixmap is used to tile (or stipple) the thumb of the scrollbar. If 532no tiling is desired, then set this resource to <function>None</function>. This 533resource will accept either a bitmap or a pixmap that is the same depth 534as the window. The resource converter for this resource constructs 535bitmaps from the contents of files. (See <function>Converting Bitmaps</function> for 536details.) 537 </para> 538 </listitem> 539 </varlistentry> 540 <varlistentry> 541 <term> 542 <function>topOfThumb</function> 543 </term> 544 <listitem> 545 <para> 546The location of the top of the thumb, as a percentage (0.0 - 1.0) 547of the length of the scrollbar. This resource was called <function>top</function> in 548previous versions of the Athena widget set. The name collided with the 549a 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 --> 561The 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> 570The possible <emphasis remap='I'>values</emphasis> are Forward, Backward, or Continuous. 571This 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> 581The possible <emphasis remap='I'>values</emphasis> are Proportional or FullLength. If the 582argument to StartScroll was Forward or Backward, NotifyScroll executes 583the <function>scrollProc</function> callbacks and passes either; the position of the 584pointer, if <emphasis remap='I'>value</emphasis> is Proportional, or the full length of the 585scroll bar, if <emphasis remap='I'>value</emphasis> is FullLength. If the argument to 586StartScroll was Continuous, NotifyScroll returns without executing any 587callbacks. 588 </para> 589 </listitem> 590 </varlistentry> 591 <varlistentry> 592 <term> 593 <function>EndScroll</function>( ) 594 </term> 595 <listitem> 596 <para> 597This 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> 607Repositions 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> 617Calls the 618<!-- .PN jumpProc --> 619callbacks and passes the relative position of the 620pointer as a percentage of the scroll bar length. 621 </para> 622 </listitem> 623 </varlistentry> 624</variablelist> 625<para> 626The default bindings for Scrollbar are: 627<indexterm><primary>Scrollbar widget</primary><secondary>default translation table</secondary></indexterm> 628</para> 629 630<literallayout class="monospaced"> 631 <Btn1Down>: StartScroll(Forward) 632 <Btn2Down>: StartScroll(Continuous) MoveThumb( ) NotifyThumb( ) 633 <Btn3Down>: StartScroll(Backward) 634 <Btn2Motion>: MoveThumb( ) NotifyThumb( ) 635 <BtnUp>: NotifyScroll(Proportional) EndScroll( ) 636</literallayout> 637 638<para> 639Examples of additional bindings a user might wish to specify in a 640resource file are: 641</para> 642 643<literallayout class="monospaced"> 644*Scrollbar.Translations: \\ 645 ~Meta<Key>space: StartScroll(Forward) NotifyScroll(FullLength) \\n\\ 646 Meta<Key>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<indexterm><primary>Scrollbar widget</primary><secondary>callbacks</secondary></indexterm> 655<para> 656<!-- .LP --> 657There are two callback lists provided by the Scrollbar widget. 658The procedural interface for these functions is described here. 659</para> 660 661<para> 662<!-- .LP --> 663The calling interface to the <function>scrollProc</function> callback procedure is: 664<indexterm significance="preferred"><primary>ScrollProc</primary></indexterm> 665</para> 666<funcsynopsis id='ScrollProc'> 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> 682Specifies 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> 692Specifies 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> 702Specifies a pixel position in integer form. 703 </para> 704 </listitem> 705 </varlistentry> 706</variablelist> 707 708<para> 709The <function>scrollProc</function> callback is used for incremental scrolling 710and is called by the <function>NotifyScroll</function> action. 711The position argument is a signed quantity and should be cast to an int 712when used. Using the default button bindings, button 1 returns a 713positive value, and button 3 returns a negative value. In both cases, 714the magnitude of the value is the distance of the pointer in 715pixels from the top (or left) of the Scrollbar. The value will never 716be greater than the length of the Scrollbar. 717</para> 718 719<para> 720The calling interface to the <function>jumpProc</function> callback procedure is: 721</para> 722<indexterm significance="preferred"><primary>jumpProc</primary></indexterm> 723<funcsynopsis id='JumpProc'> 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> 740Specifies 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> 750Specifies 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> 760Specifies the floating point position of the thumb (0.0 – 1.0). 761 </para> 762 </listitem> 763 </varlistentry> 764</variablelist> 765 766<para> 767The <function>jumpProc</function> callback is used to implement smooth scrolling and 768is called by the <function>NotifyThumb</function> action. Percent_ptr must be cast 769to 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> 777With the default button bindings, button 2 moves the thumb interactively, 778and the <function>jumpProc</function> is called on each new position of the pointer, 779while 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 781left of the Scrollbar) expressed as a percentage of the length of the 782Scrollbar. 783</para> 784 785</sect2> 786 787<sect2 id="Convenience_Routines"> 788<title>Convenience Routines</title> 789<para> 790<indexterm><primary>Scrollbar widget</primary><secondary>setting thumb values</secondary></indexterm> 791To set the position and length of a Scrollbar thumb, use 792<!-- .PN XawScrollbarSetThumb . --> 793<indexterm significance="preferred"><primary>XawScrollbarSetThumb</primary></indexterm> 794</para> 795<funcsynopsis id='XawScrollbarSetThumb'> 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> 811Specifies 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> 821Specifies the position of the top of the thumb as a fraction of the 822length 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> 832Specifies the length of the thumb as a fraction of the total length 833of the Scrollbar. 834 </para> 835 </listitem> 836 </varlistentry> 837</variablelist> 838 839<para> 840<function>XawScrollbarThumb</function> 841moves the visible thumb to a new position (0.0 – 1.0) and length (0.0 – 1.0). 842Either the top or shown arguments can be specified as -1.0, 843in which case the current value is left unchanged. 844Values greater than 1.0 are truncated to 1.0. 845</para> 846 847<para> 848If called from <function>jumpProc</function>, <xref linkend='XawScrollbarSetThumb' xrefstyle='select: title'/> has no effect. 849</para> 850 851</sect2> 852 853<sect2 id="Setting_Float_Resources"> 854<title>Setting Float Resources</title> 855<indexterm><primary>float resources</primary><secondary>setting</secondary></indexterm> 856<para> 857The <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 859argument list. The reason is that C performs an automatic cast of 860the float value to an integer value, usually truncating the important 861information. The following code fragment is one portable method of 862getting a float into an argument list. 863</para> 864<literallayout class="monospaced"> 865 top = 0.5; 866 if (sizeof(float) > 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, &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 *) &top; 879 XtSetArg(args[0], XtNshown, *l_top); 880 } 881</literallayout> 882 883</sect2> 884</sect1> 885