1XmMenuShell(library call)                            XmMenuShell(library call)
2
3
4

NAME

6       XmMenuShell — The MenuShell widget class
7

SYNOPSIS

9       #include <Xm/MenuShell.h>
10

DESCRIPTION

12       The MenuShell widget is a custom OverrideShell widget. An OverrideShell
13       widget bypasses mwm when displaying itself. It is designed specifically
14       to contain Popup or Pulldown menu panes.
15
16       Most  application  writers  never encounter this widget if they use the
17       menu-system convenience functions, XmCreatePopupMenu  or  XmCreatePull‐
18       down  Menu,  to  create a Popup or Pulldown menu pane.  The convenience
19       functions automatically create a MenuShell widget as the parent of  the
20       menu  pane.  However,  if  the  convenience functions are not used, the
21       application programmer must create  the  required  MenuShell.  In  this
22       case,  it is important to note that the parent of the MenuShell depends
23       on the type of menu system being built.
24
25          ·  If the MenuShell is  for  the  top-level  Popup  menu  pane,  the
26             MenuShell's  parent  must be the widget from which the Popup menu
27             pane is popped up.
28
29          ·  If the MenuShell is for a menu pane that is pulled  down  from  a
30             Popup  or another Pulldown menu pane, the MenuShell's parent must
31             be the Popup or Pulldown menu pane.
32
33          ·  If the MenuShell is for a menu pane that is pulled  down  from  a
34             MenuBar, the MenuShell's parent must be the MenuBar.
35
36          ·  If  the  MenuShell  is for a Pulldown menu pane in an OptionMenu,
37             the MenuShell's parent must be the OptionMenu's parent.
38
39       Setting XmNheight, XmNwidth, or XmNborderWidth for either  a  MenuShell
40       or  its  child  sets that resource to the same value in both the parent
41       and the child.  An application should always  specify  these  resources
42       for the child, not the parent.
43
44       For  the  managed  child of a MenuShell, regardless of the value of the
45       shell's XmNallowShellResize, setting XmNx or XmNy sets the  correspond‐
46       ing  resource  of  the  parent but does not change the child's position
47       relative to the parent.  XtGetValues  for  the  child's  XmNx  or  XmNy
48       yields  the  value  of the corresponding resource in the parent.  The x
49       and y-coordinates of the child's upper left outside corner relative  to
50       the parent's upper left inside corner are both 0 (zero) minus the value
51       of XmNborderWidth.
52
53       MenuShell uses the XmQTmenuSystem trait and holds  the  XmQTspecifyRen‐
54       derTable trait.
55
56   Classes
57       MenuShell  inherits  behavior, resources, and traits from Core, Compos‐
58       ite, Shell, and OverrideShell.
59
60       The class pointer is xmMenuShellWidgetClass.
61
62       The class name is XmMenuShell.
63
64   New Resources
65       MenuShell overrides the XmNallowShellResize  resource  in  Shell.   The
66       following  table defines a set of widget resources used by the program‐
67       mer to specify data. The programmer can also set  the  resource  values
68       for  the inherited classes to set attributes for this widget. To refer‐
69       ence a resource by name or by class in a .Xdefaults  file,  remove  the
70       XmN  or XmC prefix and use the remaining letters. To specify one of the
71       defined values for a resource in a .Xdefaults file, remove the Xm  pre‐
72       fix  and  use  the remaining letters (in either lowercase or uppercase,
73       but include any underscores between words).  The codes  in  the  access
74       column  indicate if the given resource can be set at creation time (C),
75       set by using XtSetValues (S), retrieved by using XtGetValues (G), or is
76       not applicable (N/A).
77
78       ┌───────────────────────────────────────────────────────────────────────────────────────┐
79       │                     │         XmMenuShell R│esource Set     │                 │        │
80Name                 Class                Type          Default         Access 
81       ├─────────────────────┼──────────────────────┼───────────────┼─────────────────┼────────┤
82       │XmNbuttonFontList    │ XmCButtonFontList    │ XmFontList    │ dynamic         │ CSG    │
83       ├─────────────────────┼──────────────────────┼───────────────┼─────────────────┼────────┤
84       │XmNbuttonRenderTable │ XmCButtonRenderTable │ XmRenderTable │ NULL            │ CSG    │
85       ├─────────────────────┼──────────────────────┼───────────────┼─────────────────┼────────┤
86       │XmNdefaultFontList   │ XmCDefaultFontList   │ XmFontList    │ dynamic         │ CG     │
87       ├─────────────────────┼──────────────────────┼───────────────┼─────────────────┼────────┤
88       │XmNlabelFontList     │ XmCLabelFontList     │ XmFontList    │ dynamic         │ CSG    │
89       ├─────────────────────┼──────────────────────┼───────────────┼─────────────────┼────────┤
90       │XmNlabelRenderTable  │ XmCLabelRenderTable  │ XmRenderTable │ NULL            │ CSG    │
91       ├─────────────────────┼──────────────────────┼───────────────┼─────────────────┼────────┤
92       │XmNlayoutDirection   │ XmCLayoutDirection   │ XmDirection   │ XmLEFT_TO_RIGHT │ CG     │
93       ├─────────────────────┼──────────────────────┼───────────────┼─────────────────┼────────┤
94       │XmNanimate           │ XmCAnimate           │ Boolean       │ False           │ CG     │
95       ├─────────────────────┼──────────────────────┼───────────────┼─────────────────┼────────┤
96       └─────────────────────┴──────────────────────┴───────────────┴─────────────────┴────────┘
97       XmNbuttonFontList
98                 Specifies  the font list used for button descendants. See the
99                 XmNbuttonRenderTable resource.
100
101       XmNbuttonRenderTable
102                 Specifies  the  render  table  used  for  MenuShell's  button
103                 descendants.   If this value is NULL at initialization and if
104                 the value of XmNdefaultFontList is  not  NULL,  XmNbuttonRen‐
105                 derTable  is  initialized to the value of XmNdefaultFontList.
106                 If the value of  XmNdefaultFontList  is  NULL,  XmNbuttonRen‐
107                 derTable is initialized by looking up the parent hierarchy of
108                 the widget for an ancestor  that  holds  the  XmQTspecifyRen‐
109                 derTable  trait.  If such an ancestor is found, XmNbuttonRen‐
110                 derTable is initialized to the XmBUTTON_RENDER_TABLE value of
111                 the  ancestor  widget.  If  no  such  ancestor  is found, the
112                 default  is  implementation  dependent.   Refer   to   XmRen‐
113                 derTable(3)  for  more information on the creation and struc‐
114                 ture of a render table.
115
116       XmNdefaultFontList
117                 Specifies a default font list  for  MenuShell's  descendants.
118                 This  resource  is obsolete and exists for compatibility with
119                 earlier releases. It has been replaced  by  XmNbuttonFontList
120                 and XmNlabelFontList.
121
122       XmNlabelFontList
123                 Specifies  the  font list used for label descendants. See the
124                 XmNlabelRenderTable resource.
125
126       XmNlabelRenderTable
127                 Specifies the render table used for MenuShell's label descen‐
128                 dants  (Labels  and  LabelGadgets).  If this value is NULL at
129                 initialization and if the value of XmNdefaultFontList is  not
130                 NULL, XmNlabelRenderTable is initialized to the value of XmN‐
131                 defaultFontList. If the value of XmNdefaultFontList is  NULL,
132                 the  parent hierarchy of the widget is searched for an ances‐
133                 tor that holds the XmQTspecifyRenderTable trait.  If such  an
134                 ancestor  is found, XmNlabelRenderTable is initialized to the
135                 XmLABEL_RENDER_TABLE value of the ancestor widget. If no such
136                 ancestor  is  found, the default is implementation dependent.
137                 Refer to XmRenderTable(3) for more information  on  the  cre‐
138                 ation and structure of a render table.
139
140       XmNlayoutDirection
141                 Specifies  the direction in which the subwidgets, children of
142                 a widget, or other visual components are to be laid out. This
143                 policy  will  apply  as  the  default  layout  policy for all
144                 descendants of this MenuShell.
145
146
147       XmNanimate
148                 Controls whether menus will post in an animated fashion.
149
150
151   Inherited Resources
152       MenuShell  inherits  behavior  and  resources  from  the   superclasses
153       described  in the following tables.  For a complete description of each
154       resource, refer to the reference page for that  superclass.   The  pro‐
155       grammer  can set the resource values for these inherited classes to set
156       attributes for this widget. To reference a resource by name or by class
157       in  a .Xdefaults file, remove the XmN or XmC prefix and use the remain‐
158       ing letters. To specify one of the defined values for a resource  in  a
159       .Xdefaults file, remove the Xm prefix and use the remaining letters (in
160       either lowercase or uppercase,  but  include  any  underscores  between
161       words).   The codes in the access column indicate if the given resource
162       can be set  at  creation  time  (C),  set  by  using  XtSetValues  (S),
163       retrieved by using XtGetValues (G), or is not applicable (N/A).
164
165       ┌─────────────────────────────────────────────────────────────────────────────────────────────────────┐
166       │                        │                Shell Res│ource Set                │                │        │
167Name                    Class                   Type                   Default        Access 
168       ├────────────────────────┼─────────────────────────┼────────────────────────┼────────────────┼────────┤
169       │XmNallowShellResize     │ XmCAllowShellResize     │ Boolean                │ True           │ G      │
170       ├────────────────────────┼─────────────────────────┼────────────────────────┼────────────────┼────────┤
171       │XmNcreatePopupChildProc │ XmCCreatePopupChildProc │ XtCreatePopupChildProc │ NULL           │ CSG    │
172       ├────────────────────────┼─────────────────────────┼────────────────────────┼────────────────┼────────┤
173       │XmNgeometry             │ XmCGeometry             │ String                 │ NULL           │ CSG    │
174       ├────────────────────────┼─────────────────────────┼────────────────────────┼────────────────┼────────┤
175       │XmNoverrideRedirect     │ XmCOverrideRedirect     │ Boolean                │ True           │ CSG    │
176       ├────────────────────────┼─────────────────────────┼────────────────────────┼────────────────┼────────┤
177       │XmNpopdownCallback      │ XmCCallback             │ XtCallbackList         │ NULL           │ C      │
178       ├────────────────────────┼─────────────────────────┼────────────────────────┼────────────────┼────────┤
179       │XmNpopupCallback        │ XmCCallback             │ XtCallbackList         │ NULL           │ C      │
180       ├────────────────────────┼─────────────────────────┼────────────────────────┼────────────────┼────────┤
181       │XmNsaveUnder            │ XmCSaveUnder            │ Boolean                │ True           │ CSG    │
182       ├────────────────────────┼─────────────────────────┼────────────────────────┼────────────────┼────────┤
183       │XmNvisual               │ XmCVisual               │ Visual *               │ CopyFromParent │ CSG    │
184       ├────────────────────────┼─────────────────────────┼────────────────────────┼────────────────┼────────┤
185       └────────────────────────┴─────────────────────────┴────────────────────────┴────────────────┴────────┘
186       ┌───────────────────────────────────────────────────────────────────────┐
187       │                  │     Composite Reso│urce Set      │         │        │
188Name              Class             Type        Default Access 
189       ├──────────────────┼───────────────────┼─────────────┼─────────┼────────┤
190       │XmNchildren       │ XmCReadOnly       │ WidgetList  │ NULL    │ G      │
191       ├──────────────────┼───────────────────┼─────────────┼─────────┼────────┤
192       │XmNinsertPosition │ XmCInsertPosition │ XtOrderProc │ NULL    │ CSG    │
193       ├──────────────────┼───────────────────┼─────────────┼─────────┼────────┤
194       │XmNnumChildren    │ XmCReadOnly       │ Cardinal    │ 0       │ G      │
195       ├──────────────────┼───────────────────┼─────────────┼─────────┼────────┤
196       └──────────────────┴───────────────────┴─────────────┴─────────┴────────┘
197       ┌───────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
198       │                              │               Core Resource Se│t                │                      │        │
199Name                          Class                         Type           Default              Access 
200       ├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
201       │XmNaccelerators               │ XmCAccelerators               │ XtAccelerators │ dynamic              │ CSG    │
202       ├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
203       │XmNancestorSensitive          │ XmCSensitive                  │ Boolean        │ dynamic              │ G      │
204       ├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
205       │XmNbackground                 │ XmCBackground                 │ Pixel          │ dynamic              │ CSG    │
206       ├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
207       │XmNbackgroundPixmap           │ XmCPixmap                     │ Pixmap         │ XmUNSPECIFIED_PIXMAP │ CSG    │
208       ├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
209       │XmNborderColor                │ XmCBorderColor                │ Pixel          │ XtDefaultForeground  │ CSG    │
210       ├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
211       │XmNborderPixmap               │ XmCPixmap                     │ Pixmap         │ XmUNSPECIFIED_PIXMAP │ CSG    │
212       ├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
213       │XmNborderWidth                │ XmCBorderWidth                │ Dimension      │ 0                    │ CSG    │
214       ├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
215       │XmNcolormap                   │ XmCColormap                   │ Colormap       │ dynamic              │ CG     │
216       ├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
217       │XmNdepth                      │ XmCDepth                      │ int            │ dynamic              │ CG     │
218       ├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
219       │XmNdestroyCallback            │ XmCCallback                   │ XtCallbackList │ NULL                 │ C      │
220       ├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
221       │XmNheight                     │ XmCHeight                     │ Dimension      │ dynamic              │ CSG    │
222       ├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
223       │XmNinitialResourcesPersistent │ XmCInitialResourcesPersistent │ Boolean        │ True                 │ C      │
224       ├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
225       │XmNmappedWhenManaged          │ XmCMappedWhenManaged          │ Boolean        │ True                 │ CSG    │
226       ├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
227       │XmNscreen                     │ XmCScreen                     │ Screen *       │ dynamic              │ CG     │
228       ├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
229       │XmNsensitive                  │ XmCSensitive                  │ Boolean        │ True                 │ CSG    │
230       ├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
231       │XmNtranslations               │ XmCTranslations               │ XtTranslations │ dynamic              │ CSG    │
232       ├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
233       │XmNwidth                      │ XmCWidth                      │ Dimension      │ dynamic              │ CSG    │
234       ├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
235       │XmNx                          │ XmCPosition                   │ Position       │ 0                    │ CSG    │
236       ├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
237       │XmNy                          │ XmCPosition                   │ Position       │ 0                    │ CSG    │
238       ├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
239       └──────────────────────────────┴───────────────────────────────┴────────────────┴──────────────────────┴────────┘
240   Translations
241       The XmMenuShell translations are described in the following list.
242
243       The following key names are listed in the X standard key event transla‐
244       tion table syntax.  This format is the one used by Motif to specify the
245       widget  actions  corresponding to a given key.  A brief overview of the
246       format is provided under VirtualBindings(3).  For a  complete  descrip‐
247       tion  of the format, please refer to the X Toolkit Instrinsics Documen‐
248       tation.
249
250       <BtnDown>:
251                 ClearTraversal()
252
253       <BtnUp>:  MenuShellPopdownDone()
254
255   Action Routines
256       The XmMenuShell action routines are
257
258       ClearTraversal():
259                 Disables keyboard traversal for the menu, enables mouse  tra‐
260                 versal, and unposts any menus posted by this menu.
261
262       MenuShellPopdownDone():
263                 Unposts  the  menu  hierarchy  and, when the shell's keyboard
264                 focus policy is XmEXPLICIT, restores focus to the widget that
265                 had the focus before the menu system was entered.
266
267       MenuShellPopdownOne():
268                 In  a top-level Pulldown MenuPane from a MenuBar, this action
269                 unposts the menu, disarms the MenuBar CascadeButton  and  the
270                 MenuBar, and, when the shell's keyboard focus policy is XmEX‐
271                 PLICIT, restores keyboard focus to the widget  that  had  the
272                 focus  before  the  MenuBar  was  entered.  In other Pulldown
273                 MenuPanes, this action unposts the menu.
274
275                 In a Popup MenuPane, this action unposts the menu, and,  when
276                 the  shell's  keyboard  focus  policy is XmEXPLICIT, restores
277                 keyboard focus to the widget from which the menu was posted.
278
279   Virtual Bindings
280       The bindings for virtual keys are  vendor  specific.   For  information
281       about bindings for virtual buttons and keys, see VirtualBindings(3).
282
284       Composite(3),    Core(3),    OverrideShell(3),    Shell(3),   XmCreate‐
285       MenuShell(3), XmCreatePopupMenu(3), XmCreatePulldownMenu(3), and XmRow‐
286       Column(3).
287
288
289
290                                                     XmMenuShell(library call)
Impressum