1XmCascadeButtonGadget(library call) XmCascadeButtonGadget(library call)
2
6 XmCascadeButtonGadget — The CascadeButtonGadget widget class
7
9 #include <Xm/CascadeBG.h>
10
12 CascadeButtonGadget links two menu panes, a MenuBar to a menu pane, or
13 an OptionMenu to a menu pane.
14 It is used in menu systems and must have a RowColumn parent with its
16 XmNrowColumnType resource set to XmMENU_BAR, XmMENU_POPUP, XmMENU_PULL‐
17 DOWN, or XmMENU_OPTION.
18 It is the only gadget that can have a Pulldown menu pane attached to it
20 as a submenu. The submenu is displayed when this gadget is activated
21 within a PopupMenu, a PulldownMenu, or an OptionMenu. Its visuals can
22 include a label or pixmap and a cascading indicator when it is in a
23 Popup or Pulldown menu pane; or it can include only a label or a pixmap
24 when it is in an OptionMenu. The positioning of the PulldownMenu with
25 respect to the CascadeButton depends on the XmNlayoutDirection resource
26 of the MenuShell.
27 The default behavior associated with a CascadeButtonGadget depends on
29 the type of menu system in which it resides. By default, BSelect con‐
30 trols the behavior of the CascadeButtonGadget. In addition, BMenu con‐
31 trols the behavior of the CascadeButtonGadget if it resides in a Popup‐
32 Menu system. The actual mouse button used is determined by its RowCol‐
33 umn parent. BMenu also performs the BSelect actions in all types of
34 menu systems.
35 A CascadeButtonGadget's visuals differ from most other button gadgets.
37 When the button becomes armed, its visuals change from a 2-D to a 3-D
38 look, and it displays the submenu that has been attached to it. If no
39 submenu is attached, it simply changes its visuals.
40 When a CascadeButtonGadget within a Pulldown or Popup menu pane is
42 armed as the result of the user moving the mouse pointer into the gad‐
43 get, it does not immediately display its submenu. Instead, it waits a
44 short time to see if the arming was temporary (that is, the user was
45 simply passing through the gadget), or the user really wanted the sub‐
46 menu posted. This delay is configurable using XmNmappingDelay.
47 CascadeButtonGadget provides a single mechanism for activating the gad‐
49 get from the keyboard. This mechanism is referred to as a keyboard
50 mnemonic. If a mnemonic has been specified for the gadget, the user
51 may activate it by simply typing the mnemonic while the CascadeButton‐
52 Gadget is visible. If the CascadeButtonGadget is in a MenuBar and the
53 MenuBar does not have focus, the MAlt modifier must be pressed with the
54 mnemonic. Mnemonics are typically used to interact with a menu using
55 the keyboard.
56 If a CascadeButtonGadget is in a Pulldown or Popup menu pane and there
58 is a submenu attached, the XmNmarginBottom, XmNmarginLeft, XmNmargin‐
59 Right, and XmNmarginTop resources may enlarge to accommodate XmNcas‐
60 cadePixmap. XmNmarginWidth defaults to 6 if this resource is in a
61 MenuBar; otherwise, it takes LabelGadget's default, which is 2.
62 CascadeButtonGadget uses the XmQTmenuSystem and XmQTspecifyRenderTable
64 traits.
65 Classes
67 CascadeButtonGadget inherits behavior, resources, and traits from the
68 Object, RectObj, XmGadget, and XmLabelGadget classes.
69 The class pointer is xmCascadeButtonGadgetClass.
71 The class name is XmCascadeButtonGadget.
73 New Resources
75 The following table defines a set of widget resources used by the pro‐
76 grammer to specify data. The programmer can also set the resource val‐
77 ues for the inherited classes to set attributes for this widget. To
78 reference a resource by name or by class in a .Xdefaults file, remove
79 the XmN or XmC prefix and use the remaining letters. To specify one of
80 the defined values for a resource in a .Xdefaults file, remove the Xm
81 prefix and use the remaining letters (in either lowercase or uppercase,
82 but include any underscores between words). The codes in the access
83 column indicate if the given resource can be set at creation time (C),
84 set by using XtSetValues (S), retrieved by using XtGetValues (G), or is
85 not applicable (N/A).
86 ┌───────────────────────────────────────────────────────────────────────────┐
88 │ │ XmCascadeButt│onGadget │ │ │
89 │Name │ Class │ Type │ Default │ Access │
90 ├─────────────────────┼─────────────────┼────────────────┼─────────┼────────┤
91 │XmNactivateCallback │ XmCCallback │ XtCallbackList │ NULL │ C │
92 ├─────────────────────┼─────────────────┼────────────────┼─────────┼────────┤
93 │XmNcascadePixmap │ XmCPixmap │ Pixmap │ dynamic │ CSG │
94 ├─────────────────────┼─────────────────┼────────────────┼─────────┼────────┤
95 │XmNcascadingCallback │ XmCCallback │ XtCallbackList │ NULL │ C │
96 ├─────────────────────┼─────────────────┼────────────────┼─────────┼────────┤
97 │XmNmappingDelay │ XmCMappingDelay │ int │ 180 ms │ CSG │
98 ├─────────────────────┼─────────────────┼────────────────┼─────────┼────────┤
99 │XmNsubMenuId │ XmCMenuWidget │ Widget │ NULL │ CSG │
100 ├─────────────────────┼─────────────────┼────────────────┼─────────┼────────┤
101 └─────────────────────┴─────────────────┴────────────────┴─────────┴────────┘
102 XmNactivateCallback
103 Specifies the list of callbacks that is called when the user
104 activates the CascadeButtonGadget, and there is no submenu
105 attached to pop up. The activation occurs when a mouse button
106 is released or when the mnemonic associated with the gadget
107 is typed. The specific mouse button depends on information in
108 the RowColumn parent. The reason sent by the callback is
109 XmCR_ACTIVATE.
110 XmNcascadePixmap
112 Specifies the cascade pixmap displayed on one end of the gad‐
113 get when a CascadeButtonGadget is used within a Popup or
114 Pulldown menu pane and a submenu is attached. The LabelGad‐
115 get class resources XmNmarginBottom, XmNmarginLeft, XmN‐
116 marginRight, and XmNmarginTop may be modified to ensure that
117 room is left for the cascade pixmap. The default cascade
118 pixmap in menus other than option menus is an arrow pointing
119 to the side of the menu where the submenu will appear. The
120 default for the CascadeButtonGadget in an option menu is
121 XmUNSPECIFIED_PIXMAP.
122 The positioning of the cascade pixmap to either the left of
124 right of the widget, and the direction of the arrow, depend
125 on the XmNlayoutDirection resource of the MenuShell.
126 XmNcascadingCallback
128 Specifies the list of callbacks that is called just prior to
129 the mapping of the submenu associated with the CascadeButton‐
130 Gadget. The reason sent by the callback is XmCR_CASCADING.
131 XmNmappingDelay
133 Specifies the amount of time, in milliseconds, between when a
134 CascadeButtonGadget becomes armed and when it maps its sub‐
135 menu. This delay is used only when the gadget is within a
136 Popup or Pulldown menu pane. The value must not be negative.
137 XmNsubMenuId
139 Specifies the widget ID for the Pulldown menu pane to be
140 associated with this CascadeButtonGadget. The specified menu
141 pane is displayed when the CascadeButtonGadget becomes armed.
142 The menu pane must have been created with the appropriate
143 parentage depending on the type of menu used. See XmCre‐
144 atePulldownMenu(3), XmCreatePopupMenu(3), and XmCreateOption‐
145 Menu(3) for more information on the menu systems.
146 Inherited Resources
148 CascadeButtonGadget inherits behavior and resources from the super‐
149 classes described in the following tables. For a complete description
150 of each resource, refer to the reference page for that superclass.
151 ┌──────────────────────────────────────────────────────────────────────────────────────────────────────────┐
153 │ │ XmLabelGadget R│esource Set │ │ │
154 │Name │ Class │ Type │ Default │ Access │
155 ├──────────────────────────┼───────────────────────────┼───────────────────┼──────────────────────┼────────┤
156 │XmNaccelerator │ XmCAccelerator │ String │ NULL │ N/A │
157 ├──────────────────────────┼───────────────────────────┼───────────────────┼──────────────────────┼────────┤
158 │XmNacceleratorText │ XmCAcceleratorText │ XmString │ NULL │ N/A │
159 ├──────────────────────────┼───────────────────────────┼───────────────────┼──────────────────────┼────────┤
160 │XmNalignment │ XmCAlignment │ unsigned char │ dynamic │ CSG │
161 ├──────────────────────────┼───────────────────────────┼───────────────────┼──────────────────────┼────────┤
162 │XmNfontList │ XmCFontList │ XmFontList │ dynamic │ CSG │
163 ├──────────────────────────┼───────────────────────────┼───────────────────┼──────────────────────┼────────┤
164 │XmNlabelInsensitivePixmap │ XmCLabelInsensitivePixmap │ Pixmap │ XmUNSPECIFIED_PIXMAP │ CSG │
165 ├──────────────────────────┼───────────────────────────┼───────────────────┼──────────────────────┼────────┤
166 │XmNlabelPixmap │ XmCLabelPixmap │ Pixmap │ XmUNSPECIFIED_PIXMAP │ CSG │
167 ├──────────────────────────┼───────────────────────────┼───────────────────┼──────────────────────┼────────┤
168 │XmNlabelString │ XmCXmString │ XmString │ dynamic │ CSG │
169 ├──────────────────────────┼───────────────────────────┼───────────────────┼──────────────────────┼────────┤
170 │XmNlabelType │ XmCLabelType │ unsigned char │ XmSTRING │ CSG │
171 ├──────────────────────────┼───────────────────────────┼───────────────────┼──────────────────────┼────────┤
172 │XmNmarginBottom │ XmCMarginBottom │ Dimension │ dynamic │ CSG │
173 ├──────────────────────────┼───────────────────────────┼───────────────────┼──────────────────────┼────────┤
174 │XmNmarginHeight │ XmCMarginHeight │ Dimension │ 2 │ CSG │
175 ├──────────────────────────┼───────────────────────────┼───────────────────┼──────────────────────┼────────┤
176 │XmNmarginLeft │ XmCMarginLeft │ Dimension │ 0 │ CSG │
177 ├──────────────────────────┼───────────────────────────┼───────────────────┼──────────────────────┼────────┤
178 │XmNmarginRight │ XmCMarginRight │ Dimension │ dynamic │ CSG │
179 ├──────────────────────────┼───────────────────────────┼───────────────────┼──────────────────────┼────────┤
180 │XmNmarginTop │ XmCMarginTop │ Dimension │ dynamic │ CSG │
181 ├──────────────────────────┼───────────────────────────┼───────────────────┼──────────────────────┼────────┤
182 │XmNmarginWidth │ XmCMarginWidth │ Dimension │ dynamic │ CSG │
183 ├──────────────────────────┼───────────────────────────┼───────────────────┼──────────────────────┼────────┤
184 │XmNmnemonic │ XmCMnemonic │ KeySym │ NULL │ CSG │
185 ├──────────────────────────┼───────────────────────────┼───────────────────┼──────────────────────┼────────┤
186 │XmNmnemonicCharSet │ XmCMnemonicCharSet │ String │ dynamic │ CSG │
187 ├──────────────────────────┼───────────────────────────┼───────────────────┼──────────────────────┼────────┤
188 │XmNrecomputeSize │ XmCRecomputeSize │ Boolean │ True │ CSG │
189 ├──────────────────────────┼───────────────────────────┼───────────────────┼──────────────────────┼────────┤
190 │XmNrenderTable │ XmCRenderTable │ XmRenderTable │ dynamic │ CSG │
191 ├──────────────────────────┼───────────────────────────┼───────────────────┼──────────────────────┼────────┤
192 │XmNstringDirection │ XmCStringDirection │ XmStringDirection │ dynamic │ CSG │
193 ├──────────────────────────┼───────────────────────────┼───────────────────┼──────────────────────┼────────┤
194 └──────────────────────────┴───────────────────────────┴───────────────────┴──────────────────────┴────────┘
195 ┌─────────────────────────────────────────────────────────────────────────────────────────────────┐
196 │ │ XmGadget │Resource Set │ │ │
197 │Name │ Class │ Type │ Default │ Access │
198 ├──────────────────────┼───────────────────────┼──────────────────┼──────────────────────┼────────┤
199 │XmNbackground │ XmCBackground │ Pixel │ dynamic │ CSG │
200 ├──────────────────────┼───────────────────────┼──────────────────┼──────────────────────┼────────┤
201 │XmNbackgroundPixmap │ XmCPixmap │ Pixmap │ XmUNSPECIFIED_PIXMAP │ CSG │
202 ├──────────────────────┼───────────────────────┼──────────────────┼──────────────────────┼────────┤
203 │XmNbottomShadowColor │ XmCBottomShadowColor │ Pixel │ dynamic │ CSG │
204 ├──────────────────────┼───────────────────────┼──────────────────┼──────────────────────┼────────┤
205 │XmNbottomShadowPixmap │ XmCBottomShadowPixmap │ Pixmap │ dynamic │ CSG │
206 ├──────────────────────┼───────────────────────┼──────────────────┼──────────────────────┼────────┤
207 │XmNhelpCallback │ XmCCallback │ XtCallbackList │ NULL │ C │
208 ├──────────────────────┼───────────────────────┼──────────────────┼──────────────────────┼────────┤
209 │XmNforeground │ XmCForeground │ Pixel │ dynamic │ CSG │
210 ├──────────────────────┼───────────────────────┼──────────────────┼──────────────────────┼────────┤
211 │XmNhighlightColor │ XmCHighlightColor │ Pixel │ dynamic │ CSG │
212 ├──────────────────────┼───────────────────────┼──────────────────┼──────────────────────┼────────┤
213 │XmNhighlightOnEnter │ XmCHighlightOnEnter │ Boolean │ False │ CSG │
214 ├──────────────────────┼───────────────────────┼──────────────────┼──────────────────────┼────────┤
215 │XmNhighlightPixmap │ XmCHighlightPixmap │ Pixmap │ dynamic │ CSG │
216 ├──────────────────────┼───────────────────────┼──────────────────┼──────────────────────┼────────┤
217 │XmNhighlightThickness │ XmCHighlightThickness │ Dimension │ 0 │ CSG │
218 ├──────────────────────┼───────────────────────┼──────────────────┼──────────────────────┼────────┤
219 │XmNlayoutDirection │ XmNCLayoutDirection │ XmDirection │ dynamic │ CG │
220 ├──────────────────────┼───────────────────────┼──────────────────┼──────────────────────┼────────┤
221 │XmNnavigationType │ XmCNavigationType │ XmNavigationType │ XmNONE │ CSG │
222 ├──────────────────────┼───────────────────────┼──────────────────┼──────────────────────┼────────┤
223 │XmNshadowThickness │ XmCShadowThickness │ Dimension │ 2 │ CSG │
224 ├──────────────────────┼───────────────────────┼──────────────────┼──────────────────────┼────────┤
225 │XmNtopShadowColor │ XmCTopShadowColor │ Pixel │ dynamic │ CSG │
226 ├──────────────────────┼───────────────────────┼──────────────────┼──────────────────────┼────────┤
227 │XmNtopShadowPixmap │ XmCTopShadowPixmap │ Pixmap │ dynamic │ CSG │
228 ├──────────────────────┼───────────────────────┼──────────────────┼──────────────────────┼────────┤
229 │XmNtraversalOn │ XmCTraversalOn │ Boolean │ True │ CSG │
230 ├──────────────────────┼───────────────────────┼──────────────────┼──────────────────────┼────────┤
231 │XmNunitType │ XmCUnitType │ unsigned char │ dynamic │ CSG │
232 ├──────────────────────┼───────────────────────┼──────────────────┼──────────────────────┼────────┤
233 │XmNuserData │ XmCUserData │ XtPointer │ NULL │ CSG │
234 ├──────────────────────┼───────────────────────┼──────────────────┼──────────────────────┼────────┤
235 └──────────────────────┴───────────────────────┴──────────────────┴──────────────────────┴────────┘
236 ┌─────────────────────────────────────────────────────────────────────┐
237 │ │ RectObj Resour│ce Set │ │ │
238 │Name │ Class │ Type │ Default │ Access │
239 ├─────────────────────┼────────────────┼───────────┼─────────┼────────┤
240 │XmNancestorSensitive │ XmCSensitive │ Boolean │ dynamic │ G │
241 ├─────────────────────┼────────────────┼───────────┼─────────┼────────┤
242 │XmNborderWidth │ XmCBorderWidth │ Dimension │ 0 │ N/A │
243 ├─────────────────────┼────────────────┼───────────┼─────────┼────────┤
244 │XmNheight │ XmCHeight │ Dimension │ dynamic │ CSG │
245 ├─────────────────────┼────────────────┼───────────┼─────────┼────────┤
246 │XmNsensitive │ XmCSensitive │ Boolean │ True │ CSG │
247 ├─────────────────────┼────────────────┼───────────┼─────────┼────────┤
248 │XmNwidth │ XmCWidth │ Dimension │ dynamic │ CSG │
249 ├─────────────────────┼────────────────┼───────────┼─────────┼────────┤
250 │XmNx │ XmCPosition │ Position │ 0 │ CSG │
251 ├─────────────────────┼────────────────┼───────────┼─────────┼────────┤
252 │XmNy │ XmCPosition │ Position │ 0 │ CSG │
253 ├─────────────────────┼────────────────┼───────────┼─────────┼────────┤
254 └─────────────────────┴────────────────┴───────────┴─────────┴────────┘
255 ┌─────────────────────────────────────────────────────────────────────┐
256 │ │ Object Re│source Set │ │ │
257 │Name │ Class │ Type │ Default │ Access │
258 ├───────────────────┼─────────────┼────────────────┼─────────┼────────┤
259 │XmNdestroyCallback │ XmCCallback │ XtCallbackList │ NULL │ C │
260 ├───────────────────┼─────────────┼────────────────┼─────────┼────────┤
261 └───────────────────┴─────────────┴────────────────┴─────────┴────────┘
262 Callback Information
263 A pointer to the following structure is passed to each callback:
264 typedef struct
266 {
267 int reason;
268 XEvent * event;
269 } XmAnyCallbackStruct;
270 reason Indicates why the callback was invoked
272 event Points to the XEvent that triggered the callback or is NULL
274 if this callback was not triggered by an XEvent
275 Behavior
277 XmCascadeButtonGadget includes behavior from XmGadget. XmCascadeButton
278 includes the menu traversal behavior from XmLabel. Additional XmCas‐
279 cadeButtonGadget behavior is described in the following list (in a
280 Popup menu system, <Btn3> also performs the <Btn1> actions).
281 <Btn1Down>:
283 Unposts any menus posted by the parent menu. Arms the Cas‐
284 cadeButtonGadget, posts the associated submenu, enables mouse
285 traversal, and, in a MenuBar, arms the MenuBar. If the menu
286 is already active, this event disables keyboard traversal for
287 the menu and returns the menu to mouse traversal mode.
288 <Btn1Up>: Calls the callbacks in XmNcascadingCallback, posts the sub‐
290 menu attached to the CascadeButtonGadget and enables keyboard
291 traversal within the menu. If the CascadeButtonGadget does
292 not have a submenu attached, this action calls the callbacks
293 in XmNactivateCallback, activates the CascadeButtonGadget,
294 and unposts all posted menus in the cascade.
295 <Key><osfActivate>:
297 Calls the callbacks in XmNcascadingCallback, and posts the
298 submenu attached to the CascadeButtonGadget if keyboard tra‐
299 versal is enabled in the menu. If the CascadeButtonGadget
300 does not have a submenu attached, this action calls the call‐
301 backs in XmNactivateCallback, activates the CascadeButtonGad‐
302 get, and unposts all posted menus in the cascade. This
303 action applies only to gadgets in MenuBars, PulldownMenus,
304 and PopupMenus. For a CascadeButtonGadget in an OptionMenu,
305 if the parent is a manager, this action passes the event to
306 the parent.
307 <Key><osfSelect>:
309 Calls the callbacks in XmNcascadingCallback, and posts the
310 submenu attached to the CascadeButtonGadget if keyboard tra‐
311 versal is enabled in the menu. If the CascadeButtonGadget
312 does not have a submenu attached, this action calls the call‐
313 backs in XmNactivateCallback, activates the CascadeButtonGad‐
314 get, and unposts all posted menus in the cascade.
315 <Key><osfHelp>:
317 Unposts all menus in the menu hierarchy and, when the shell's
318 keyboard focus policy is XmEXPLICIT, restores keyboard focus
319 to the widget that had the focus before the menu system was
320 entered. Calls the callbacks for XmNhelpCallback if any
321 exist. If there are no help callbacks for this widget, this
322 action calls the help callbacks for the nearest ancestor that
323 has them.
324 <Key><osfCancel>:
326 In a MenuBar, disarms the CascadeButtonGadget and the menu
327 and, when the shell's keyboard focus policy is XmEXPLICIT,
328 restores keyboard focus to the widget that had the focus
329 before the menu was entered. For a CascadeButtonGadget in an
330 OptionMenu, if the parent is a manager, this action passes
331 the event to the parent.
332 In a toplevel Pulldown MenuPane from a MenuBar, unposts the
334 menu, disarms the MenuBar CascadeButton and the MenuBar, and,
335 when the shell's keyboard focus policy is XmEXPLICIT,
336 restores keyboard focus to the widget that had the focus
337 before the MenuBar was entered. In other Pulldown MenuPanes,
338 unposts the menu.
339 In a Popup MenuPane, unposts the menu and restores keyboard
341 focus to the widget from which the menu was posted.
342 <Enter>: If keyboard traversal is enabled does nothing. Otherwise, in
344 a MenuBar, unposts any MenuPanes associated with another
345 MenuBar entry, arms the CascadeButtonGadget, and posts the
346 associated submenu. In other menus, arms the CascadeButton‐
347 Gadget and posts the associated submenu after the delay spec‐
348 ified by XmNmappingDelay.
349 <Leave>: If keyboard traversal is enabled does nothing. Otherwise, in
351 a MenuBar, disarms the CascadeButtonGadget if the submenu
352 associated with the CascadeButtonGadget is not currently
353 posted or if there is no submenu associated with the Cascade‐
354 ButtonGadget.
355 In other menus, if the pointer moves anywhere except into a
357 submenu associated with the CascadeButtonGadget, the Cascade‐
358 ButtonGadget is disarmed and its submenu is unposted.
359 Virtual Bindings
361 The bindings for virtual keys are vendor specific. For information
362 about bindings for virtual buttons and keys, see VirtualBindings(3).
363
365 Object(3), RectObj(3), XmCascadeButtonHighlight(3), XmCreateCascadeBut‐
366 tonGadget(3), XmCreatePulldownMenu(3), XmCreatePopupMenu(3), XmCre‐
367 ateOptionMenu(3), XmGadget(3), XmLabelGadget(3), XmRowColumn(3),
368 XmVaCreateCascadeButtonGadget(3), and XmVaCreateManagedCascadeButton‐
369 Gadget(3).
370 XmCascadeButtonGadget(library call)