specs/Panner.xml

   1 <sect1 id="Panner_Widget">
   2 <title>Panner Widget</title>
   3 <para>
   4 <!-- .LP -->
   5 <!-- .XS -->
   6 <!--    Panner Widget -->
   7 <!-- .XE -->
   8 <!-- .IN "Panner widget" "" "@DEF@" -->
   9 <literallayout class="monospaced">
  10 <!-- .TA 2.0i -->
  11 <!-- .ta 2.0i -->
  12 <!-- .sp -->
  13 Application header file &lt;X11/Xaw/Panner.h&gt;
  14 <!-- .IN "Panner.h" "" -->
  15 Class header file       &lt;X11/Xaw/PannerP.h&gt;
  16 <!-- .IN "PannerP.h" "" -->
  17 Class           pannerWidgetClass
  18 <!-- .IN "pannerWidgetClass" "" -->
  19 Class Name      Panner
  20 <!-- .IN "Panner widget" "class name" -->
  21 Superclass      Simple
  22 <!-- .sp -->
  23 </literallayout>
  24 </para>
  25 <para>
  26 <!-- .LP -->
  27 A Panner widget is a rectangle, called the
  28 ``canvas,'' on which another rectangle, the ``slider,'' moves in two
  29 dimensions.  It is often used with a Porthole widget to move, or
  30 ``scroll,'' a third widget in two dimensions, in which case the
  31 slider's size and position gives feedback as to what portion of
  32 the third widget is visible.
  33 </para>
  34 <para>
  35 <!-- .LP -->
  36 The slider may be scrolled around the canvas by pressing,
  37 dragging, and releasing Button1; the default translation also
  38 enables scrolling via arrow keys and some other keys.  While
  39 scrolling is in progress, the application receives notification
  40 through callback procedures.  Notification may be done either
  41 continuously whenever the slider moves or discretely whenever the
  42 slider has been given a new location.
  43 </para>
  44 <sect2 id='Panner::Resources'>
  45 <title>Resources</title>
  46 <para>
  47 <!-- .LP -->
  48 When creating a Panner widget instance, the following resources are
  49 retrieved from the argument list or from the resource database:
  50 </para>
  51 <para>
  52 <!-- .LP -->
  53 <!-- .IN "Panner widget" "resources" -->
  54 <informaltable>
  55   <tgroup cols='5' align='center'>
  56   <colspec colname='c1'/>
  57   <colspec colname='c2'/>
  58   <colspec colname='c3'/>
  59   <colspec colname='c4'/>
  60   <colspec colname='c5'/>
  61   <thead>
  62     <row>
  63       <entry>Name</entry>
  64       <entry>Class</entry>
  65       <entry>Type</entry>
  66       <entry>Notes</entry>
  67       <entry>Default Value</entry>
  68     </row>
  69   </thead>
  70   <tbody>
  71     <row>
  72       <entry>accelerators</entry>
  73       <entry>Accelerators</entry>
  74       <entry>AcceleratorTable</entry>
  75       <entry></entry>
  76       <entry>NULL</entry>
  77     </row>
  78     <row>
  79       <entry>allowOff</entry>
  80       <entry>AllowOff</entry>
  81       <entry>Boolean</entry>
  82       <entry></entry>
  83       <entry>False</entry>
  84     </row>
  85     <row>
  86       <entry>ancestorSensitive</entry>
  87       <entry>AncestorSensitive</entry>
  88       <entry>Boolean</entry>
  89       <entry>D</entry>
  90       <entry>True</entry>
  91     </row>
  92     <row>
  93       <entry>background</entry>
  94       <entry>Background</entry>
  95       <entry>Pixel</entry>
  96       <entry></entry>
  97       <entry>XtDefaultBackground</entry>
  98     </row>
  99     <row>
 100       <entry>backgroundPixmap</entry>
 101       <entry>Pixmap</entry>
 102       <entry>Pixmap</entry>
 103       <entry></entry>
 104       <entry>XtUnspecifiedPixmap</entry>
 105     </row>
 106     <row>
 107       <entry>backgroundStipple</entry>
 108       <entry>BackgroundStipple</entry>
 109       <entry>String</entry>
 110       <entry></entry>
 111       <entry>NULL</entry>
 112     </row>
 113     <row>
 114       <entry>borderColor</entry>
 115       <entry>BorderColor</entry>
 116       <entry>Pixel</entry>
 117       <entry></entry>
 118       <entry>XtDefaultForeground</entry>
 119     </row>
 120     <row>
 121       <entry>borderPixmap</entry>
 122       <entry>Pixmap</entry>
 123       <entry>Pixmap</entry>
 124       <entry></entry>
 125       <entry>XtUnspecifiedPixmap</entry>
 126     </row>
 127     <row>
 128       <entry>borderWidth</entry>
 129       <entry>BorderWidth</entry>
 130       <entry>Dimension</entry>
 131       <entry></entry>
 132       <entry>1</entry>
 133     </row>
 134     <row>
 135       <entry>canvasHeight</entry>
 136       <entry>CanvasHeight</entry>
 137       <entry>Dimension</entry>
 138       <entry></entry>
 139       <entry>0</entry>
 140     </row>
 141     <row>
 142       <entry>canvasWidth</entry>
 143       <entry>CanvasWidth</entry>
 144       <entry>Dimension</entry>
 145       <entry></entry>
 146       <entry>0</entry>
 147     </row>
 148     <row>
 149       <entry>colormap</entry>
 150       <entry>Colormap</entry>
 151       <entry>Colormap</entry>
 152       <entry></entry>
 153       <entry>Parent's Colormap</entry>
 154     </row>
 155     <row>
 156       <entry>cursor</entry>
 157       <entry>Cursor</entry>
 158       <entry>Cursor</entry>
 159       <entry></entry>
 160       <entry>None</entry>
 161     </row>
 162     <row>
 163       <entry>cursorName</entry>
 164       <entry>Cursor</entry>
 165       <entry>String</entry>
 166       <entry></entry>
 167       <entry>NULL</entry>
 168     </row>
 169     <row>
 170       <entry>defaultScale</entry>
 171       <entry>DefaultScale</entry>
 172       <entry>Dimension</entry>
 173       <entry></entry>
 174       <entry>8</entry>
 175     </row>
 176     <row>
 177       <entry>depth</entry>
 178       <entry>Depth</entry>
 179       <entry>int</entry>
 180       <entry>C</entry>
 181       <entry>Parent's Depth</entry>
 182     </row>
 183     <row>
 184       <entry>destroyCallback</entry>
 185       <entry>Callback</entry>
 186       <entry>XtCallbackList</entry>
 187       <entry></entry>
 188       <entry>NULL</entry>
 189     </row>
 190     <row>
 191       <entry>foreground</entry>
 192       <entry>Foreground</entry>
 193       <entry>Pixel</entry>
 194       <entry></entry>
 195       <entry>XtDefaultForeground</entry>
 196     </row>
 197     <row>
 198       <entry>height</entry>
 199       <entry>Height</entry>
 200       <entry>Dimension</entry>
 201       <entry>A</entry>
 202       <entry>depends on orientation</entry>
 203     </row>
 204     <row>
 205       <entry>internalSpace</entry>
 206       <entry>InternalSpace</entry>
 207       <entry>Dimension</entry>
 208       <entry></entry>
 209       <entry>4</entry>
 210     </row>
 211     <row>
 212       <entry>international</entry>
 213       <entry>International</entry>
 214       <entry>Boolean</entry>
 215       <entry>C</entry>
 216       <entry>False</entry>
 217     </row>
 218     <row>
 219       <entry>lineWidth</entry>
 220       <entry>LineWidth</entry>
 221       <entry>Dimension</entry>
 222       <entry></entry>
 223       <entry>0</entry>
 224     </row>
 225     <row>
 226       <entry>mappedWhenManaged</entry>
 227       <entry>MappedWhenManaged</entry>
 228       <entry>Boolean</entry>
 229       <entry></entry>
 230       <entry>True</entry>
 231     </row>
 232     <row>
 233       <entry>pointerColor</entry>
 234       <entry>Foreground</entry>
 235       <entry>Pixel</entry>
 236       <entry></entry>
 237       <entry>XtDefaultForeground</entry>
 238     </row>
 239     <row>
 240       <entry>pointerColorBackground</entry>
 241       <entry>Background</entry>
 242       <entry>Pixel</entry>
 243       <entry></entry>
 244       <entry>XtDefaultBackground</entry>
 245     </row>
 246     <row>
 247       <entry>reportCallback</entry>
 248       <entry>ReportCallback</entry>
 249       <entry>Callback</entry>
 250       <entry></entry>
 251       <entry>NULL</entry>
 252     </row>
 253     <row>
 254       <entry>resize</entry>
 255       <entry>Resize</entry>
 256       <entry>Boolean</entry>
 257       <entry></entry>
 258       <entry>True</entry>
 259     </row>
 260     <row>
 261       <entry>rubberBand</entry>
 262       <entry>RubberBand</entry>
 263       <entry>Boolean</entry>
 264       <entry></entry>
 265       <entry>False</entry>
 266     </row>
 267     <row>
 268       <entry>screen</entry>
 269       <entry>Screen</entry>
 270       <entry>Screen</entry>
 271       <entry>R</entry>
 272       <entry>Parent's Screen</entry>
 273     </row>
 274     <row>
 275       <entry>sensitive</entry>
 276       <entry>Sensitive</entry>
 277       <entry>Boolean</entry>
 278       <entry></entry>
 279       <entry>True</entry>
 280     </row>
 281     <row>
 282       <entry>shadowColor</entry>
 283       <entry>ShadowColor</entry>
 284       <entry>Pixel</entry>
 285       <entry></entry>
 286       <entry>XtDefaultForeground</entry>
 287     </row>
 288     <row>
 289       <entry>shadowThickness</entry>
 290       <entry>ShadowThickness</entry>
 291       <entry>Dimension</entry>
 292       <entry></entry>
 293       <entry>2</entry>
 294     </row>
 295     <row>
 296       <entry>sliderX</entry>
 297       <entry>SliderX</entry>
 298       <entry>Position</entry>
 299       <entry></entry>
 300       <entry>0</entry>
 301     </row>
 302     <row>
 303       <entry>sliderY</entry>
 304       <entry>SliderY</entry>
 305       <entry>Position</entry>
 306       <entry></entry>
 307       <entry>0</entry>
 308     </row>
 309     <row>
 310       <entry>sliderHeight</entry>
 311       <entry>SliderHeight</entry>
 312       <entry>Dimension</entry>
 313       <entry></entry>
 314       <entry>0</entry>
 315     </row>
 316     <row>
 317       <entry>sliderWidth</entry>
 318       <entry>SliderWidth</entry>
 319       <entry>Dimension</entry>
 320       <entry></entry>
 321       <entry>0</entry>
 322     </row>
 323     <row>
 324       <entry>translations</entry>
 325       <entry>Translations</entry>
 326       <entry>TranslationTable</entry>
 327       <entry></entry>
 328       <entry>See below</entry>
 329     </row>
 330     <row>
 331       <entry>width</entry>
 332       <entry>Width</entry>
 333       <entry>Dimension</entry>
 334       <entry>A</entry>
 335       <entry>depends on orientation</entry>
 336     </row>
 337     <row>
 338       <entry>x</entry>
 339       <entry>Position</entry>
 340       <entry>Position</entry>
 341       <entry></entry>
 342       <entry>0</entry>
 343     </row>
 344     <row>
 345       <entry>y</entry>
 346       <entry>Position</entry>
 347       <entry>Position</entry>
 348       <entry></entry>
 349       <entry>0</entry>
 350     </row>
 351   </tbody>
 352   </tgroup>
 353 </informaltable>
 354 </para>
 355 <!-- .Ac -->
 356 <variablelist>
 357   <varlistentry>
 358     <term>
 359       <function>allowOff</function>
 360     </term>
 361     <listitem>
 362       <para>
 363 Whether to allow the edges of the slider to go off the edges of the canvas.
 364 <!-- .As -->
 365 <!-- .Bg -->
 366 <!-- .Gp -->
 367       </para>
 368     </listitem>
 369   </varlistentry>
 370   <varlistentry>
 371     <term>
 372       <function>backgroundStipple</function>
 373     </term>
 374     <listitem>
 375       <para>
 376 The name of a bitmap pattern to be used as the background for
 377 the area representing the canvas.
 378 <!-- .Bc -->
 379 <!-- .Bp -->
 380 <!-- .Bw -->
 381       </para>
 382     </listitem>
 383   </varlistentry>
 384   <varlistentry>
 385     <term>
 386       <function>canvasHeight</function>
 387     </term>
 388     <listitem>
 389       <para>
 390 <!-- .br -->
 391 <!-- .ns -->
 392       </para>
 393     </listitem>
 394   </varlistentry>
 395   <varlistentry>
 396     <term>
 397       <function>canvasWidth</function>
 398     </term>
 399     <listitem>
 400       <para>
 401 The size of the canvas.
 402 <!-- .Cm -->
 403 <!-- .Cu -->
 404 <!-- .Cn -->
 405       </para>
 406     </listitem>
 407   </varlistentry>
 408   <varlistentry>
 409     <term>
 410       <function>defaultScale</function>
 411     </term>
 412     <listitem>
 413       <para>
 414 The percentage size that the Panner widget should have relative
 415 to the size of the canvas.
 416 <!-- .Dp -->
 417 <!-- .Dc -->
 418       </para>
 419     </listitem>
 420   </varlistentry>
 421   <varlistentry>
 422     <term>
 423       <function>foreground</function>
 424     </term>
 425     <listitem>
 426       <para>
 427 A pixel value which indexes the widget's colormap to derive the color
 428 used to draw the slider.
 429 <!-- .Hw -->
 430     </para>
 431   </listitem>
 432   </varlistentry>
 433   <varlistentry>
 434     <term>
 435       <function>internalSpace</function>
 436     </term>
 437     <listitem>
 438       <para>
 439 The width of internal border in pixels between a slider representing the
 440 full size of the canvas
 441 and the edge of the Panner widget.
 442 <!-- .Ix -->
 443       </para>
 444     </listitem>
 445   </varlistentry>
 446   <varlistentry>
 447     <term>
 448       <function>lineWidth</function>
 449     </term>
 450     <listitem>
 451       <para>
 452 The width of the lines in the rubberbanding rectangle when rubberbanding
 453 is in effect instead of continuous scrolling.  The default is 0.
 454 <!-- .Mm -->
 455 <!-- .Pf -->
 456 <!-- .Pb -->
 457       </para>
 458     </listitem>
 459   </varlistentry>
 460   <varlistentry>
 461     <term>
 462       <function>reportCallback</function>
 463     </term>
 464     <listitem>
 465       <para>
 466 All functions on this callback list are called when the
 467 <function>notify</function> action is invoked.  See the <function>Panner Actions</function> section
 468 for details.
 469       </para>
 470     </listitem>
 471   </varlistentry>
 472   <varlistentry>
 473     <term>
 474       <function>resize</function>
 475     </term>
 476     <listitem>
 477       <para>
 478 Whether or not to resize the panner whenever the canvas size is changed so
 479 that the <function>defaultScale</function> is maintained.
 480       </para>
 481     </listitem>
 482   </varlistentry>
 483   <varlistentry>
 484     <term>
 485       <function>rubberBand</function>
 486     </term>
 487     <listitem>
 488       <para>
 489 Whether or not scrolling should be discrete (only moving a rubberbanded
 490 rectangle until the scrolling is done) or continuous (moving the slider
 491 itself).  This controls whether or not the <function>move</function> action procedure also
 492 invokes the <function>notify</function> action procedure.
 493 <!-- .Sc -->
 494 <!-- .Se -->
 495       </para>
 496     </listitem>
 497   </varlistentry>
 498   <varlistentry>
 499     <term>
 500       <function>shadowColor</function>
 501     </term>
 502     <listitem>
 503       <para>
 504 The color of the shadow underneath the slider.
 505       </para>
 506     </listitem>
 507   </varlistentry>
 508   <varlistentry>
 509     <term>
 510       <function>shadowThickness</function>
 511     </term>
 512     <listitem>
 513       <para>
 514 The width of the shadow underneath the slider.
 515       </para>
 516     </listitem>
 517   </varlistentry>
 518   <varlistentry>
 519     <term>
 520       <function>sliderX</function>
 521     </term>
 522     <listitem>
 523       <para>
 524 <!-- .br -->
 525 <!-- .ns -->
 526       </para>
 527     </listitem>
 528   </varlistentry>
 529   <varlistentry>
 530     <term>
 531       <function>sliderY</function>
 532     </term>
 533     <listitem>
 534       <para>
 535 The location of the slider in the coordinates of the canvas.
 536       </para>
 537     </listitem>
 538   </varlistentry>
 539   <varlistentry>
 540     <term>
 541       <function>sliderHeight</function>
 542     </term>
 543     <listitem>
 544       <para>
 545 <!-- .br -->
 546 <!-- .ns -->
 547       </para>
 548     </listitem>
 549   </varlistentry>
 550   <varlistentry>
 551     <term>
 552       <function>sliderWidth</function>
 553     </term>
 554     <listitem>
 555       <para>
 556 The size of the slider.
 557 <!-- .Tr -->
 558 <!-- .Xy -->
 559      </para>
 560     </listitem>
 561   </varlistentry>
 562 </variablelist>
 563 </sect2>
 564 <sect2 id="Panner_Actions">
 565 <title>Panner Actions</title>
 566 <!-- .IN "Panner widget" "actions" -->
 567 <para>
 568 <!-- .LP -->
 569 The actions supported by the Panner widget are:
 570 </para>
 571 <variablelist>
 572   <varlistentry>
 573     <term>
 574       <function>start</function>()
 575     </term>
 576     <listitem>
 577       <para>
 578 This action begins movement of the slider.
 579       </para>
 580     </listitem>
 581   </varlistentry>
 582   <varlistentry>
 583     <term>
 584       <function>stop</function>()
 585     </term>
 586     <listitem>
 587       <para>
 588 This action ends movement of the slider.
 589       </para>
 590     </listitem>
 591   </varlistentry>
 592   <varlistentry>
 593     <term>
 594       <function>abort</function>()
 595     </term>
 596     <listitem>
 597       <para>
 598 This action ends movement of the slider and restores it to the position it
 599 held when the <function>start</function> action was invoked.
 600       </para>
 601     </listitem>
 602   </varlistentry>
 603   <varlistentry>
 604     <term>
 605       <function>move</function>()
 606     </term>
 607     <listitem>
 608       <para>
 609 This action moves the outline of the slider (if the <function>rubberBand</function> resource
 610 is True) or the slider itself (by invoking the <function>notify</function>
 611 action procedure).
 612       </para>
 613     </listitem>
 614   </varlistentry>
 615   <varlistentry>
 616     <term>
 617       <function>page</function>(<function>xamount</function>,<function>yamount</function>)
 618     </term>
 619     <listitem>
 620       <para>
 621 This action moves the slider by the specified amounts.  The format
 622 for the amounts is a signed or unsigned floating-point number (e.g., +1.0
 623 or \-.5) followed
 624 by either <function>p</function> indicating pages (slider sizes), or <function>c</function> indicating
 625 canvas sizes.  Thus, <emphasis remap='I'>page(+0,+.5p)</emphasis> represents vertical movement down
 626 one-half the height of the slider and <emphasis remap='I'>page(0,0)</emphasis> represents moving to
 627 the upper left corner of the canvas.
 628       </para>
 629     </listitem>
 630   </varlistentry>
 631   <varlistentry>
 632     <term>
 633       <function>notify</function>()
 634     </term>
 635     <listitem>
 636       <para>
 637 This action informs the application of the slider's current position by
 638 invoking the <function>reportCallback</function> functions registered by the application.
 639       </para>
 640     </listitem>
 641   </varlistentry>
 642   <varlistentry>
 643     <term>
 644       <function>set</function>(<function>what</function>,<function>value</function>)
 645     </term>
 646     <listitem>
 647       <para>
 648 This action changes the behavior of the Panner.  The <emphasis remap='I'>what</emphasis> argument
 649 must currently be the string <function>rubberband</function> and controls the value of
 650 the <function>rubberBand</function> resource.  The <function>value</function> argument
 651 may have one of the values <function>on</function>, <function>off</function>, or <function>toggle</function>.
 652       </para>
 653     </listitem>
 654   </varlistentry>
 655 </variablelist>
 656
 657 <para>
 658 <!-- .LP -->
 659 <!-- .sp -->
 660 The default bindings for Panner are:
 661 <!-- .IN "Panner widget" "default translation table" -->
 662 </para>
 663 <!-- .LP -->
 664 <literallayout class="monospaced">
 665 <!-- .TA .5i 1.75i -->
 666 <!-- .ta .5i 1.75i -->
 667         &lt;Btn1Down&gt;:       start(\|)
 668         &lt;Btn1Motion&gt;:     move(\|)
 669         &lt;Btn1Up&gt;: notify(\|) stop(\|)
 670         &lt;Btn2Down&gt;:       abort(\|)
 671         &lt;Key&gt;KP_Enter:    set(rubberband,toggle)
 672         &lt;Key&gt;space:       page(+1p,+1p)
 673         &lt;Key&gt;Delete:      page(\-1p,\-1p)
 674         &lt;Key&gt;BackSpace:   page(\-1p,\-1p)
 675         &lt;Key&gt;Left:        page(\-.5p,+0)
 676         &lt;Key&gt;Right:       page(+.5p,+0)
 677         &lt;Key&gt;Up:  page(+0,\-.5p)
 678         &lt;Key&gt;Down:        page(+0,+.5p)
 679         &lt;Key&gt;Home:        page(0,0)
 680 </literallayout>
 681 </sect2>
 682
 683 <sect2 id="Panner_Callbacks">
 684 <title>Panner Callbacks</title>
 685 <!-- .IN "Panner widget" "callbacks" -->
 686 <para>
 687 <!-- .LP -->
 688 The functions registered on the <function>reportCallback</function> list are invoked by
 689 the <function>notify</function> action as follows:
 690 <!-- .IN "ReportProc" "" "@DEF@" -->
 691 <funcsynopsis id='Panner::ReportProc'>
 692 <funcprototype>
 693   <funcdef>void<function> ReportProc</function></funcdef>
 694   <paramdef>Widget<parameter> panner</parameter></paramdef>
 695   <paramdef>XtPointer<parameter> client_data</parameter></paramdef>
 696   <paramdef>XtPointer<parameter> report</parameter></paramdef>
 697 </funcprototype>
 698 </funcsynopsis>
 699 <!-- .FN -->
 700     </para>
 701 <para>
 702 <variablelist>
 703   <varlistentry>
 704     <term>panner</term>
 705     <listitem>
 706       <para>
 707 <!-- .IP <emphasis remap='I'>panner</emphasis> 1i -->
 708 Specifies the Panner widget.
 709       </para>
 710     </listitem>
 711   </varlistentry>
 712   <varlistentry>
 713     <term>panner</term>
 714     <listitem>
 715       <para>
 716 <!-- .IP <emphasis remap='I'>client_data</emphasis> 1i -->
 717 Specifies the client data.
 718       </para>
 719     </listitem>
 720   </varlistentry>
 721   <varlistentry>
 722     <term>panner</term>
 723     <listitem>
 724       <para>
 725 <!-- .IP <emphasis remap='I'>report</emphasis> 1i -->
 726 Specifies a pointer to an <function>XawPannerReport</function> structure containing
 727 the location and size of the slider and the size of the canvas.
 728       </para>
 729     </listitem>
 730   </varlistentry>
 731 </variablelist>
 732 </para>
 733 </sect2>
 734 </sect1>