specs/Command.xml

   1 <sect1 id="Command_Widget">
   2 <title>Command Widget</title>
   3 <!-- .XS -->
   4 <!--    Command Widget -->
   5 <!-- .XE -->
   6 <!-- .IN "Command widget" "" "@DEF@" -->
   7 <literallayout class="monospaced">
   8 <!-- .TA 2.0i -->
   9 <!-- .ta 2.0i -->
  10 <!-- .sp -->
  11 Application header file &lt;X11/Xaw/Command.h&gt;
  12 <!-- .IN "Command.h" "" -->
  13 Class header file       &lt;X11/Xaw/CommandP.h&gt;
  14 <!-- .IN "CommandP.h" "" -->
  15 Class   commandWidgetClass
  16 <!-- .IN "commandWidgetClass" "" -->
  17 Class Name      Command
  18 <!-- .IN "Command widget" "class name" -->
  19 Superclass      Label
  20 <!-- .sp -->
  21 </literallayout>
  22 <para>
  23 <!-- .LP -->
  24 The Command widget is an area, often rectangular, that contains text
  25 or a graphical image. Command widgets are often referred to as
  26 ``push buttons.''  When the pointer is over a Command widget, the
  27 widget becomes highlighted by drawing a rectangle around its perimeter.
  28 This highlighting indicates that the widget is ready for selection.
  29 When mouse button 1 is pressed, the Command widget indicates that
  30 it has been selected by reversing its foreground and background colors.
  31 When the mouse button is released, the Command widget's <function>notify</function>
  32 action is invoked, calling all functions on its callback list.  If
  33 the pointer is moved off of the widget before the pointer button is
  34 released, the widget reverts to its normal foreground and background
  35 colors, and releasing the pointer button has no effect.  This behavior
  36 allows the user to cancel an action.
  37 </para>
  38 <sect2 id="Resources">
  39 <title>Resources</title>
  40 <para>
  41 <!-- .LP -->
  42 When creating a Command widget instance, the following resources are
  43 retrieved from the argument list or from the resource database:
  44 </para>
  45 <para>
  46 <!-- .LP -->
  47 <!-- .IN "Command widget" "resources" -->
  48 <informaltable>
  49   <tgroup cols='5' align='center'>
  50   <colspec colname='c1'/>
  51   <colspec colname='c2'/>
  52   <colspec colname='c3'/>
  53   <colspec colname='c4'/>
  54   <colspec colname='c5'/>
  55   <thead>
  56     <row>
  57       <entry>Name</entry>
  58       <entry>Class</entry>
  59       <entry>Type</entry>
  60       <entry>Notes</entry>
  61       <entry>Default Value</entry>
  62     </row>
  63   </thead>
  64   <tbody>
  65     <row>
  66       <entry>accelerators</entry>
  67       <entry>Accelerators</entry>
  68       <entry>AcceleratorTable</entry>
  69       <entry></entry>
  70       <entry>NULL</entry>
  71     </row>
  72     <row>
  73       <entry>ancestorSensitive</entry>
  74       <entry>AncestorSensitive</entry>
  75       <entry>Boolean</entry>
  76       <entry>D</entry>
  77       <entry>True</entry>
  78     </row>
  79     <row>
  80       <entry>background</entry>
  81       <entry>Background</entry>
  82       <entry>Pixel</entry>
  83       <entry></entry>
  84       <entry>XtDefaultBackground</entry>
  85     </row>
  86     <row>
  87       <entry>backgroundPixmap</entry>
  88       <entry>Pixmap</entry>
  89       <entry>Pixmap</entry>
  90       <entry></entry>
  91       <entry>XtUnspecifiedPixmap</entry>
  92     </row>
  93     <row>
  94       <entry>bitmap</entry>
  95       <entry>Bitmap</entry>
  96       <entry>Pixmap</entry>
  97       <entry></entry>
  98       <entry>None</entry>
  99     </row>
 100     <row>
 101       <entry>borderColor</entry>
 102       <entry>BorderColor</entry>
 103       <entry>Pixel</entry>
 104       <entry></entry>
 105       <entry>XtDefaultForeground</entry>
 106     </row>
 107     <row>
 108       <entry>borderPixmap</entry>
 109       <entry>Pixmap</entry>
 110       <entry>Pixmap</entry>
 111       <entry></entry>
 112       <entry>XtUnspecifiedPixmap</entry>
 113     </row>
 114     <row>
 115       <entry>borderWidth</entry>
 116       <entry>BorderWidth</entry>
 117       <entry>Dimension</entry>
 118       <entry></entry>
 119       <entry>1</entry>
 120     </row>
 121     <row>
 122       <entry>callback</entry>
 123       <entry>Callback</entry>
 124       <entry>XtCallbackList</entry>
 125       <entry></entry>
 126       <entry>NULL</entry>
 127     </row>
 128     <row>
 129       <entry>colormap</entry>
 130       <entry>Colormap</entry>
 131       <entry>Colormap</entry>
 132       <entry></entry>
 133       <entry>Parent's Colormap</entry>
 134     </row>
 135     <row>
 136       <entry>cornerRoundPercent</entry>
 137       <entry>CornerRoundPercent</entry>
 138       <entry>Dimension</entry>
 139       <entry></entry>
 140       <entry>25</entry>
 141     </row>
 142     <row>
 143       <entry>cursor</entry>
 144       <entry>Cursor</entry>
 145       <entry>Cursor</entry>
 146       <entry></entry>
 147       <entry>None</entry>
 148     </row>
 149     <row>
 150       <entry>cursorName</entry>
 151       <entry>Cursor</entry>
 152       <entry>String</entry>
 153       <entry></entry>
 154       <entry>NULL</entry>
 155     </row>
 156     <row>
 157       <entry>depth</entry>
 158       <entry>Depth</entry>
 159       <entry>int</entry>
 160       <entry>C</entry>
 161       <entry>Parent's Depth</entry>
 162     </row>
 163     <row>
 164       <entry>destroyCallback</entry>
 165       <entry>Callback</entry>
 166       <entry>XtCallbackList</entry>
 167       <entry></entry>
 168       <entry>NULL</entry>
 169     </row>
 170     <row>
 171       <entry>encoding</entry>
 172       <entry>Encoding</entry>
 173       <entry>UnsignedChar</entry>
 174       <entry></entry>
 175       <entry>XawTextEncoding8bit</entry>
 176     </row>
 177     <row>
 178       <entry>font</entry>
 179       <entry>Font</entry>
 180       <entry>XFontStruct</entry>
 181       <entry></entry>
 182       <entry>XtDefaultFont</entry>
 183     </row>
 184     <row>
 185       <entry>foreground</entry>
 186       <entry>Foreground</entry>
 187       <entry>Pixel</entry>
 188       <entry></entry>
 189       <entry>XtDefaultForeground</entry>
 190     </row>
 191     <row>
 192       <entry>height</entry>
 193       <entry>Height</entry>
 194       <entry>Dimension</entry>
 195       <entry>A</entry>
 196       <entry>graphic height + 2 * <function>internalHeight</function></entry>
 197     </row>
 198     <row>
 199       <entry>highlightThickness</entry>
 200       <entry>Thickness</entry>
 201       <entry>Dimension</entry>
 202       <entry>A</entry>
 203       <entry>2 (0 if Shaped)</entry>
 204     </row>
 205     <row>
 206       <entry>insensitiveBorder</entry>
 207       <entry>Insensitive</entry>
 208       <entry>Pixmap</entry>
 209       <entry></entry>
 210       <entry>GreyPixmap</entry>
 211     </row>
 212     <row>
 213       <entry>internalHeight</entry>
 214       <entry>Height</entry>
 215       <entry>Dimension</entry>
 216       <entry></entry>
 217       <entry>2</entry>
 218     </row>
 219     <row>
 220       <entry>internalWidth</entry>
 221       <entry>Width</entry>
 222       <entry>Dimension</entry>
 223       <entry></entry>
 224       <entry>4</entry>
 225     </row>
 226     <row>
 227       <entry>international</entry>
 228       <entry>International</entry>
 229       <entry>Boolean</entry>
 230       <entry>C</entry>
 231       <entry>False</entry>
 232     </row>
 233     <row>
 234       <entry>justify</entry>
 235       <entry>Justify</entry>
 236       <entry>Justify</entry>
 237       <entry></entry>
 238       <entry>XtJustifyCenter (center)</entry>
 239     </row>
 240     <row>
 241       <entry>label</entry>
 242       <entry>Label</entry>
 243       <entry>String</entry>
 244       <entry></entry>
 245       <entry>name of widget</entry>
 246     </row>
 247     <row>
 248       <entry>leftBitmap</entry>
 249       <entry>LeftBitmap</entry>
 250       <entry>Bitmap</entry>
 251       <entry></entry>
 252       <entry>None</entry>
 253     </row>
 254     <row>
 255       <entry>mappedWhenManaged</entry>
 256       <entry>MappedWhenManaged</entry>
 257       <entry>Boolean</entry>
 258       <entry></entry>
 259       <entry>True</entry>
 260     </row>
 261     <row>
 262       <entry>pointerColor</entry>
 263       <entry>Foreground</entry>
 264       <entry>Pixel</entry>
 265       <entry></entry>
 266       <entry>XtDefaultForeground</entry>
 267     </row>
 268     <row>
 269       <entry>pointerColorBackground</entry>
 270       <entry>Background</entry>
 271       <entry>Pixel</entry>
 272       <entry></entry>
 273       <entry>XtDefaultBackground</entry>
 274     </row>
 275     <row>
 276       <entry>resize</entry>
 277       <entry>Resize</entry>
 278       <entry>Boolean</entry>
 279       <entry></entry>
 280       <entry>True</entry>
 281     </row>
 282     <row>
 283       <entry>screen</entry>
 284       <entry>Screen</entry>
 285       <entry>Screen</entry>
 286       <entry>R</entry>
 287       <entry>Parent's Screen</entry>
 288     </row>
 289     <row>
 290       <entry>sensitive</entry>
 291       <entry>Sensitive</entry>
 292       <entry>Boolean</entry>
 293       <entry></entry>
 294       <entry>True</entry>
 295     </row>
 296     <row>
 297       <entry>shapeStyle</entry>
 298       <entry>ShapeStyle</entry>
 299       <entry>ShapeStyle</entry>
 300       <entry></entry>
 301       <entry>Rectangle</entry>
 302     </row>
 303     <row>
 304       <entry>translations</entry>
 305       <entry>Translations</entry>
 306       <entry>TranslationTable</entry>
 307       <entry></entry>
 308       <entry>See below</entry>
 309     </row>
 310     <row>
 311       <entry>width</entry>
 312       <entry>Width</entry>
 313       <entry>Dimension</entry>
 314       <entry>A</entry>
 315       <entry>graphic width + 2 * <function>internalWidth</function></entry>
 316     </row>
 317     <row>
 318       <entry>x</entry>
 319       <entry>Position</entry>
 320       <entry>Position</entry>
 321       <entry></entry>
 322       <entry>0</entry>
 323     </row>
 324     <row>
 325       <entry>y</entry>
 326       <entry>Position</entry>
 327       <entry>Position</entry>
 328       <entry></entry>
 329       <entry>0</entry>
 330     </row>
 331     <row>
 332       <entry>_</entry>
 333     </row>
 334   </tbody>
 335   </tgroup>
 336 </informaltable>
 337 \" Resource Descriptions
 338 <!-- .Ac -->
 339 <!-- .As -->
 340 <!-- .Bg -->
 341 <!-- .Gp -->
 342 <!-- .Bm -->
 343 <!-- .Bc -->
 344 <!-- .Bp -->
 345 <!-- .Bw -->
 346 <!-- .Cb Bold -->
 347 <!-- .Cm -->
 348 <!-- .Cr Bold -->
 349 <!-- .Cu -->
 350 <!-- .Cn -->
 351 <!-- .Dp -->
 352 <!-- .Dc -->
 353 <!-- .Le -->
 354 <!-- .Lf -->
 355 <!-- .Ls -->
 356 <!-- .Lg -->
 357 <!-- .Hw -->
 358 <!-- .Ht Bold -->
 359 <!-- .Ib -->
 360 <!-- .Ih -->
 361 <!-- .In -->
 362 <!-- .Ju -->
 363 <!-- .La -->
 364 <!-- .Ll -->
 365 <!-- .Mm -->
 366 <!-- .Pf -->
 367 <!-- .Pb -->
 368 <!-- .Re -->
 369 <!-- .Sc -->
 370 <!-- .Se -->
 371 <!-- .Ss Bold -->
 372 <!-- .Tr -->
 373 <!-- .Xy -->
 374 </para>
 375 </sect2>
 376 <sect2 id="Command_Actions">
 377 <title>Command Actions</title>
 378 <!-- .IN "Command widget" "actions" -->
 379 <para>
 380 <!-- .LP -->
 381 The Command widget supports the following actions:
 382 </para>
 383 <itemizedlist>
 384   <listitem>
 385     <para>
 386 Switching the button's interior between the foreground and background
 387 colors with <function>set</function>, <function>unset</function>, and <function>reset</function>.
 388     </para>
 389   </listitem>
 390   <listitem>
 391     <para>
 392 Processing application callbacks with <function>notify</function>
 393     </para>
 394   </listitem>
 395   <listitem>
 396     <para>
 397 Switching the internal border between highlighted
 398 and unhighlighted states with <function>highlight</function> and <function>unhighlight</function>
 399     </para>
 400   </listitem>
 401 </itemizedlist>
 402 <para>
 403 <!-- .LP -->
 404 <!-- .IN "Command widget" "translation bindings" -->
 405 The following are the default translation bindings used by the
 406 Command widget:
 407 </para>
 408 <para>
 409 <!-- .LP -->
 410 <literallayout class="monospaced">
 411 <!-- .TA .5i 2.25i -->
 412 <!-- .ta .5i 2.25i -->
 413         &lt;EnterWindow&gt;:    highlight(\|)
 414         &lt;LeaveWindow&gt;:    reset(\|)
 415         &lt;Btn1Down&gt;:       set(\|)
 416         &lt;Btn1Up&gt;: notify(\|) unset(\|)
 417 </literallayout>
 418 </para>
 419 <para>
 420 <!-- .LP -->
 421 The full list of actions supported by Command is:
 422 <variablelist>
 423   <varlistentry>
 424     <term>
 425       <function>highlight</function>(<function>condition</function>)
 426     </term>
 427     <listitem>
 428       <para>
 429 Displays the internal highlight border in the color (<function>foreground</function>
 430 or <function>background</function> ) that contrasts with the interior color of the
 431 Command widget.  The conditions <function>WhenUnset</function> and <function>Always</function> are
 432 understood by this action procedure.  If no argument is passed,
 433 <function>WhenUnset</function> is assumed.
 434       </para>
 435     </listitem>
 436   </varlistentry>
 437   <varlistentry>
 438     <term>
 439       <function>unhighlight</function>(\|)
 440     </term>
 441     <listitem>
 442       <para>
 443 Displays the internal highlight border in the color (<function>foreground</function>
 444 or <function>background</function> ) that matches the interior color of the
 445 Command widget.
 446       </para>
 447     </listitem>
 448   </varlistentry>
 449   <varlistentry>
 450     <term>
 451       <function>set</function>(\|)
 452     </term>
 453     <listitem>
 454       <para>
 455 Enters the <function>set</function> state, in which <function>notify</function> is possible.  This
 456 action causes the button to display its interior in the
 457 <function>foreground</function> color.  The label or bitmap is displayed in the
 458 <function>background</function> color.
 459       </para>
 460     </listitem>
 461   </varlistentry>
 462   <varlistentry>
 463     <term>
 464       <function>unset</function>(\|)
 465     </term>
 466     <listitem>
 467       <para>
 468 Cancels the <emphasis remap='I'>set</emphasis> state and displays the interior of the button in the
 469 <function>background</function> color.  The label or bitmap is displayed in the
 470 <function>foreground</function> color.
 471       </para>
 472     </listitem>
 473   </varlistentry>
 474   <varlistentry>
 475     <term>
 476       <function>reset</function>(\|)
 477     </term>
 478     <listitem>
 479       <para>
 480 Cancels any <emphasis remap='I'>set</emphasis> or <emphasis remap='I'>highlight</emphasis> and displays the interior of the
 481 button in the <function>background</function> color, with the label or bitmap displayed
 482 in the <function>foreground</function> color.
 483       </para>
 484     </listitem>
 485   </varlistentry>
 486   <varlistentry>
 487     <term>
 488       <function>notify</function>(\|)
 489     </term>
 490     <listitem>
 491       <para>
 492 When the button is in the <function>set</function> state this action calls all functions in
 493 the callback list named by the <function>callback</function> resource.  The value of
 494 the <emphasis remap='I'>call_data</emphasis> argument passed to these functions is undefined.
 495     </para>
 496   </listitem>
 497   </varlistentry>
 498 </variablelist>
 499 </para>
 500 <para>
 501 <!-- .LP -->
 502 A very common alternative to registering callbacks is to augment a
 503 Command's translations with an action performing the desired
 504 function.  This often takes the form of:
 505 </para>
 506 <para>
 507 <!-- .LP -->
 508 <literallayout class="monospaced">
 509 <!-- .TA .5i 2.25i -->
 510 <!-- .ta .5i 2.25i -->
 511 *Myapp*save.translations: #augment &lt;Btn1Down&gt;,&lt;Btn1Up&gt;: Save()
 512 </literallayout>
 513 </para>
 514 <para>
 515 <!-- .LP -->
 516 <!-- .NT -->
 517 When a bitmap of depth greater that one (1) is specified the
 518 <emphasis remap='I'>set</emphasis>(), <emphasis remap='I'>unset</emphasis>(), and <emphasis remap='I'>reset</emphasis>() actions have no effect,
 519 since there are no foreground and background colors used in a
 520 multi-plane pixmap.
 521 <!-- .NE -->
 522
 523 </para>
 524 </sect2>
 525 </sect1>