1<chapter id='Menus'>
2<title>Menus</title>
3<para>
4The Athena widget set provides support for single paned non-hierarchical
5popup and pulldown menus.  Since menus are such a common user interface
6tool, support for them must be provided in even the most basic widget
7sets.  In menuing as in other areas, the Athena Widget Set provides only
8basic functionality.
9</para>
10<para>
11Menus in the Athena widget set are implemented as a menu container (the
12SimpleMenu widget) and a collection of objects that comprise the
13menu entries.  The SimpleMenu widget is itself a direct subclass of the
14OverrideShell widget class, so no other shell is necessary when
15creating a menu.  The managed children of a SimpleMenu must be
16subclasses of the Sme (Simple Menu Entry) object.
17</para>
18<para>
19The Athena widget set provides three classes of Sme objects that may be
20used to build menus.
21</para>
22<para>
23<variablelist>
24  <varlistentry>
25    <term>Sme</term>
26    <listitem>
27      <para>
28The base class of all menu entries.  It may be used as a menu entry
29itself to provide blank space in a menu.  "Sme" means "Simple Menu
30Entry."
31      </para>
32    </listitem>
33  </varlistentry>
34  <varlistentry>
35    <term>SmeBSB</term>
36    <listitem>
37      <para>
38This menu entry provides a selectable entry containing a text string.
39A bitmap may also be placed in the left and right margins.  "BSB" means
40"Bitmap String Bitmap."
41      </para>
42    </listitem>
43  </varlistentry>
44  <varlistentry>
45    <term>SmeLine</term>
46    <listitem>
47      <para>
48This menu entry provides an unselectable entry containing a separator line.
49      </para>
50    </listitem>
51  </varlistentry>
52</variablelist>
53</para>
54<para>
55The SimpleMenu widget informs the window manager that it should ignore
56its window by setting the <function>Override Redirect</function> flag.  This is the
57correct behavior for the press-drag-release style of menu operation.  If
58click-move-click or "pinable" menus are desired it is the
59responsibility of the application programmer, using the SimpleMenu
60resources, to inform the window manager of the menu.
61</para>
62<para>
63To allow easy creation of pulldown menus, a MenuButton widget is
64also provided as part of the Athena widget set.
65</para>
66<sect1 id="Using_the_Menus">
67<title>Using the Menus</title>
68<!-- .XS -->
69<!-- 	Using the Menus -->
70<!-- .XE -->
71<indexterm><primary>Menus</primary><secondary>using</secondary></indexterm>
72<para>
73<!-- .LP -->
74The default configuration for the menus is press-drag-release.
75The menus will typically be
76activated by clicking a pointer button while the pointer is over a
77MenuButton, causing the menu to appear in a fixed location relative to
78that button; this is a <function>pulldown</function> menu.  Menus may also be activated
79<indexterm><primary>Menus</primary><secondary>pulldown</secondary></indexterm>
80when a specific pointer and/or key sequence is used anywhere in the
81application; this is a <function>popup</function> menu (e.g. clicking Ctrl-&lt;pointer
82<indexterm><primary>Menus</primary><secondary>popup</secondary></indexterm>
83button 1&gt; in the common application <function>xterm</function>).  In this
84case the menu should be positioned under
85the cursor. Typically menus will be placed so the pointer cursor is on
86the first menu entry, or the last entry selected by the user.
87</para>
88<para>
89<!-- .LP -->
90The menu remains on the screen as long as the pointer button is held
91down.  Moving the pointer will highlight different menu items.
92If the pointer leaves the menu, or moves over an entry that cannot
93be selected then no menu entry will highlighted.  When the desired menu
94entry has been highlighted, releasing the pointer button removes the menu,
95and causes any mechanism associated with this entry to be invoked.
96
97</para>
98</sect1>
99<xi:include xmlns:xi="http://www.w3.org/2001/XInclude"  href="SimpleMenu.xml"/>
100<xi:include xmlns:xi="http://www.w3.org/2001/XInclude"  href="SmeBSB.xml"/>
101<xi:include xmlns:xi="http://www.w3.org/2001/XInclude"  href="SmeLine.xml"/>
102<xi:include xmlns:xi="http://www.w3.org/2001/XInclude"  href="Sme.xml"/>
103<xi:include xmlns:xi="http://www.w3.org/2001/XInclude"  href="MenuButton.xml"/>
104</chapter>
105