specs/MenuButton.xml

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