specs/SimpleMenu.xml

   1 <sect2 id="SimpleMenu_Widget">
   2 <title>SimpleMenu Widget</title>
   3 <!-- .XS -->
   4 <!--    SimpleMenu Widget -->
   5 <!-- .XE -->
   6 <!-- .IN "SimpleMenu widget" "" "@DEF@" -->
   7 <literallayout class="monospaced">
   8 <!-- .TA 2.0i -->
   9 <!-- .ta 2.0i -->
  10 <!-- .sp -->
  11 Application Header file &lt;X11/Xaw/SimpleMenu.h&gt;
  12 <!-- .IN "SimpleMenu.h" "" -->
  13 Class Header file       &lt;X11/Xaw/SimpleMenP.h&gt;
  14 <!-- .IN "SimpleMenP.h" "" -->
  15 Class           simpleMenuWidgetClass
  16 <!-- .IN "simpleMenuWidgetClass" "" -->
  17 Class Name      SimpleMenu
  18 <!-- .IN "SimpleMenu widget" "class name" -->
  19 Superclass      OverrideShell
  20 <!-- .sp -->
  21 </literallayout>
  22 <para>
  23 <!-- .LP -->
  24 The SimpleMenu widget is a container for the menu entries.  It is a
  25 direct subclass of shell, and is should be created with
  26 <function>XtCreatePopupShell</function>, not <function>XtCreateManagedWidget</function>.  This is the
  27 only part of the menu that
  28 actually is associated with a window.  The SimpleMenu serves as the glue to bind
  29 the individual menu entries together into a menu.
  30 </para>
  31 <sect3 id="Resources">
  32 <title>Resources</title>
  33 <para>
  34 <!-- .LP -->
  35 <!-- .IN "SimpleMenu widget" "resources" -->
  36 </para>
  37 <para>
  38 <!-- .LP -->
  39 The resources associated with the SimpleMenu widget control aspects
  40 that will affect the entire menu.
  41 <informaltable>
  42   <tgroup cols='5' align='center'>
  43   <colspec colname='c1'/>
  44   <colspec colname='c2'/>
  45   <colspec colname='c3'/>
  46   <colspec colname='c4'/>
  47   <colspec colname='c5'/>
  48   <thead>
  49     <row>
  50       <entry>Name</entry>
  51       <entry>Class</entry>
  52       <entry>Type</entry>
  53       <entry>Notes</entry>
  54       <entry>Default Value</entry>
  55     </row>
  56   </thead>
  57   <tbody>
  58     <row>
  59       <entry>accelerators</entry>
  60       <entry>Accelerators</entry>
  61       <entry>AcceleratorTable</entry>
  62       <entry></entry>
  63       <entry>NULL</entry>
  64     </row>
  65     <row>
  66       <entry>ancestorSensitive</entry>
  67       <entry>AncestorSensitive</entry>
  68       <entry>Boolean</entry>
  69       <entry>D</entry>
  70       <entry>True</entry>
  71     </row>
  72     <row>
  73       <entry>allowShellResize</entry>
  74       <entry>AllowShellResize</entry>
  75       <entry>Boolean</entry>
  76       <entry></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>backingStore</entry>
  95       <entry>BackingStore</entry>
  96       <entry>BackingStore</entry>
  97       <entry></entry>
  98       <entry>see below</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>bottomMargin</entry>
 123       <entry>VerticalMargins</entry>
 124       <entry>Dimension</entry>
 125       <entry></entry>
 126       <entry>0</entry>
 127     </row>
 128     <row>
 129       <entry>children</entry>
 130       <entry>ReadOnly</entry>
 131       <entry>WidgetList</entry>
 132       <entry>R</entry>
 133       <entry>NULL</entry>
 134     </row>
 135     <row>
 136       <entry>createPopupChildProc</entry>
 137       <entry>CreatePopupChildProc</entry>
 138       <entry>Function</entry>
 139       <entry></entry>
 140       <entry>NULL</entry>
 141     </row>
 142     <row>
 143       <entry>colormap</entry>
 144       <entry>Colormap</entry>
 145       <entry>Colormap</entry>
 146       <entry></entry>
 147       <entry>Parent's Colormap</entry>
 148     </row>
 149     <row>
 150       <entry>cursor</entry>
 151       <entry>Cursor</entry>
 152       <entry>Cursor</entry>
 153       <entry></entry>
 154       <entry>None</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>geometry</entry>
 172       <entry>Geometry</entry>
 173       <entry>String</entry>
 174       <entry></entry>
 175       <entry>NULL</entry>
 176     </row>
 177     <row>
 178       <entry>height</entry>
 179       <entry>Height</entry>
 180       <entry>Dimension</entry>
 181       <entry></entry>
 182       <entry>Enough space to contain all entries</entry>
 183     </row>
 184     <row>
 185       <entry>label</entry>
 186       <entry>Label</entry>
 187       <entry>String</entry>
 188       <entry></entry>
 189       <entry>NULL</entry>
 190     </row>
 191     <row>
 192       <entry>labelClass</entry>
 193       <entry>LabelClass</entry>
 194       <entry>Pointer</entry>
 195       <entry></entry>
 196       <entry>SmeBSBObjectClass</entry>
 197     </row>
 198     <row>
 199       <entry>mappedWhenManaged</entry>
 200       <entry>MappedWhenManaged</entry>
 201       <entry>Boolean</entry>
 202       <entry></entry>
 203       <entry>True</entry>
 204     </row>
 205     <row>
 206       <entry>menuOnScreen</entry>
 207       <entry>MenuOnScreen</entry>
 208       <entry>Boolean</entry>
 209       <entry></entry>
 210       <entry>True</entry>
 211     </row>
 212     <row>
 213       <entry>numChildren</entry>
 214       <entry>ReadOnly</entry>
 215       <entry>Cardinal</entry>
 216       <entry>R</entry>
 217       <entry>0</entry>
 218     </row>
 219     <row>
 220       <entry>overrideRedirect</entry>
 221       <entry>OverrideRedirect</entry>
 222       <entry>Boolean</entry>
 223       <entry></entry>
 224       <entry>True</entry>
 225     </row>
 226     <row>
 227       <entry>popdownCallback</entry>
 228       <entry>Callback</entry>
 229       <entry>XtCallbackList</entry>
 230       <entry></entry>
 231       <entry>NULL</entry>
 232     </row>
 233     <row>
 234       <entry>popupCallback</entry>
 235       <entry>Callback</entry>
 236       <entry>XtCallbackList</entry>
 237       <entry></entry>
 238       <entry>NULL</entry>
 239     </row>
 240     <row>
 241       <entry>popupOnEntry</entry>
 242       <entry>PopupOnEntry</entry>
 243       <entry>Widget</entry>
 244       <entry>A</entry>
 245       <entry>Label or first entry</entry>
 246     </row>
 247     <row>
 248       <entry>rowHeight</entry>
 249       <entry>RowHeight</entry>
 250       <entry>Dimension</entry>
 251       <entry></entry>
 252       <entry>0</entry>
 253     </row>
 254     <row>
 255       <entry>saveUnder</entry>
 256       <entry>SaveUnder</entry>
 257       <entry>Boolean</entry>
 258       <entry></entry>
 259       <entry>False</entry>
 260     </row>
 261     <row>
 262       <entry>screen</entry>
 263       <entry>Screen</entry>
 264       <entry>Screen</entry>
 265       <entry>R</entry>
 266       <entry>Parent's Screen</entry>
 267     </row>
 268     <row>
 269       <entry>sensitive</entry>
 270       <entry>Sensitive</entry>
 271       <entry>Boolean</entry>
 272       <entry></entry>
 273       <entry>True</entry>
 274     </row>
 275     <row>
 276       <entry>topMargin</entry>
 277       <entry>VerticalMargins</entry>
 278       <entry>Dimension</entry>
 279       <entry></entry>
 280       <entry>0</entry>
 281     </row>
 282     <row>
 283       <entry>translations</entry>
 284       <entry>Translations</entry>
 285       <entry>TranslationTable</entry>
 286       <entry></entry>
 287       <entry>See below</entry>
 288     </row>
 289     <row>
 290       <entry>visual</entry>
 291       <entry>Visual</entry>
 292       <entry>Visual</entry>
 293       <entry></entry>
 294       <entry>CopyFromParent</entry>
 295     </row>
 296     <row>
 297       <entry>width</entry>
 298       <entry>Width</entry>
 299       <entry>Dimension</entry>
 300       <entry></entry>
 301       <entry>Width of widest entry</entry>
 302     </row>
 303     <row>
 304       <entry>x</entry>
 305       <entry>Position</entry>
 306       <entry>Position</entry>
 307       <entry></entry>
 308       <entry>0</entry>
 309     </row>
 310     <row>
 311       <entry>y</entry>
 312       <entry>Position</entry>
 313       <entry>Position</entry>
 314       <entry></entry>
 315       <entry>0</entry>
 316     </row>
 317   </tbody>
 318   </tgroup>
 319 </informaltable>
 320 <!-- .Ac -->
 321 <!-- .As -->
 322 <variablelist>
 323   <varlistentry>
 324     <term>
 325       <function>backingStore</function>
 326     </term>
 327     <listitem>
 328       <para>
 329 <!-- .IN "conversions" "BackingStore" -->
 330 Determines what type of backing store will be used for the menu.  Legal
 331 values for this resource are <function>NotUseful</function>, <function>WhenMapped</function>, and
 332 <function>Always</function>.  These values are the backing-store integers defined in
 333 &lt;X11/X.h&gt;.
 334 <!-- .Rs "notUseful, whenMapped, always, \fPand\fP default" -->
 335 If <function>default</function> is specified (the default behavior) the server will use
 336 whatever it thinks is appropriate.
 337 <!-- .Bg -->
 338 <!-- .Gp -->
 339 <!-- .Bc -->
 340 <!-- .Bp -->
 341 <!-- .Bw -->
 342       </para>
 343     </listitem>
 344   </varlistentry>
 345   <varlistentry>
 346     <term>
 347       <function>bottomMargin</function>
 348     </term>
 349     <listitem>
 350       <para>
 351 <!-- .br -->
 352 <!-- .ns -->
 353       </para>
 354     </listitem>
 355   </varlistentry>
 356   <varlistentry>
 357     <term>
 358       <function>topMargin</function>
 359     </term>
 360     <listitem>
 361       <para>
 362 The amount of space between the top or bottom of the menu and the menu entry
 363 closest to that edge.
 364 <!-- .Ch -->
 365 <!-- .Cm -->
 366       </para>
 367     </listitem>
 368   </varlistentry>
 369   <varlistentry>
 370     <term>
 371       <function>cursor</function>
 372     </term>
 373     <listitem>
 374       <para>
 375 The shape of the mouse pointer whenever it is in this widget.
 376 <!-- .Dp -->
 377 <!-- .Dc -->
 378       </para>
 379     </listitem>
 380   </varlistentry>
 381   <varlistentry>
 382     <term>
 383       geometry
 384     </term>
 385     <listitem>
 386       <para>
 387 If this resource is specified it will override the x, y, width and
 388 height of this widget.  The format of this string is
 389 [&lt;<emphasis remap='I'>width</emphasis>&gt;x&lt;<emphasis remap='I'>height</emphasis>&gt;][{+ -} &lt;<emphasis remap='I'>xoffset</emphasis>&gt; {+ -}&lt;<emphasis remap='I'>yoffset</emphasis>&gt;].
 390 <!-- .Hw -->
 391       </para>
 392     </listitem>
 393   </varlistentry>
 394   <varlistentry>
 395     <term>
 396       <function>label</function>
 397     </term>
 398     <listitem>
 399       <para>
 400 This label will be placed at the top of the SimpleMenu, and may not be
 401 highlighted.  The name of the
 402 label object is <function>menuLabel</function>.  Using this name it is possible to
 403 modify the label's attributes through the resource database.  When the label
 404 is created, the <function>label</function> is hard coded to the value of <function>label</function>, and
 405 <function>justify</function> is hard coded as <function>XtJustifyCenter</function>.
 406       </para>
 407     </listitem>
 408   </varlistentry>
 409   <varlistentry>
 410     <term>
 411       <function>labelClass</function>
 412     </term>
 413     <listitem>
 414       <para>
 415 Specifies the type of Sme object created as the menu label.
 416 <!-- .Mm -->
 417       </para>
 418     </listitem>
 419   </varlistentry>
 420   <varlistentry>
 421     <term>
 422       <function>menuOnScreen</function>
 423     </term>
 424     <listitem>
 425       <para>
 426 If the menu is automatically positioned under the cursor with the
 427 <function>XawPositionSimpleMenu</function> action, and this resource is <function>True</function>,
 428 then the menu will always be fully visible on the screen.
 429 <!-- .Nc -->
 430       </para>
 431     </listitem>
 432   </varlistentry>
 433   <varlistentry>
 434     <term>
 435       overrideRedirect
 436     </term>
 437     <listitem>
 438       <para>
 439 Determines the value of the override_redirect attribute of the
 440 SimpleMenu's window.  The override_redirect attribute of a window
 441 determines whether or not a window manager may interpose itself between
 442 this window and the root window of the display.  For more information
 443 see the <emphasis remap='I'>Interclient Communications Conventions Manual</emphasis>.
 444       </para>
 445     </listitem>
 446   </varlistentry>
 447   <varlistentry>
 448     <term>
 449       popdownCallback
 450     </term>
 451     <listitem>
 452       <para>
 453 <!-- .br -->
 454 <!-- .ns -->
 455       </para>
 456     </listitem>
 457   </varlistentry>
 458   <varlistentry>
 459     <term>
 460       popupCallback
 461     </term>
 462     <listitem>
 463       <para>
 464 These callback functions are called by the Xt Intrinsics whenever the
 465 shell is popped up or down (See <emphasis remap='I'>(xT</emphasis> for details).
 466       </para>
 467     </listitem>
 468   </varlistentry>
 469   <varlistentry>
 470     <term>
 471       <function>popupOnEntry</function>
 472     </term>
 473     <listitem>
 474       <para>
 475 The <function>XawPositionSimpleMenu</function> action will, by default, popup the
 476 SimpleMenu with its label (or first entry) directly under the
 477 pointer.  To popup the menu under
 478 another entry, set this resource to the menu entry that should be
 479 under the pointer, when the menu is popped up.  This allows the
 480 application to offer the user a default menu entry that can be selected
 481 with out moving the pointer.
 482       </para>
 483     </listitem>
 484   </varlistentry>
 485   <varlistentry>
 486     <term>
 487       <function>rowHeight</function>
 488     </term>
 489     <listitem>
 490       <para>
 491 If this resources is zero (the default) then each menu entry will be
 492 given its desired height.  If this resource has any other value then
 493 all menu entries will be forced to be <function>rowHeight</function> pixels high.
 494       </para>
 495     </listitem>
 496   </varlistentry>
 497   <varlistentry>
 498     <term>
 499       saveUnder
 500     </term>
 501     <listitem>
 502       <para>
 503 If this is <function>True</function> then save unders will be active on the menu's window.
 504 <!-- .Sc -->
 505 <!-- .Se -->
 506 <!-- .Tr -->
 507 <!-- .Xy -->
 508     </para>
 509   </listitem>
 510   </varlistentry>
 511 </variablelist>
 512 </para>
 513 </sect3>
 514 <sect3 id="SimpleMenu_Actions">
 515 <title>SimpleMenu Actions</title>
 516 <!-- .IN "SimpleMenu widget" "actions" -->
 517 <para>
 518 <!-- .LP -->
 519 The SimpleMenu widget supports the following actions:
 520 </para>
 521 <itemizedlist>
 522   <listitem>
 523     <para>
 524 Switching the entry under the mouse pointer between
 525 the foreground and background colors with <function>highlight</function>
 526 and <function>unhighlight</function>
 527     </para>
 528   </listitem>
 529   <listitem>
 530     <para>
 531 Processing menu entry callbacks with <function>notify</function>
 532 <!-- .sp -->
 533     </para>
 534   </listitem>
 535 </itemizedlist>
 536 <para>
 537 <!-- .LP -->
 538 <!-- .IN "SimpleMenu widget" "default translations" -->
 539 The following are the default translation bindings used
 540 by the SimpleMenu widget:
 541 </para>
 542 <para>
 543 <!-- .LP -->
 544 <!-- .sp -->
 545 <literallayout class="monospaced">
 546 <!-- .TA .5i 2.25i -->
 547 <!-- .ta .5i 2.25i -->
 548         &lt;EnterWindow&gt;:    highlight(\|)
 549         &lt;LeaveWindow&gt;:    unhighlight(\|)
 550         &lt;BtnMotion&gt;:      highlight(\|)
 551         &lt;BtnUp&gt;:  MenuPopdown(\|) notify(\|) unhighlight(\|)
 552 </literallayout>
 553 <!-- .sp -->
 554 </para>
 555 <para>
 556 <!-- .LP -->
 557 <!-- .IN "SimpleMenu widget" "MenuPopdown routine" -->
 558 The user can pop down the menu without activating any of the callback
 559 functions by releasing the pointer button when no menu item is
 560 highlighted.
 561 <!-- .sp -->
 562 </para>
 563 <para>
 564 <!-- .LP -->
 565 The full list of actions supported by SimpleMenu is:
 566 <variablelist>
 567   <varlistentry>
 568     <term>
 569       <function>highlight</function>()
 570     </term>
 571     <listitem>
 572       <para>
 573 Highlight the menu entry that is currently under the pointer.
 574 Only a item that is highlighted will be notified when the <function>notify</function>
 575 action is invoked.  The look of a highlighted entry is determined by
 576 the menu entry.
 577       </para>
 578     </listitem>
 579   </varlistentry>
 580   <varlistentry>
 581     <term>
 582       <function>unhighlight</function>(\|)
 583     </term>
 584     <listitem>
 585       <para>
 586 Unhighlights the currently highlighted menu item, and returns it to
 587 its normal look.
 588       </para>
 589     </listitem>
 590   </varlistentry>
 591   <varlistentry>
 592     <term>
 593       <function>notify</function>(\|)
 594     </term>
 595     <listitem>
 596       <para>
 597 Notifies the menu entry that is currently highlighted that is has been
 598 selected.  It is the responsibility of the menu entry to take the
 599 appropriate action.
 600       </para>
 601     </listitem>
 602   </varlistentry>
 603   <varlistentry>
 604     <term>
 605       <function>MenuPopdown</function>(<emphasis remap='I'>menu</emphasis>)
 606     </term>
 607     <listitem>
 608       <para>
 609 This action is defined in <emphasis remap='I'>(xT</emphasis>.
 610 <!-- .IN "SimpleMenu widget" "MenuPopdown routine" -->
 611     </para>
 612   </listitem>
 613   </varlistentry>
 614 </variablelist>
 615 </para>
 616 </sect3>
 617 <sect3 id="Positioning_the_SimpleMenu">
 618 <title>Positioning the SimpleMenu</title>
 619 <!-- .IN "XawPositionSimpleMenu" "" "@DEF@" -->
 620 <!-- .IN "SimpleMenu widget" "positioning" "@DEF@" -->
 621 <para>
 622 <!-- .LP -->
 623 If the SimpleMenu widget is to be used as a pulldown menu then the
 624 MenuButton widget, or some other outside means should be used to place
 625 the menu when it is popped up.
 626 </para>
 627 <para>
 628 <!-- .LP -->
 629 If popup menus are desired it will be necessary to add the
 630 <function>XawPositionSimpleMenu</function> and <function>MenuPopup</function> actions to the
 631 translation table of the widget that will be popping up the menu.  The
 632 <function>MenuPopup</function> action is described in <emphasis remap='I'>(xT</emphasis>.
 633 <function>XawPositionSimpleMenu</function> is a global action procedure registered by
 634 the SimpleMenu widget when the first one is created or the convenience
 635 routine <function>XawSimpleMenuAddGlobalActions</function> is called.
 636 </para>
 637 <para>
 638 <!-- .LP -->
 639 Translation writers should be aware that Xt does not register grabs on
 640 ``don't care'' modifiers, and therefore the left hand side of the
 641 production should be written to exclude unspecified modifiers.
 642 For example these are the translations needed to popup some of
 643 <function>xterm's</function> menus:
 644 <!-- .sp -->
 645 </para>
 646 <para>
 647 <!-- .LP -->
 648 <literallayout class="monospaced">
 649 <!-- .TA .5i 2.25i -->
 650 <!-- .ta .5i 2.25i -->
 651         !Ctrl&lt;Btn1Down&gt;: XawPositionSimpleMenu(xterm) MenuPopup(xterm)
 652         !Ctrl&lt;Btn2Down&gt;: XawPositionSimpleMenu(modes) MenuPopup(modes)
 653 </literallayout>
 654 <!-- .sp 1 -->
 655 </para>
 656 <para>
 657 <!-- .LP -->
 658 <variablelist>
 659   <varlistentry>
 660     <term>
 661       <function>XawPositionSimpleMenu</function>(<emphasis remap='I'>menu</emphasis>)
 662     </term>
 663     <listitem>
 664       <para>
 665 The <function>XawPositionSimpleMenu</function> routine will search for the menu name
 666 passed to it using <function>XtNameToWidget</function> starting with the widget
 667 invoking the action as the reference widget.  If it is unsuccessful it
 668 will continue up the widget tree using each of the invoking widget's
 669 ancestors as the reference widget.  If it is still unsuccessful it will
 670 print a warning message and give up.  <function>XawPositionSimpleMenu</function> will
 671 position the menu directly under the pointer cursor.  The menu will be
 672 placed so that the pointer cursor is centered on the entry named by the
 673 <function>popupOnEntry</function> resource.  If the <function>menuOnScreen</function> resource is
 674 <function>True</function> then the menu will always be fully visible on the screen.
 675     </para>
 676   </listitem>
 677   </varlistentry>
 678 </variablelist>
 679 </para>
 680 </sect3>
 681 <sect3 id="Convenience_Routines">
 682 <title>Convenience Routines</title>
 683 <sect4 id="Registering_the_Global_Action_Routines">
 684 <title>Registering the Global Action Routines</title>
 685 <para>
 686 <!-- .LP -->
 687 <!-- .IN "XawPositionSimpleMenu" "" -->
 688 The <function>XawPositionSimpleMenu</function> action routine may often be invoked
 689 before any menus have been created.  This can occur when an
 690 application uses dynamic menu creation.  In these cases an application will
 691 need to register this global action routine by calling
 692 <function>XawSimpleMenuAddGlobalActions</function>:
 693 <!-- .IN "XawSimpleMenuAddGlobalActions" "" "@DEF@" -->
 694 <funcsynopsis>
 695 <funcprototype>
 696   <funcdef>void<function> XawSimpleMenuAddGlobalActions</function></funcdef>
 697   <paramdef>XtAppContext<parameter> app_con</parameter></paramdef>
 698 </funcprototype>
 699 </funcsynopsis>
 700 <!-- .FN -->
 701 <variablelist>
 702   <varlistentry>
 703     <term>
 704       <emphasis remap='I'>app_con</emphasis>
 705     </term>
 706     <listitem>
 707       <para>
 708 Specifies the application context in which this action should be registered.
 709     </para>
 710   </listitem>
 711   </varlistentry>
 712 </variablelist>
 713 </para>
 714 <para>
 715 <!-- .LP -->
 716 This function need only be called once per application and must be
 717 called before any widget that uses <function>XawPositionSimpleMenu</function> action
 718 is realized.
 719 </para>
 720 </sect4>
 721 <sect4 id="Getting_and_Clearing_the_Current_Menu_Entry">
 722 <title>Getting and Clearing the Current Menu Entry</title>
 723 <para>
 724 <!-- .LP -->
 725 To get the currently highlighted menu entry use
 726 <function>XawSimpleMenuGetActiveEntry</function>:
 727 <!-- .IN "XawSimpleMenuGetActiveEntry" "" "@DEF@" -->
 728 <funcsynopsis>
 729 <funcprototype>
 730   <funcdef>Widget<function> XawSimpleMenuGetActiveEntry</function></funcdef>
 731   <paramdef>Widget<parameter> w</parameter></paramdef>
 732 </funcprototype>
 733 </funcsynopsis>
 734 <!-- .FN -->
 735 <variablelist>
 736   <varlistentry>
 737     <term>
 738       <emphasis remap='I'>w</emphasis>
 739     </term>
 740     <listitem>
 741       <para>
 742 Specifies the SimpleMenu widget.
 743     </para>
 744   </listitem>
 745   </varlistentry>
 746 </variablelist>
 747 </para>
 748 <para>
 749 <!-- .LP -->
 750 This function returns the menu entry that is
 751 currently highlighted, or NULL if no entry is highlighted.
 752 </para>
 753 <para>
 754 <!-- .LP -->
 755 <!-- .sp -->
 756 To clear the SimpleMenu widget's internal information about the
 757 currently highlighted menu entry use
 758 <function>XawSimpleMenuClearActiveEntry</function>:
 759 <!-- .IN "XawSimpleMenuClearActiveEntry" "" "@DEF@" -->
 760 <funcsynopsis>
 761 <funcprototype>
 762   <funcdef>Widget<function> XawSimpleMenuClearActiveEntry</function></funcdef>
 763   <paramdef>Widget<parameter> w</parameter></paramdef>
 764 </funcprototype>
 765 </funcsynopsis>
 766 <!-- .FN -->
 767 <variablelist>
 768   <varlistentry>
 769     <term>
 770       <emphasis remap='I'>w</emphasis>
 771     </term>
 772     <listitem>
 773       <para>
 774 Specifies the SimpleMenu widget.
 775     </para>
 776   </listitem>
 777   </varlistentry>
 778 </variablelist>
 779 </para>
 780 <para>
 781 <!-- .LP -->
 782 This function unsets all internal references to the currently
 783 highlighted menu entry.  It does not <emphasis remap='I'>unhighlight</emphasis> or otherwise
 784 alter the appearance of the active entry.  This function is primarily
 785 for use by implementors of menu entries.
 786
 787 </para>
 788 </sect4>
 789 </sect3>
 790 </sect2>