1QMenuBar(3qt) QMenuBar(3qt)
2
6 QMenuBar - Horizontal menu bar
7
9 #include <qmenubar.h>
10 Inherits QFrame and QMenuData.
12 Public Members
14 QMenuBar ( QWidget * parent = 0, const char * name = 0 )
15 ~QMenuBar ()
16 virtual void show ()
17 virtual void hide ()
18 virtual int heightForWidth ( int max_width ) const
19 enum Separator { Never = 0, InWindowsStyle = 1 }
20 Separator separator () const (obsolete)
21 virtual void setSeparator ( Separator when ) (obsolete)
22 void setDefaultUp ( bool )
23 bool isDefaultUp () const
24 Signals
26 void activated ( int id )
27 void highlighted ( int id )
28 Important Inherited Members
30 int insertItem ( const QString & text, const QObject * receiver, const
31 char * member, const QKeySequence & accel = 0, int id = -1, int
32 index = -1 )
33 int insertItem ( const QIconSet & icon, const QString & text, const
34 QObject * receiver, const char * member, const QKeySequence & accel
35 = 0, int id = -1, int index = -1 )
36 int insertItem ( const QPixmap & pixmap, const QObject * receiver,
37 const char * member, const QKeySequence & accel = 0, int id = -1,
38 int index = -1 )
39 int insertItem ( const QIconSet & icon, const QPixmap & pixmap, const
40 QObject * receiver, const char * member, const QKeySequence & accel
41 = 0, int id = -1, int index = -1 )
42 int insertItem ( const QString & text, int id = -1, int index = -1 )
43 int insertItem ( const QIconSet & icon, const QString & text, int id =
44 -1, int index = -1 )
45 int insertItem ( const QString & text, QPopupMenu * popup, int id = -1,
46 int index = -1 )
47 int insertItem ( const QIconSet & icon, const QString & text,
48 QPopupMenu * popup, int id = -1, int index = -1 )
49 int insertItem ( const QPixmap & pixmap, int id = -1, int index = -1 )
50 int insertItem ( const QIconSet & icon, const QPixmap & pixmap, int id
51 = -1, int index = -1 )
52 int insertItem ( const QPixmap & pixmap, QPopupMenu * popup, int id =
53 -1, int index = -1 )
54 int insertItem ( const QIconSet & icon, const QPixmap & pixmap,
55 QPopupMenu * popup, int id = -1, int index = -1 )
56 int insertItem ( QWidget * widget, int id = -1, int index = -1 )
57 int insertItem ( const QIconSet & icon, QCustomMenuItem * custom, int
58 id = -1, int index = -1 )
59 int insertItem ( QCustomMenuItem * custom, int id = -1, int index = -1
60 )
61 int insertSeparator ( int index = -1 )
62 void removeItem ( int id )
63 void clear ()
64 bool isItemEnabled ( int id ) const
65 void setItemEnabled ( int id, bool enable )
66 bool isItemVisible ( int id ) const
67 void setItemVisible ( int id, bool visible )
68 Properties
70 bool defaultUp - the popup orientation
71 Separator separator - in which cases a menubar sparator is drawn
72 (obsolete)
73 Protected Members
75 virtual void drawContents ( QPainter * p )
76 virtual void menuContentsChanged ()
77 virtual void menuStateChanged ()
78
80 The QMenuBar class provides a horizontal menu bar.
81 A menu bar consists of a list of pull-down menu items. You add menu
83 items with insertItem(). For example, asuming that menubar is a pointer
84 to a QMenuBar and filemenu is a pointer to a QPopupMenu, the following
85 statement inserts the menu into the menu bar:
86 menubar->insertItem( "&File", filemenu );
88 The ampersand in the menu item's text sets Alt+F as a shortcut for this
89 menu. (You can use "&&" to get a real ampersand in the menu bar.)
90 Items are either enabled or disabled. You toggle their state with
92 setItemEnabled().
93 There is no need to lay out a menu bar. It automatically sets its own
95 geometry to the top of the parent widget and changes it appropriately
96 whenever the parent is resized.
97 Example of creating a menu bar with menu items (from menu/menu.cpp):
99 QPopupMenu *file = new QPopupMenu( this );
101 file->insertItem( p1, "&Open", this, SLOT(open()), CTRL+Key_O );
103 file->insertItem( p2, "&New", this, SLOT(news()), CTRL+Key_N );
104 menu = new QMenuBar( this );
106 menu->insertItem( "&File", file );
108 In most main window style applications you would use the menuBar()
110 provided in QMainWindow, adding QPopupMenus to the menu bar and adding
111 QActions to the popup menus.
112 Example (from action/application.cpp):
114 QPopupMenu * file = new QPopupMenu( this );
116 menuBar()->insertItem( "&File", file );
117 fileNewAction->addTo( file );
118 Menu items can have text and pixmaps (or iconsets), see the various
120 insertItem() overloads, as well as separators, see insertSeparator().
121 You can also add custom menu items that are derived from
122 QCustomMenuItem.
123 Menu items may be removed with removeItem() and enabled or disabled
125 with setItemEnabled().
126 [Image Omitted]
128 [Image Omitted]
130
132 QMenuBar on Qt/Mac is a wrapper for using the system-wide menubar. If
133 you have multiple menubars in one dialog the outermost menubar
134 (normally inside a widget with widget flag WType_TopLevel) will be used
135 for the system-wide menubar.
136 Note that arbitrary Qt widgets cannot be inserted into a QMenuBar on
138 the Mac because Qt uses Mac's native menus which don't support this
139 functionality. This limitation does not apply to stand-alone
140 QPopupMenus.
141 Qt/Mac also provides a menubar merging feature to make QMenuBar conform
143 more closely to accepted Mac OS X menubar layout. The merging
144 functionality is based on string matching the title of a QPopupMenu
145 entry. These strings are translated (using QObject::tr()) in the
146 "QMenuBar" context. If an entry is moved its slots will still fire as
147 if it was in the original place. The table below outlines the strings
148 looked for and where the entry is placed if matched:
149 <center>.nf
151 </center>
153 menu/menu.cpp is an example of QMenuBar and QPopupMenu use.
155 See also QPopupMenu, QAccel, QAction, Aqua Style Guidelines, GUI Design
157 Handbook: Menu Bar, and Main Window and Related Classes.
158 Member Type Documentation
161 This enum type is used to decide whether QMenuBar should draw a
162 separator line at its bottom.
163 QMenuBar::Never - In many applications there is already a separator,
165 and having two looks wrong.
166 QMenuBar::InWindowsStyle - In some other applications a separator looks
168 good in Windows style, but nowhere else.
169
172 Constructs a menu bar called name with parent parent.
173
175 Destroys the menu bar.
176
178 This signal is emitted when a menu item is selected; id is the id of
179 the selected item.
180 Normally you will connect each menu item to a single slot using
182 QMenuData::insertItem(), but sometimes you will want to connect several
183 items to a single slot (most often if the user selects from an array).
184 This signal is useful in such cases.
185 See also highlighted() and QMenuData::insertItem().
187 Example: progress/progress.cpp.
189
191 Removes all menu items.
192 See also removeItem() and removeItemAt().
194 Examples:
196
198 Called from QFrame::paintEvent(). Draws the menu bar contents using
199 painter p.
200 Reimplemented from QFrame.
202
204 Returns the height that the menu would resize itself to if its parent
205 (and hence itself) resized to the given max_width. This can be useful
206 for simple layout tasks in which the height of the menu bar is needed
207 after items have been inserted. See showimg/showimg.cpp for an example
208 of the usage.
209 Example: showimg/showimg.cpp.
211 Reimplemented from QWidget.
213
215 Reimplements QWidget::hide() in order to deselect any selected item,
216 and calls setUpLayout() for the main window.
217 Example: grapher/grapher.cpp.
219 Reimplemented from QWidget.
221
223 This signal is emitted when a menu item is highlighted; id is the id of
224 the highlighted item.
225 Normally, you will connect each menu item to a single slot using
227 QMenuData::insertItem(), but sometimes you will want to connect several
228 items to a single slot (most often if the user selects from an array).
229 This signal is useful in such cases.
230 See also activated() and QMenuData::insertItem().
232
234 const char * member, const QKeySequence & accel = 0, int id = -1, int
235 index = -1 )
236 The family of insertItem() functions inserts menu items into a popup
237 menu or a menu bar.
238 A menu item is usually either a text string or a pixmap, both with an
240 optional icon or keyboard accelerator. For special cases it is also
241 possible to insert custom items (see QCustomMenuItem) or even widgets
242 into popup menus.
243 Some insertItem() members take a popup menu as an additional argument.
245 Use this to insert submenus into existing menus or pulldown menus into
246 a menu bar.
247 The number of insert functions may look confusing, but they are
249 actually quite simple to use.
250 This default version inserts a menu item with the text text, the
252 accelerator key accel, an id and an optional index and connects it to
253 the slot member in the object receiver.
254 Example:
256 QMenuBar *mainMenu = new QMenuBar;
258 QPopupMenu *fileMenu = new QPopupMenu;
259 fileMenu->insertItem( "New", myView, SLOT(newFile()), CTRL+Key_N );
260 fileMenu->insertItem( "Open", myView, SLOT(open()), CTRL+Key_O );
261 mainMenu->insertItem( "File", fileMenu );
262 Not all insert functions take an object/slot parameter or an
264 accelerator key. Use connectItem() and setAccel() on those items.
265 If you need to translate accelerators, use tr() with the text and
267 accelerator. (For translations use a string key sequence.):
268 fileMenu->insertItem( tr("Open"), myView, SLOT(open()),
270 tr("Ctrl+O") );
271 In the example above, pressing Ctrl+O or selecting "Open" from the menu
273 activates the myView->open() function.
274 Some insert functions take a QIconSet parameter to specify the little
276 menu item icon. Note that you can always pass a QPixmap object instead.
277 The id specifies the identification number associated with the menu
279 item. Note that only positive values are valid, as a negative value
280 will make Qt select a unique id for the item.
281 The index specifies the position in the menu. The menu item is appended
283 at the end of the list if index is negative.
284 Note that keyboard accelerators in Qt are not application-global,
286 instead they are bound to a certain top-level window. For example,
287 accelerators in QPopupMenu items only work for menus that are
288 associated with a certain window. This is true for popup menus that
289 live in a menu bar since their accelerators will then be installed in
290 the menu bar itself. This also applies to stand-alone popup menus that
291 have a top-level widget in their parentWidget() chain. The menu will
292 then install its accelerator object on that top-level widget. For all
293 other cases use an independent QAccel object.
294 Warning: Be careful when passing a literal 0 to insertItem() because
296 some C++ compilers choose the wrong overloaded function. Cast the 0 to
297 what you mean, e.g. (QObject*)0.
298 Warning: On Mac OS X, items that connect to a slot that are inserted
300 into a menubar will not function as we use the native menubar that
301 knows nothing about signals or slots. Instead insert the items into a
302 popup menu and insert the popup menu into the menubar. This may be
303 fixed in a future Qt version.
304 Returns the allocated menu identifier number (id if id >= 0).
306 See also removeItem(), changeItem(), setAccel(), connectItem(), QAccel,
308 and qnamespace.h.
309 Examples:
311
313 QObject * receiver, const char * member, const QKeySequence & accel =
314 0, int id = -1, int index = -1 )
315 This is an overloaded member function, provided for convenience. It
316 behaves essentially like the above function.
317 Inserts a menu item with icon icon, text text, accelerator accel,
319 optional id id, and optional index position. The menu item is connected
320 it to the receiver's member slot. The icon will be displayed to the
321 left of the text in the item.
322 Returns the allocated menu identifier number (id if id >= 0).
324 See also removeItem(), changeItem(), setAccel(), connectItem(), QAccel,
326 and qnamespace.h.
327
329 const char * member, const QKeySequence & accel = 0, int id = -1, int
330 index = -1 )
331 This is an overloaded member function, provided for convenience. It
332 behaves essentially like the above function.
333 Inserts a menu item with pixmap pixmap, accelerator accel, optional id
335 id, and optional index position. The menu item is connected it to the
336 receiver's member slot. The icon will be displayed to the left of the
337 text in the item.
338 To look best when being highlighted as a menu item, the pixmap should
340 provide a mask (see QPixmap::mask()).
341 Returns the allocated menu identifier number (id if id >= 0).
343 See also removeItem(), changeItem(), setAccel(), and connectItem().
345
347 const QObject * receiver, const char * member, const QKeySequence &
348 accel = 0, int id = -1, int index = -1 )
349 This is an overloaded member function, provided for convenience. It
350 behaves essentially like the above function.
351 Inserts a menu item with icon icon, pixmap pixmap, accelerator accel,
353 optional id id, and optional index position. The icon will be displayed
354 to the left of the pixmap in the item. The item is connected to the
355 member slot in the receiver object.
356 To look best when being highlighted as a menu item, the pixmap should
358 provide a mask (see QPixmap::mask()).
359 Returns the allocated menu identifier number (id if id >= 0).
361 See also removeItem(), changeItem(), setAccel(), connectItem(), QAccel,
363 and qnamespace.h.
364
366 )
367 This is an overloaded member function, provided for convenience. It
368 behaves essentially like the above function.
369 Inserts a menu item with text text, optional id id, and optional index
371 position.
372 Returns the allocated menu identifier number (id if id >= 0).
374 See also removeItem(), changeItem(), setAccel(), and connectItem().
376
378 id = -1, int index = -1 )
379 This is an overloaded member function, provided for convenience. It
380 behaves essentially like the above function.
381 Inserts a menu item with icon icon, text text, optional id id, and
383 optional index position. The icon will be displayed to the left of the
384 text in the item.
385 Returns the allocated menu identifier number (id if id >= 0).
387 See also removeItem(), changeItem(), setAccel(), and connectItem().
389
391 -1, int index = -1 )
392 This is an overloaded member function, provided for convenience. It
393 behaves essentially like the above function.
394 Inserts a menu item with text text, submenu popup, optional id id, and
396 optional index position.
397 The popup must be deleted by the programmer or by its parent widget. It
399 is not deleted when this menu item is removed or when the menu is
400 deleted.
401 Returns the allocated menu identifier number (id if id >= 0).
403 See also removeItem(), changeItem(), setAccel(), and connectItem().
405
407 QPopupMenu * popup, int id = -1, int index = -1 )
408 This is an overloaded member function, provided for convenience. It
409 behaves essentially like the above function.
410 Inserts a menu item with icon icon, text text, submenu popup, optional
412 id id, and optional index position. The icon will be displayed to the
413 left of the text in the item.
414 The popup must be deleted by the programmer or by its parent widget. It
416 is not deleted when this menu item is removed or when the menu is
417 deleted.
418 Returns the allocated menu identifier number (id if id >= 0).
420 See also removeItem(), changeItem(), setAccel(), and connectItem().
422
424 -1 )
425 This is an overloaded member function, provided for convenience. It
426 behaves essentially like the above function.
427 Inserts a menu item with pixmap pixmap, optional id id, and optional
429 index position.
430 To look best when being highlighted as a menu item, the pixmap should
432 provide a mask (see QPixmap::mask()).
433 Returns the allocated menu identifier number (id if id >= 0).
435 See also removeItem(), changeItem(), setAccel(), and connectItem().
437
439 id = -1, int index = -1 )
440 This is an overloaded member function, provided for convenience. It
441 behaves essentially like the above function.
442 Inserts a menu item with icon icon, pixmap pixmap, optional id id, and
444 optional index position. The icon will be displayed to the left of the
445 pixmap in the item.
446 Returns the allocated menu identifier number (id if id >= 0).
448 See also removeItem(), changeItem(), setAccel(), and connectItem().
450
452 = -1, int index = -1 )
453 This is an overloaded member function, provided for convenience. It
454 behaves essentially like the above function.
455 Inserts a menu item with pixmap pixmap, submenu popup, optional id id,
457 and optional index position.
458 The popup must be deleted by the programmer or by its parent widget. It
460 is not deleted when this menu item is removed or when the menu is
461 deleted.
462 Returns the allocated menu identifier number (id if id >= 0).
464 See also removeItem(), changeItem(), setAccel(), and connectItem().
466
468 QPopupMenu * popup, int id = -1, int index = -1 )
469 This is an overloaded member function, provided for convenience. It
470 behaves essentially like the above function.
471 Inserts a menu item with icon icon, pixmap pixmap submenu popup,
473 optional id id, and optional index position. The icon will be displayed
474 to the left of the pixmap in the item.
475 The popup must be deleted by the programmer or by its parent widget. It
477 is not deleted when this menu item is removed or when the menu is
478 deleted.
479 Returns the allocated menu identifier number (id if id >= 0).
481 See also removeItem(), changeItem(), setAccel(), and connectItem().
483
485 This is an overloaded member function, provided for convenience. It
486 behaves essentially like the above function.
487 Inserts a menu item that consists of the widget widget with optional id
489 id, and optional index position.
490 Ownership of widget is transferred to the popup menu or to the menu
492 bar.
493 Theoretically, any widget can be inserted into a popup menu. In
495 practice, this only makes sense with certain widgets.
496 If a widget is not focus-enabled (see QWidget::isFocusEnabled()), the
498 menu treats it as a separator; this means that the item is not
499 selectable and will never get focus. In this way you can, for example,
500 simply insert a QLabel if you need a popup menu with a title.
501 If the widget is focus-enabled it will get focus when the user
503 traverses the popup menu with the arrow keys. If the widget does not
504 accept ArrowUp and ArrowDown in its key event handler, the focus will
505 move back to the menu when the respective arrow key is hit one more
506 time. This works with a QLineEdit, for example. If the widget accepts
507 the arrow key itself, it must also provide the possibility to put the
508 focus back on the menu again by calling QWidget::focusNextPrevChild().
509 Futhermore, if the embedded widget closes the menu when the user made a
510 selection, this can be done safely by calling:
511 if ( isVisible() &&
513 parentWidget() &&
514 parentWidget()->inherits("QPopupMenu") )
515 parentWidget()->close();
516 Returns the allocated menu identifier number (id if id >= 0).
518 See also removeItem().
520
522 int id = -1, int index = -1 )
523 This is an overloaded member function, provided for convenience. It
524 behaves essentially like the above function.
525 Inserts a custom menu item custom with an icon and with optional id id,
527 and optional index position.
528 This only works with popup menus. It is not supported for menu bars.
530 Ownership of custom is transferred to the popup menu.
531 If you want to connect a custom item to a slot, use connectItem().
533 Returns the allocated menu identifier number (id if id >= 0).
535 See also connectItem(), removeItem(), and QCustomMenuItem.
537
539 -1 )
540 This is an overloaded member function, provided for convenience. It
541 behaves essentially like the above function.
542 Inserts a custom menu item custom with optional id id, and optional
544 index position.
545 This only works with popup menus. It is not supported for menu bars.
547 Ownership of custom is transferred to the popup menu.
548 If you want to connect a custom item to a slot, use connectItem().
550 Returns the allocated menu identifier number (id if id >= 0).
552 See also connectItem(), removeItem(), and QCustomMenuItem.
554
556 Inserts a separator at position index, and returns the menu identifier
557 number allocated to it. The separator becomes the last menu item if
558 index is negative.
559 In a popup menu a separator is rendered as a horizontal line. In a
561 Motif menu bar a separator is spacing, so the rest of the items
562 (normally just "Help") are drawn right-justified. In a Windows menu bar
563 separators are ignored (to comply with the Windows style guidelines).
564 Examples:
566
568 Returns the popup orientation. See the "defaultUp" property for
569 details.
570
572 Returns TRUE if the item with identifier id is enabled; otherwise
573 returns FALSE
574 See also setItemEnabled() and isItemVisible().
576
578 Returns TRUE if the menu item with the id id is visible; otherwise
579 returns FALSE.
580 See also setItemVisible().
582
584 Recomputes the menu bar's display data according to the new contents.
585 You should never need to call this; it is called automatically by
587 QMenuData whenever it needs to be called.
588 Reimplemented from QMenuData.
590
592 Recomputes the menu bar's display data according to the new state.
593 You should never need to call this; it is called automatically by
595 QMenuData whenever it needs to be called.
596 Reimplemented from QMenuData.
598
600 Removes the menu item that has the identifier id.
601 See also removeItemAt() and clear().
603 Example: chart/chartform.cpp.
605
607 Returns in which cases a menubar sparator is drawn. See the "separator"
608 property for details.
609
611 Sets the popup orientation. See the "defaultUp" property for details.
612
614 If enable is TRUE, enables the menu item with identifier id; otherwise
615 disables the menu item with identifier id.
616 See also isItemEnabled().
618 Examples:
620
622 If visible is TRUE, shows the menu item with id id; otherwise hides the
623 menu item with id id.
624 See also isItemVisible() and isItemEnabled().
626
628 Sets in which cases a menubar sparator is drawn to when. See the
629 "separator" property for details.
630
632 Reimplements QWidget::show() in order to set up the correct keyboard
633 accelerators and to raise itself to the top of the widget stack.
634 Example: grapher/grapher.cpp.
636 Reimplemented from QWidget.
638 Property Documentation
641 This property holds the popup orientation.
642 The default popup orientation. By default, menus pop "down" the screen.
644 By setting the property to TRUE, the menu will pop "up". You might call
645 this for menus that are below the document to which they refer.
646 If the menu would not fit on the screen, the other direction is used
648 automatically.
649 Set this property's value with setDefaultUp() and get this property's
651 value with isDefaultUp().
652
654 This property holds in which cases a menubar sparator is drawn.
655 This property is obsolete. It is provided to keep old source working.
657 We strongly advise against using it in new code.
658 Set this property's value with setSeparator() and get this property's
660 value with separator().
661
664 http://doc.trolltech.com/qmenubar.html
665 http://www.trolltech.com/faq/tech.html
666
668 Copyright 1992-2007 Trolltech ASA, http://www.trolltech.com. See the
669 license file included in the distribution for a complete license
670 statement.
671
673 Generated automatically from the source code.
674
676 If you find a bug in Qt, please report it as described in
677 http://doc.trolltech.com/bughowto.html. Good bug reports help us to
678 help you. Thank you.
679 The definitive Qt documentation is provided in HTML format; it is
681 located at $QTDIR/doc/html and can be read using Qt Assistant or with a
682 web browser. This man page is provided as a convenience for those users
683 who prefer man pages, although this format is not officially supported
684 by Trolltech.
685 If you find errors in this manual page, please report them to qt-
687 bugs@trolltech.com. Please include the name of the manual page
688 (qmenubar.3qt) and the Qt version (3.3.8).
689Trolltech AS 2 February 2007 QMenuBar(3qt)