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

</para>
</sect4>
</sect3>
</sect2>