specs/CH4.xml

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