1<sect1 id="MenuButton_Widget"> 2<title>MenuButton Widget</title> 3<!-- .XS --> 4<!-- MenuButton Widget --> 5<!-- .XE --> 6<indexterm significance="preferred"><primary>MenuButton widget</primary></indexterm> 7<!-- .sp --> 8<literallayout class="monospaced"> 9<!-- .TA 2.0i --> 10<!-- .ta 2.0i --> 11Application Header file <X11/Xaw/MenuButton.h> 12<indexterm><primary>MenuButton.h</primary></indexterm> 13Class Header file <X11/Xaw/MenuButtonP.h> 14<indexterm><primary>MenuButtonP.h</primary></indexterm> 15Class menuButtonWidgetClass 16<indexterm><primary>menuButtonWidgetClass</primary></indexterm> 17Class Name MenuButton 18<indexterm><primary>MenuButton widget</primary><secondary>class name</secondary></indexterm> 19Superclass Command 20</literallayout> 21<para> 22<!-- .LP --> 23<!-- .sp --> 24The MenuButton widget is an area, often rectangular, 25that displays a graphic. The graphic may be a text 26string containing multiple lines of characters in an 8 27bit 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 29a <emphasis remap='I'>fontset</emphasis>). The graphic may also be a bitmap or 30pixmap. 31</para> 32<para> 33<!-- .LP --> 34When the pointer cursor is on a MenuButton widget, the 35MenuButton becomes highlighted by drawing a rectangle 36around its perimeter. This highlighting indicates 37that the MenuButton is ready for selection. When a 38pointer button is pressed, the MenuButton widget will 39pop up the menu named in the <function>menuName</function> resource. 40</para> 41<sect2 id="MenuButton::Resources"> 42<title>Resources</title> 43<para> 44<!-- .LP --> 45When creating a MenuButton widget instance, 46the following resources are retrieved from the argument list 47or from the resource database: 48</para> 49<para> 50<!-- .LP --> 51<indexterm><primary>MenuButton widget</primary><secondary>resources</secondary></indexterm> 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> 388The name of a popup shell to popup as a menu. The MenuButton 389will search for this name using <function>XtNameToWidget</function> starting 390with itself as the reference widget. If the search is 391unsuccessful the widget will continue up the widget tree using 392each of its ancestors as the reference widget passed to 393<function>XtNameToWidget</function>. If no widget of called <function>menuName</function> is 394found by this algorithm, the widget will print a warning message 395and give up. When the menu is found it will be popped up 396exclusive and spring_loaded. The MenuButton widget does not 397copy the value of this resource into newly allocated memory. The 398application programmer must pass the resource value in 399nonvolatile 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</sect2> 414<sect2 id="MenuButton_Actions"> 415<title>MenuButton Actions</title> 416<indexterm><primary>MenuButton widget</primary><secondary>actions</secondary></indexterm> 417<para> 418<!-- .LP --> 419The MenuButton widget supports the following actions: 420</para> 421<itemizedlist> 422 <listitem> 423 <para> 424Switching the button between the foreground and background 425colors with <function>set</function> and <function>unset</function> 426 </para> 427 </listitem> 428 <listitem> 429 <para> 430Processing application callbacks with <function>notify</function> 431 </para> 432 </listitem> 433 <listitem> 434 <para> 435Switching the internal border between highlighted 436and unhighlighted states with <function>highlight</function> and <function>unhighlight</function> 437 </para> 438 </listitem> 439 <listitem> 440 <para> 441Popping up a menu with <function>PopupMenu</function> 442 </para> 443 </listitem> 444</itemizedlist> 445<para> 446<!-- .LP --> 447The following are the default translation bindings used by the 448MenuButton widget: 449</para> 450<para> 451<!-- .LP --> 452<!-- .sp --> 453<literallayout class="monospaced"> 454<!-- .TA .5i 2.25i --> 455<!-- .ta .5i 2.25i --> 456 <EnterWindow>: highlight( ) 457 <LeaveWindow>: reset( ) 458 <BtnDown>: reset( ) PopupMenu(\) 459</literallayout> 460</para> 461</sect2> 462<sect2 id='MenuButton_Actions_b'> 463<title>MenuButton Actions</title> 464<para> 465<!-- .LP --> 466The 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> 474Displays the internal highlight border in the color (<function>foreground</function> 475or <function>background</function> ) that contrasts with the interior color of the 476Command widget. The conditions <function>WhenUnset</function> and <function>Always</function> are 477understood 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> 488Displays the internal highlight border in the color (<function>XtNforeground</function> 489or <function>background</function> ) that matches the interior color of the 490MenuButton widget. 491 </para> 492 </listitem> 493 </varlistentry> 494 <varlistentry> 495 <term> 496 <function>set</function>( ) 497 </term> 498 <listitem> 499 <para> 500Enters the <function>set</function> state, in which <function>notify</function> is possible. This 501action 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> 513Cancels 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> 525Cancels any <function>set</function> or <function>highlight</function> and displays the interior of the 526button 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> 537When the button is in the <function>set</function> state this action calls all functions in 538the callback list named by the <function>callback</function> resource. The value of 539the 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> 549Pops up the menu specified by the <function>menuName</function> resource. 550 </para> 551 </listitem> 552 </varlistentry> 553</variablelist> 554</para> 555<para> 556<!-- .LP --> 557The MenuButton widget does not place a server grab on itself. 558Instead, PopupMenu is registered as a grab action. 559As a result, clients which popup menus without using XtMenuPopup 560or MenuPopup or PopupMenu in translations will fail to have a grab active. 561They should make a call to XtRegisterGrabAction on the appropriate action 562in the application initialization routine, or use a different translation. 563<!-- .bp --> 564 565</para> 566</sect2> 567</sect1> 568