specs/Repeater.xml

   1 <sect1 id="Repeater_Widget">
   2 <title>Repeater Widget</title>
   3 <!-- .XS -->
   4 <!--    Repeater Widget -->
   5 <!-- .XE -->
   6 <!-- .IN "Repeater widget" "" "@DEF@" -->
   7 <literallayout class="monospaced">
   8 <!-- .TA 2.0i -->
   9 <!-- .ta 2.0i -->
  10 <!-- .sp -->
  11 Application header file &lt;X11/Xaw/Repeater.h&gt;
  12 <!-- .IN "Repeater.h" "" -->
  13 Class header file       &lt;X11/Xaw/RepeaterP.h&gt;
  14 <!-- .IN "RepeaterP.h" "" -->
  15 Class   repeaterWidgetClass
  16 <!-- .IN "repeaterWidgetClass" "" -->
  17 Class Name      Repeater
  18 <!-- .IN "Repeater widget" "class name" -->
  19 Superclass      Command
  20 <!-- .sp -->
  21 </literallayout>
  22 <para>
  23 <!-- .LP -->
  24 The Repeater widget is a subclass of the Command widget; see the <!-- xref -->
  25 Command documentation for details.  The difference is that the Repeater can call its
  26 registered callbacks repeatedly, at an increasing rate.  The default translation
  27 does so for the duration the user holds down pointer button 1 while the pointer
  28 is on the Repeater.
  29 </para>
  30 <sect2 id='Repeater::Resources'>
  31 <title>Resources</title>
  32 <para>
  33 <!-- .LP -->
  34 When creating a Repeater widget instance, the following resources are
  35 retrieved from the argument list or from the resource database:
  36 </para>
  37 <para>
  38 <!-- .LP -->
  39 <!-- .IN "Repeater widget" "resources" -->
  40 <informaltable>
  41   <tgroup cols='5' align='center'>
  42   <colspec colname='c1'/>
  43   <colspec colname='c2'/>
  44   <colspec colname='c3'/>
  45   <colspec colname='c4'/>
  46   <colspec colname='c5'/>
  47   <thead>
  48     <row>
  49       <entry>Name</entry>
  50       <entry>Class</entry>
  51       <entry>Type</entry>
  52       <entry>Notes</entry>
  53       <entry>Default Value</entry>
  54     </row>
  55   </thead>
  56   <tbody>
  57     <row>
  58       <entry>accelerators</entry>
  59       <entry>Accelerators</entry>
  60       <entry>AcceleratorTable</entry>
  61       <entry></entry>
  62       <entry>NULL</entry>
  63     </row>
  64     <row>
  65       <entry>ancestorSensitive</entry>
  66       <entry>AncestorSensitive</entry>
  67       <entry>Boolean</entry>
  68       <entry>D</entry>
  69       <entry>True</entry>
  70     </row>
  71     <row>
  72       <entry>background</entry>
  73       <entry>Background</entry>
  74       <entry>Pixel</entry>
  75       <entry></entry>
  76       <entry>XtDefaultBackground</entry>
  77     </row>
  78     <row>
  79       <entry>backgroundPixmap</entry>
  80       <entry>Pixmap</entry>
  81       <entry>Pixmap</entry>
  82       <entry></entry>
  83       <entry>XtUnspecifiedPixmap</entry>
  84     </row>
  85     <row>
  86       <entry>bitmap</entry>
  87       <entry>Bitmap</entry>
  88       <entry>Pixmap</entry>
  89       <entry></entry>
  90       <entry>None</entry>
  91     </row>
  92     <row>
  93       <entry>borderColor</entry>
  94       <entry>BorderColor</entry>
  95       <entry>Pixel</entry>
  96       <entry></entry>
  97       <entry>XtDefaultForeground</entry>
  98     </row>
  99     <row>
 100       <entry>borderPixmap</entry>
 101       <entry>Pixmap</entry>
 102       <entry>Pixmap</entry>
 103       <entry></entry>
 104       <entry>XtUnspecifiedPixmap</entry>
 105     </row>
 106     <row>
 107       <entry>borderWidth</entry>
 108       <entry>BorderWidth</entry>
 109       <entry>Dimension</entry>
 110       <entry></entry>
 111       <entry>1</entry>
 112     </row>
 113     <row>
 114       <entry>callback</entry>
 115       <entry>Callback</entry>
 116       <entry>XtCallbackList</entry>
 117       <entry></entry>
 118       <entry>NULL</entry>
 119     </row>
 120     <row>
 121       <entry>colormap</entry>
 122       <entry>Colormap</entry>
 123       <entry>Colormap</entry>
 124       <entry></entry>
 125       <entry>Parent's Colormap</entry>
 126     </row>
 127     <row>
 128       <entry>cornerRoundPercent</entry>
 129       <entry>CornerRoundPercent</entry>
 130       <entry>Dimension</entry>
 131       <entry></entry>
 132       <entry>25</entry>
 133     </row>
 134     <row>
 135       <entry>cursor</entry>
 136       <entry>Cursor</entry>
 137       <entry>Cursor</entry>
 138       <entry></entry>
 139       <entry>None</entry>
 140     </row>
 141     <row>
 142       <entry>cursorName</entry>
 143       <entry>Cursor</entry>
 144       <entry>String</entry>
 145       <entry></entry>
 146       <entry>NULL</entry>
 147     </row>
 148     <row>
 149       <entry>decay</entry>
 150       <entry>Decay</entry>
 151       <entry>Int</entry>
 152       <entry></entry>
 153       <entry>5</entry>
 154     </row>
 155     <row>
 156       <entry>depth</entry>
 157       <entry>Depth</entry>
 158       <entry>int</entry>
 159       <entry>C</entry>
 160       <entry>Parent's Depth</entry>
 161     </row>
 162     <row>
 163       <entry>destroyCallback</entry>
 164       <entry>Callback</entry>
 165       <entry>XtCallbackList</entry>
 166       <entry></entry>
 167       <entry>NULL</entry>
 168     </row>
 169     <row>
 170       <entry>encoding</entry>
 171       <entry>Encoding</entry>
 172       <entry>UnsignedChar</entry>
 173       <entry></entry>
 174       <entry>XawTextEncoding8bit</entry>
 175     </row>
 176     <row>
 177       <entry>flash</entry>
 178       <entry>Boolean</entry>
 179       <entry>Boolean</entry>
 180       <entry></entry>
 181       <entry>False</entry>
 182     </row>
 183     <row>
 184       <entry>font</entry>
 185       <entry>Font</entry>
 186       <entry>XFontStruct</entry>
 187       <entry></entry>
 188       <entry>XtDefaultFont</entry>
 189     </row>
 190     <row>
 191       <entry>fontSet</entry>
 192       <entry>FontSet</entry>
 193       <entry>XFontSet</entry>
 194       <entry></entry>
 195       <entry>XtDefaultFontSet</entry>
 196     </row>
 197     <row>
 198       <entry>foreground</entry>
 199       <entry>Foreground</entry>
 200       <entry>Pixel</entry>
 201       <entry></entry>
 202       <entry>XtDefaultForeground</entry>
 203     </row>
 204     <row>
 205       <entry>height</entry>
 206       <entry>Height</entry>
 207       <entry>Dimension</entry>
 208       <entry>A</entry>
 209       <entry>graphic height + 2 * <function>internalHeight</function></entry>
 210     </row>
 211     <row>
 212       <entry>highlightThickness</entry>
 213       <entry>Thickness</entry>
 214       <entry>Dimension</entry>
 215       <entry>A</entry>
 216       <entry>2 (0 if Shaped)</entry>
 217     </row>
 218     <row>
 219       <entry>initialDelay</entry>
 220       <entry>Delay</entry>
 221       <entry>Int</entry>
 222       <entry></entry>
 223       <entry>200</entry>
 224     </row>
 225     <row>
 226       <entry>insensitiveBorder</entry>
 227       <entry>Insensitive</entry>
 228       <entry>Pixmap</entry>
 229       <entry></entry>
 230       <entry>GreyPixmap</entry>
 231     </row>
 232     <row>
 233       <entry>internalHeight</entry>
 234       <entry>Height</entry>
 235       <entry>Dimension</entry>
 236       <entry></entry>
 237       <entry>2</entry>
 238     </row>
 239     <row>
 240       <entry>internalWidth</entry>
 241       <entry>Width</entry>
 242       <entry>Dimension</entry>
 243       <entry></entry>
 244       <entry>4</entry>
 245     </row>
 246     <row>
 247       <entry>international</entry>
 248       <entry>International</entry>
 249       <entry>Boolean</entry>
 250       <entry>C</entry>
 251       <entry>False</entry>
 252     </row>
 253     <row>
 254       <entry>justify</entry>
 255       <entry>Justify</entry>
 256       <entry>Justify</entry>
 257       <entry></entry>
 258       <entry>XtJustifyCenter (center)</entry>
 259     </row>
 260     <row>
 261       <entry>label</entry>
 262       <entry>Label</entry>
 263       <entry>String</entry>
 264       <entry></entry>
 265       <entry>name of widget</entry>
 266     </row>
 267     <row>
 268       <entry>leftBitmap</entry>
 269       <entry>LeftBitmap</entry>
 270       <entry>Bitmap</entry>
 271       <entry></entry>
 272       <entry>None</entry>
 273     </row>
 274     <row>
 275       <entry>mappedWhenManaged</entry>
 276       <entry>MappedWhenManaged</entry>
 277       <entry>Boolean</entry>
 278       <entry></entry>
 279       <entry>True</entry>
 280     </row>
 281     <row>
 282       <entry>minimumDelay</entry>
 283       <entry>MinimumDelay</entry>
 284       <entry>Int</entry>
 285       <entry></entry>
 286       <entry>10</entry>
 287     </row>
 288     <row>
 289       <entry>pointerColor</entry>
 290       <entry>Foreground</entry>
 291       <entry>Pixel</entry>
 292       <entry></entry>
 293       <entry>XtDefaultForeground</entry>
 294     </row>
 295     <row>
 296       <entry>pointerColorBackground</entry>
 297       <entry>Background</entry>
 298       <entry>Pixel</entry>
 299       <entry></entry>
 300       <entry>XtDefaultBackground</entry>
 301     </row>
 302     <row>
 303       <entry>repeatDelay</entry>
 304       <entry>Delay</entry>
 305       <entry>Int</entry>
 306       <entry></entry>
 307       <entry>50</entry>
 308     </row>
 309     <row>
 310       <entry>resize</entry>
 311       <entry>Resize</entry>
 312       <entry>Boolean</entry>
 313       <entry></entry>
 314       <entry>True</entry>
 315     </row>
 316     <row>
 317       <entry>screen</entry>
 318       <entry>Screen</entry>
 319       <entry>Pointer</entry>
 320       <entry>R</entry>
 321       <entry>Parent's Screen</entry>
 322     </row>
 323     <row>
 324       <entry>sensitive</entry>
 325       <entry>Sensitive</entry>
 326       <entry>Boolean</entry>
 327       <entry></entry>
 328       <entry>True</entry>
 329     </row>
 330     <row>
 331       <entry>shapeStyle</entry>
 332       <entry>ShapeStyle</entry>
 333       <entry>ShapeStyle</entry>
 334       <entry></entry>
 335       <entry>Rectangle</entry>
 336     </row>
 337     <row>
 338       <entry>startCallback</entry>
 339       <entry>StartCallback</entry>
 340       <entry>Callback</entry>
 341       <entry></entry>
 342       <entry>NULL</entry>
 343     </row>
 344     <row>
 345       <entry>stopCallback</entry>
 346       <entry>StopCallback</entry>
 347       <entry>Callback</entry>
 348       <entry></entry>
 349       <entry>NULL</entry>
 350     </row>
 351     <row>
 352       <entry>translations</entry>
 353       <entry>Translations</entry>
 354       <entry>TranslationTable</entry>
 355       <entry></entry>
 356       <entry>See below</entry>
 357     </row>
 358     <row>
 359       <entry>width</entry>
 360       <entry>Width</entry>
 361       <entry>Dimension</entry>
 362       <entry>A</entry>
 363       <entry>graphic width + 2 * <function>internalWidth</function></entry>
 364     </row>
 365     <row>
 366       <entry>x</entry>
 367       <entry>Position</entry>
 368       <entry>Position</entry>
 369       <entry></entry>
 370       <entry>0</entry>
 371     </row>
 372     <row>
 373       <entry>y</entry>
 374       <entry>Position</entry>
 375       <entry>Position</entry>
 376       <entry></entry>
 377       <entry>0</entry>
 378     </row>
 379   </tbody>
 380   </tgroup>
 381 </informaltable>
 382 \" Resource Descriptions
 383 <!-- .Ac -->
 384 <!-- .As -->
 385 <!-- .Bg -->
 386 <!-- .Gp -->
 387 <!-- .Bm -->
 388 <!-- .Bc -->
 389 <!-- .Bp -->
 390 <!-- .Bw -->
 391 <!-- .Cb -->
 392 <!-- .Cm -->
 393 <!-- .Cr -->
 394 <!-- .Cu -->
 395 <!-- .Cn -->
 396 <variablelist>
 397   <varlistentry>
 398     <term>
 399       <function>decay</function>
 400     </term>
 401     <listitem>
 402       <para>
 403 The number of milliseconds that should be subtracted from each succeeding
 404 interval while the Repeater button is being held down until the interval
 405 has reached <function>minimumDelay</function> milliseconds.
 406 <!-- .Dp -->
 407 <!-- .Dc -->
 408 <!-- .Le -->
 409       </para>
 410     </listitem>
 411   </varlistentry>
 412   <varlistentry>
 413     <term>
 414       <function>flash</function>
 415     </term>
 416     <listitem>
 417       <para>
 418 Whether or not to flash the Repeater button whenever the timer goes off.
 419 <!-- .Lf -->
 420 <!-- .Ls -->
 421 <!-- .Lg -->
 422 <!-- .Hw -->
 423 <!-- .Ht -->
 424       </para>
 425     </listitem>
 426   </varlistentry>
 427   <varlistentry>
 428     <term>
 429       <function>initialDelay</function>
 430     </term>
 431     <listitem>
 432       <para>
 433 The number of milliseconds between the beginning of the Repeater button
 434 being held down and the first invocation of the <function>callback</function> function.
 435 <!-- .Ib -->
 436 <!-- .Ih -->
 437 <!-- .In -->
 438 <!-- .Ju -->
 439 <!-- .La -->
 440 <!-- .Ll -->
 441 <!-- .Mm -->
 442       </para>
 443     </listitem>
 444   </varlistentry>
 445   <varlistentry>
 446     <term>
 447       <function>minimumDelay</function>
 448     </term>
 449     <listitem>
 450       <para>
 451 The minimum time between callbacks in milliseconds.
 452 <!-- .Pf -->
 453 <!-- .Pb -->
 454       </para>
 455     </listitem>
 456   </varlistentry>
 457   <varlistentry>
 458     <term>
 459       <function>repeatDelay</function>
 460     </term>
 461     <listitem>
 462       <para>
 463 The number of milliseconds between each callback after the first (minus an
 464 increasing number of <function>decay</function>s).
 465 <!-- .Re -->
 466 <!-- .Sc -->
 467 <!-- .Se -->
 468 <!-- .Ss -->
 469       </para>
 470     </listitem>
 471   </varlistentry>
 472   <varlistentry>
 473     <term>
 474       <function>startCallback</function>
 475     </term>
 476     <listitem>
 477       <para>
 478 The list of functions to invoke by the <function>start</function> action (typically
 479 when the Repeater button is first pressed).  The callback data parameter
 480 is set to NULL.
 481       </para>
 482     </listitem>
 483   </varlistentry>
 484   <varlistentry>
 485     <term>
 486       <function>stopCallback</function>
 487     </term>
 488     <listitem>
 489       <para>
 490 The list of functions to invoke by the <function>stop</function> action (typically
 491 when the Repeater button is released).  The callback data parameter
 492 is set to NULL.
 493 <!-- .Tr -->
 494 <!-- .Xy -->
 495     </para>
 496   </listitem>
 497   </varlistentry>
 498 </variablelist>
 499 </para>
 500 </sect2>
 501 <sect2 id="Repeater_Actions">
 502 <title>Repeater Actions</title>
 503 <!-- .IN "Repeater widget" "actions" -->
 504 <para>
 505 <!-- .LP -->
 506 The Repeater widget supports the following actions beyond those of the Command
 507 button:
 508 <variablelist>
 509   <varlistentry>
 510     <term>
 511       <function>start</function>()
 512     </term>
 513     <listitem>
 514       <para>
 515 This invokes the functions on the <function>startCallback</function> and <function>callback</function> lists
 516 and sets a timer to go off in <function>initialDelay</function> milliseconds.  The timer
 517 will cause the <function>callback</function> functions to be invoked with increasing
 518 frequency until the <function>stop</function> action occurs.
 519       </para>
 520     </listitem>
 521   </varlistentry>
 522   <varlistentry>
 523     <term>
 524       <function>stop</function>()
 525     </term>
 526     <listitem>
 527       <para>
 528 This invokes the functions on the <function>stopCallback</function> list and prevents any
 529 further timers from occuring until the next <function>start</function> action.
 530     </para>
 531   </listitem>
 532   </varlistentry>
 533 </variablelist>
 534 </para>
 535 <para>
 536 <!-- .LP -->
 537 <!-- .sp -->
 538 <!-- .IN "Repeater widget" "translation bindings" -->
 539 The following are the default translation bindings used by the
 540 Repeater widget:
 541 </para>
 542 <para>
 543 <!-- .LP -->
 544 <literallayout class="monospaced">
 545 <!-- .TA .5i 2.25i -->
 546 <!-- .ta .5i 2.25i -->
 547         &lt;EnterWindow&gt;:    highlight(\|)
 548         &lt;LeaveWindow&gt;:    unhighlight(\|)
 549         &lt;Btn1Down&gt;:       set(\|) start(\|)
 550         &lt;Btn1Up&gt;: stop(\|) unset(\|)
 551 </literallayout>
 552 </para>
 553 <para>
 554 <!-- .LP -->
 555
 556 </para>
 557 </sect2>
 558 </sect1>