1QPopupMenu(3qt)                                                QPopupMenu(3qt)
2
3
4

NAME

6       QPopupMenu - Popup menu widget
7

SYNOPSIS

9       #include <qpopupmenu.h>
10
11       Inherits QFrame and QMenuData.
12
13   Public Members
14       QPopupMenu ( QWidget * parent = 0, const char * name = 0 )
15       ~QPopupMenu ()
16       void popup ( const QPoint & pos, int indexAtPoint = -1 )
17       virtual void updateItem ( int id )
18       virtual void setCheckable ( bool )
19       bool isCheckable () const
20       int exec ()
21       int exec ( const QPoint & pos, int indexAtPoint = 0 )
22       virtual void setActiveItem ( int i )
23       int idAt ( int index ) const
24       int idAt ( const QPoint & pos ) const
25       int insertTearOffHandle ( int id = -1, int index = -1 )
26
27   Signals
28       void activated ( int id )
29       void highlighted ( int id )
30       void aboutToShow ()
31       void aboutToHide ()
32
33   Important Inherited Members
34       int insertItem ( const QString & text, const QObject * receiver, const
35           char * member, const QKeySequence & accel = 0, int id = -1, int
36           index = -1 )
37       int insertItem ( const QIconSet & icon, const QString & text, const
38           QObject * receiver, const char * member, const QKeySequence & accel
39           = 0, int id = -1, int index = -1 )
40       int insertItem ( const QPixmap & pixmap, const QObject * receiver,
41           const char * member, const QKeySequence & accel = 0, int id = -1,
42           int index = -1 )
43       int insertItem ( const QIconSet & icon, const QPixmap & pixmap, const
44           QObject * receiver, const char * member, const QKeySequence & accel
45           = 0, int id = -1, int index = -1 )
46       int insertItem ( const QString & text, int id = -1, int index = -1 )
47       int insertItem ( const QIconSet & icon, const QString & text, int id =
48           -1, int index = -1 )
49       int insertItem ( const QString & text, QPopupMenu * popup, int id = -1,
50           int index = -1 )
51       int insertItem ( const QIconSet & icon, const QString & text,
52           QPopupMenu * popup, int id = -1, int index = -1 )
53       int insertItem ( const QPixmap & pixmap, int id = -1, int index = -1 )
54       int insertItem ( const QIconSet & icon, const QPixmap & pixmap, int id
55           = -1, int index = -1 )
56       int insertItem ( const QPixmap & pixmap, QPopupMenu * popup, int id =
57           -1, int index = -1 )
58       int insertItem ( const QIconSet & icon, const QPixmap & pixmap,
59           QPopupMenu * popup, int id = -1, int index = -1 )
60       int insertItem ( QWidget * widget, int id = -1, int index = -1 )
61       int insertItem ( const QIconSet & icon, QCustomMenuItem * custom, int
62           id = -1, int index = -1 )
63       int insertItem ( QCustomMenuItem * custom, int id = -1, int index = -1
64           )
65       int insertSeparator ( int index = -1 )
66       void removeItem ( int id )
67       void removeItemAt ( int index )
68       void clear ()
69       QKeySequence accel ( int id ) const
70       void setAccel ( const QKeySequence & key, int id )
71       QIconSet * iconSet ( int id ) const
72       QString text ( int id ) const
73       QPixmap * pixmap ( int id ) const
74       void setWhatsThis ( int id, const QString & text )
75       QString whatsThis ( int id ) const
76       void changeItem ( int id, const QString & text )
77       void changeItem ( int id, const QPixmap & pixmap )
78       void changeItem ( int id, const QIconSet & icon, const QString & text )
79       void changeItem ( int id, const QIconSet & icon, const QPixmap & pixmap
80           )
81       bool isItemEnabled ( int id ) const
82       void setItemEnabled ( int id, bool enable )
83       bool isItemChecked ( int id ) const
84       void setItemChecked ( int id, bool check )
85       bool isItemVisible ( int id ) const
86       void setItemVisible ( int id, bool visible )
87       bool connectItem ( int id, const QObject * receiver, const char *
88           member )
89       bool disconnectItem ( int id, const QObject * receiver, const char *
90           member )
91       bool setItemParameter ( int id, int param )
92       int itemParameter ( int id ) const
93
94   Properties
95       bool checkable - whether the display of check marks on menu items is
96           enabled
97
98   Protected Members
99       int itemHeight ( int row ) const
100       int itemHeight ( QMenuItem * mi ) const
101       void drawItem ( QPainter * p, int tab_, QMenuItem * mi, bool act, int
102           x, int y, int w, int h )
103       virtual void drawContents ( QPainter * p )
104       int columns () const
105

DESCRIPTION

107       The QPopupMenu class provides a popup menu widget.
108
109       A popup menu widget is a selection menu. It can be either a pull-down
110       menu in a menu bar or a standalone context (popup) menu. Pull-down
111       menus are shown by the menu bar when the user clicks on the respective
112       item or presses the specified shortcut key. Use QMenuBar::insertItem()
113       to insert a popup menu into a menu bar. Show a context menu either
114       asynchronously with popup() or synchronously with exec().
115
116       Technically, a popup menu consists of a list of menu items. You add
117       items with insertItem(). An item is either a string, a pixmap or a
118       custom item that provides its own drawing function (see
119       QCustomMenuItem). In addition, items can have an optional icon drawn on
120       the very left side and an accelerator key such as" Ctrl+X".
121
122       There are three kinds of menu items: separators, menu items that
123       perform an action and menu items that show a submenu. Separators are
124       inserted with insertSeparator(). For submenus, you pass a pointer to a
125       QPopupMenu in your call to insertItem(). All other items are considered
126       action items.
127
128       When inserting action items you usually specify a receiver and a slot.
129       The receiver will be notifed whenever the item is selected. In
130       addition, QPopupMenu provides two signals, activated() and
131       highlighted(), which signal the identifier of the respective menu item.
132       It is sometimes practical to connect several items to one slot. To
133       distinguish between them, specify a slot that takes an integer argument
134       and use setItemParameter() to associate a unique value with each item.
135
136       You clear a popup menu with clear() and remove single items with
137       removeItem() or removeItemAt().
138
139       A popup menu can display check marks for certain items when enabled
140       with setCheckable(TRUE). You check or uncheck items with
141       setItemChecked().
142
143       Items are either enabled or disabled. You toggle their state with
144       setItemEnabled(). Just before a popup menu becomes visible, it emits
145       the aboutToShow() signal. You can use this signal to set the correct
146       enabled/disabled states of all menu items before the user sees it. The
147       corresponding aboutToHide() signal is emitted when the menu hides
148       again.
149
150       You can provide What's This? help for single menu items with
151       setWhatsThis(). See QWhatsThis for general information about this kind
152       of lightweight online help.
153
154       For ultimate flexibility, you can also add entire widgets as items into
155       a popup menu (for example, a color selector).
156
157       A QPopupMenu can also provide a tear-off menu. A tear-off menu is a
158       top-level window that contains a copy of the menu. This makes it
159       possible for the user to "tear off" frequently used menus and position
160       them in a convenient place on the screen. If you want that
161       functionality for a certain menu, insert a tear-off handle with
162       insertTearOffHandle(). When using tear-off menus, bear in mind that the
163       concept isn't typically used on Microsoft Windows so users may not be
164       familiar with it. Consider using a QToolBar instead. Tear-off menus
165       cannot contain custom widgets; if the original menu contains a custom
166       widget item, this item is omitted.
167
168       menu/menu.cpp is an example of QMenuBar and QPopupMenu use.
169
170                                   [Image Omitted]
171
172                                   [Image Omitted]
173
174       See also QMenuBar, GUI Design Handbook: Menu, Drop-Down and Pop-Up,
175       Main Window and Related Classes, and Basic Widgets.
176

MEMBER FUNCTION DOCUMENTATION

QPopupMenu::QPopupMenu ( QWidget * parent = 0, const char * name = 0 )

179       Constructs a popup menu called name with parent parent.
180
181       Although a popup menu is always a top-level widget, if a parent is
182       passed the popup menu will be deleted when that parent is destroyed (as
183       with any other QObject).
184

QPopupMenu::~QPopupMenu ()

186       Destroys the popup menu.
187

void QPopupMenu::aboutToHide () [signal]

189       This signal is emitted just before the popup menu is hidden after it
190       has been displayed.
191
192       Warning: Do not open a widget in a slot connected to this signal.
193
194       See also aboutToShow(), setItemEnabled(), setItemChecked(),
195       insertItem(), and removeItem().
196

void QPopupMenu::aboutToShow () [signal]

198       This signal is emitted just before the popup menu is displayed. You can
199       connect it to any slot that sets up the menu contents (e.g. to ensure
200       that the right items are enabled).
201
202       See also aboutToHide(), setItemEnabled(), setItemChecked(),
203       insertItem(), and removeItem().
204
205       Example: mdi/application.cpp.
206

QKeySequence QMenuData::accel ( int id ) const

208       Returns the accelerator key that has been defined for the menu item id,
209       or 0 if it has no accelerator key or if there is no such menu item.
210
211       See also setAccel(), QAccel, and qnamespace.h.
212

void QPopupMenu::activated ( int id ) [signal]

214       This signal is emitted when a menu item is selected; id is the id of
215       the selected item.
216
217       Normally, you connect each menu item to a single slot using
218       QMenuData::insertItem(), but sometimes you will want to connect several
219       items to a single slot (most often if the user selects from an array).
220       This signal is useful in such cases.
221
222       See also highlighted() and QMenuData::insertItem().
223
224       Examples:
225

void QMenuData::changeItem ( int id, const QString & text )

227       Changes the text of the menu item id to text. If the item has an icon,
228       the icon remains unchanged.
229
230       See also text().
231

void QMenuData::changeItem ( int id, const QPixmap & pixmap )

233       This is an overloaded member function, provided for convenience. It
234       behaves essentially like the above function.
235
236       Changes the pixmap of the menu item id to the pixmap pixmap. If the
237       item has an icon, the icon is unchanged.
238
239       See also pixmap().
240

void QMenuData::changeItem ( int id, const QIconSet & icon, const QString &

242       text )
243       This is an overloaded member function, provided for convenience. It
244       behaves essentially like the above function.
245
246       Changes the iconset and text of the menu item id to the icon and text
247       respectively.
248
249       See also pixmap().
250

void QMenuData::changeItem ( int id, const QIconSet & icon, const QPixmap &

252       pixmap )
253       This is an overloaded member function, provided for convenience. It
254       behaves essentially like the above function.
255
256       Changes the iconset and pixmap of the menu item id to icon and pixmap
257       respectively.
258
259       See also pixmap().
260

void QMenuData::clear ()

262       Removes all menu items.
263
264       See also removeItem() and removeItemAt().
265
266       Examples:
267

int QPopupMenu::columns () const [protected]

269       If a popup menu does not fit on the screen it lays itself out so that
270       it does fit. It is style dependent what layout means (for example, on
271       Windows it will use multiple columns).
272
273       This functions returns the number of columns necessary.
274
275       See also sizeHint.
276

bool QMenuData::connectItem ( int id, const QObject * receiver, const char *

278       member )
279       Connects the menu item with identifier id to receiver's member slot or
280       signal.
281
282       The receiver's slot (or signal) is activated when the menu item is
283       activated.
284
285       See also disconnectItem() and setItemParameter().
286
287       Example: menu/menu.cpp.
288

bool QMenuData::disconnectItem ( int id, const QObject * receiver, const char

290       * member )
291       Disconnects the receiver's member from the menu item with identifier
292       id.
293
294       All connections are removed when the menu data object is destroyed.
295
296       See also connectItem() and setItemParameter().
297

void QPopupMenu::drawContents ( QPainter * p ) [virtual protected]

299       Draws all menu items using painter p.
300
301       Reimplemented from QFrame.
302

void QPopupMenu::drawItem ( QPainter * p, int tab_, QMenuItem * mi, bool act,

304       int x, int y, int w, int h ) [protected]
305       Draws menu item mi in the area x, y, w, h, using painter p. The item is
306       drawn active if act is TRUE or drawn inactive if act is FALSE. The
307       rightmost tab_ pixels are used for accelerator text.
308
309       See also QStyle::drawControl().
310

int QPopupMenu::exec ()

312       Executes this popup synchronously.
313
314       This is equivalent to exec(mapToGlobal(QPoint(0,0))). In most
315       situations you'll want to specify the position yourself, for example at
316       the current mouse position:
317
318               exec(QCursor::pos());
319       or aligned to a widget:
320
321               exec(somewidget.mapToGlobal(QPoint(0,0)));
322
323       Examples:
324

int QPopupMenu::exec ( const QPoint & pos, int indexAtPoint = 0 )

326       This is an overloaded member function, provided for convenience. It
327       behaves essentially like the above function.
328
329       Executes this popup synchronously.
330
331       Opens the popup menu so that the item number indexAtPoint will be at
332       the specified global position pos. To translate a widget's local
333       coordinates into global coordinates, use QWidget::mapToGlobal().
334
335       The return code is the id of the selected item in either the popup menu
336       or one of its submenus, or -1 if no item is selected (normally because
337       the user pressed Esc).
338
339       Note that all signals are emitted as usual. If you connect a menu item
340       to a slot and call the menu's exec(), you get the result both via the
341       signal-slot connection and in the return value of exec().
342
343       Common usage is to position the popup at the current mouse position:
344
345               exec( QCursor::pos() );
346       or aligned to a widget:
347
348               exec( somewidget.mapToGlobal(QPoint(0, 0)) );
349
350       When positioning a popup with exec() or popup(), bear in mind that you
351       cannot rely on the popup menu's current size(). For performance
352       reasons, the popup adapts its size only when necessary. So in many
353       cases, the size before and after the show is different. Instead, use
354       sizeHint(). It calculates the proper size depending on the menu's
355       current contents.
356
357       See also popup() and sizeHint.
358

void QPopupMenu::highlighted ( int id ) [signal]

360       This signal is emitted when a menu item is highlighted; id is the id of
361       the highlighted item.
362
363       See also activated() and QMenuData::insertItem().
364

QIconSet * QMenuData::iconSet ( int id ) const

366       Returns the icon set that has been set for menu item id, or 0 if no
367       icon set has been set.
368
369       See also changeItem(), text(), and pixmap().
370

int QPopupMenu::idAt ( int index ) const

372       Returns the identifier of the menu item at position index in the
373       internal list, or -1 if index is out of range.
374
375       See also QMenuData::setId() and QMenuData::indexOf().
376
377       Example: scrollview/scrollview.cpp.
378

int QPopupMenu::idAt ( const QPoint & pos ) const

380       This is an overloaded member function, provided for convenience. It
381       behaves essentially like the above function.
382
383       Returns the id of the item at pos, or -1 if there is no item there or
384       if it is a separator.
385

int QMenuData::insertItem ( const QString & text, const QObject * receiver,

387       const char * member, const QKeySequence & accel = 0, int id = -1, int
388       index = -1 )
389       The family of insertItem() functions inserts menu items into a popup
390       menu or a menu bar.
391
392       A menu item is usually either a text string or a pixmap, both with an
393       optional icon or keyboard accelerator. For special cases it is also
394       possible to insert custom items (see QCustomMenuItem) or even widgets
395       into popup menus.
396
397       Some insertItem() members take a popup menu as an additional argument.
398       Use this to insert submenus into existing menus or pulldown menus into
399       a menu bar.
400
401       The number of insert functions may look confusing, but they are
402       actually quite simple to use.
403
404       This default version inserts a menu item with the text text, the
405       accelerator key accel, an id and an optional index and connects it to
406       the slot member in the object receiver.
407
408       Example:
409
410               QMenuBar   *mainMenu = new QMenuBar;
411               QPopupMenu *fileMenu = new QPopupMenu;
412               fileMenu->insertItem( "New",  myView, SLOT(newFile()), CTRL+Key_N );
413               fileMenu->insertItem( "Open", myView, SLOT(open()),    CTRL+Key_O );
414               mainMenu->insertItem( "File", fileMenu );
415
416       Not all insert functions take an object/slot parameter or an
417       accelerator key. Use connectItem() and setAccel() on those items.
418
419       If you need to translate accelerators, use tr() with the text and
420       accelerator. (For translations use a string key sequence.):
421
422               fileMenu->insertItem( tr("Open"), myView, SLOT(open()),
423                                     tr("Ctrl+O") );
424
425       In the example above, pressing Ctrl+O or selecting "Open" from the menu
426       activates the myView->open() function.
427
428       Some insert functions take a QIconSet parameter to specify the little
429       menu item icon. Note that you can always pass a QPixmap object instead.
430
431       The id specifies the identification number associated with the menu
432       item. Note that only positive values are valid, as a negative value
433       will make Qt select a unique id for the item.
434
435       The index specifies the position in the menu. The menu item is appended
436       at the end of the list if index is negative.
437
438       Note that keyboard accelerators in Qt are not application-global,
439       instead they are bound to a certain top-level window. For example,
440       accelerators in QPopupMenu items only work for menus that are
441       associated with a certain window. This is true for popup menus that
442       live in a menu bar since their accelerators will then be installed in
443       the menu bar itself. This also applies to stand-alone popup menus that
444       have a top-level widget in their parentWidget() chain. The menu will
445       then install its accelerator object on that top-level widget. For all
446       other cases use an independent QAccel object.
447
448       Warning: Be careful when passing a literal 0 to insertItem() because
449       some C++ compilers choose the wrong overloaded function. Cast the 0 to
450       what you mean, e.g. (QObject*)0.
451
452       Warning: On Mac OS X, items that connect to a slot that are inserted
453       into a menubar will not function as we use the native menubar that
454       knows nothing about signals or slots. Instead insert the items into a
455       popup menu and insert the popup menu into the menubar. This may be
456       fixed in a future Qt version.
457
458       Returns the allocated menu identifier number (id if id >= 0).
459
460       See also removeItem(), changeItem(), setAccel(), connectItem(), QAccel,
461       and qnamespace.h.
462
463       Examples:
464

int QMenuData::insertItem ( const QIconSet & icon, const QString & text, const

466       QObject * receiver, const char * member, const QKeySequence & accel =
467       0, int id = -1, int index = -1 )
468       This is an overloaded member function, provided for convenience. It
469       behaves essentially like the above function.
470
471       Inserts a menu item with icon icon, text text, accelerator accel,
472       optional id id, and optional index position. The menu item is connected
473       it to the receiver's member slot. The icon will be displayed to the
474       left of the text in the item.
475
476       Returns the allocated menu identifier number (id if id >= 0).
477
478       See also removeItem(), changeItem(), setAccel(), connectItem(), QAccel,
479       and qnamespace.h.
480

int QMenuData::insertItem ( const QPixmap & pixmap, const QObject * receiver,

482       const char * member, const QKeySequence & accel = 0, int id = -1, int
483       index = -1 )
484       This is an overloaded member function, provided for convenience. It
485       behaves essentially like the above function.
486
487       Inserts a menu item with pixmap pixmap, accelerator accel, optional id
488       id, and optional index position. The menu item is connected it to the
489       receiver's member slot. The icon will be displayed to the left of the
490       text in the item.
491
492       To look best when being highlighted as a menu item, the pixmap should
493       provide a mask (see QPixmap::mask()).
494
495       Returns the allocated menu identifier number (id if id >= 0).
496
497       See also removeItem(), changeItem(), setAccel(), and connectItem().
498

int QMenuData::insertItem ( const QIconSet & icon, const QPixmap & pixmap,

500       const QObject * receiver, const char * member, const QKeySequence &
501       accel = 0, int id = -1, int index = -1 )
502       This is an overloaded member function, provided for convenience. It
503       behaves essentially like the above function.
504
505       Inserts a menu item with icon icon, pixmap pixmap, accelerator accel,
506       optional id id, and optional index position. The icon will be displayed
507       to the left of the pixmap in the item. The item is connected to the
508       member slot in the receiver object.
509
510       To look best when being highlighted as a menu item, the pixmap should
511       provide a mask (see QPixmap::mask()).
512
513       Returns the allocated menu identifier number (id if id >= 0).
514
515       See also removeItem(), changeItem(), setAccel(), connectItem(), QAccel,
516       and qnamespace.h.
517

int QMenuData::insertItem ( const QString & text, int id = -1, int index = -1

519       )
520       This is an overloaded member function, provided for convenience. It
521       behaves essentially like the above function.
522
523       Inserts a menu item with text text, optional id id, and optional index
524       position.
525
526       Returns the allocated menu identifier number (id if id >= 0).
527
528       See also removeItem(), changeItem(), setAccel(), and connectItem().
529

int QMenuData::insertItem ( const QIconSet & icon, const QString & text, int

531       id = -1, int index = -1 )
532       This is an overloaded member function, provided for convenience. It
533       behaves essentially like the above function.
534
535       Inserts a menu item with icon icon, text text, optional id id, and
536       optional index position. The icon will be displayed to the left of the
537       text in the item.
538
539       Returns the allocated menu identifier number (id if id >= 0).
540
541       See also removeItem(), changeItem(), setAccel(), and connectItem().
542

int QMenuData::insertItem ( const QString & text, QPopupMenu * popup, int id =

544       -1, int index = -1 )
545       This is an overloaded member function, provided for convenience. It
546       behaves essentially like the above function.
547
548       Inserts a menu item with text text, submenu popup, optional id id, and
549       optional index position.
550
551       The popup must be deleted by the programmer or by its parent widget. It
552       is not deleted when this menu item is removed or when the menu is
553       deleted.
554
555       Returns the allocated menu identifier number (id if id >= 0).
556
557       See also removeItem(), changeItem(), setAccel(), and connectItem().
558

int QMenuData::insertItem ( const QIconSet & icon, const QString & text,

560       QPopupMenu * popup, int id = -1, int index = -1 )
561       This is an overloaded member function, provided for convenience. It
562       behaves essentially like the above function.
563
564       Inserts a menu item with icon icon, text text, submenu popup, optional
565       id id, and optional index position. The icon will be displayed to the
566       left of the text in the item.
567
568       The popup must be deleted by the programmer or by its parent widget. It
569       is not deleted when this menu item is removed or when the menu is
570       deleted.
571
572       Returns the allocated menu identifier number (id if id >= 0).
573
574       See also removeItem(), changeItem(), setAccel(), and connectItem().
575

int QMenuData::insertItem ( const QPixmap & pixmap, int id = -1, int index =

577       -1 )
578       This is an overloaded member function, provided for convenience. It
579       behaves essentially like the above function.
580
581       Inserts a menu item with pixmap pixmap, optional id id, and optional
582       index position.
583
584       To look best when being highlighted as a menu item, the pixmap should
585       provide a mask (see QPixmap::mask()).
586
587       Returns the allocated menu identifier number (id if id >= 0).
588
589       See also removeItem(), changeItem(), setAccel(), and connectItem().
590

int QMenuData::insertItem ( const QIconSet & icon, const QPixmap & pixmap, int

592       id = -1, int index = -1 )
593       This is an overloaded member function, provided for convenience. It
594       behaves essentially like the above function.
595
596       Inserts a menu item with icon icon, pixmap pixmap, optional id id, and
597       optional index position. The icon will be displayed to the left of the
598       pixmap in the item.
599
600       Returns the allocated menu identifier number (id if id >= 0).
601
602       See also removeItem(), changeItem(), setAccel(), and connectItem().
603

int QMenuData::insertItem ( const QPixmap & pixmap, QPopupMenu * popup, int id

605       = -1, int index = -1 )
606       This is an overloaded member function, provided for convenience. It
607       behaves essentially like the above function.
608
609       Inserts a menu item with pixmap pixmap, submenu popup, optional id id,
610       and optional index position.
611
612       The popup must be deleted by the programmer or by its parent widget. It
613       is not deleted when this menu item is removed or when the menu is
614       deleted.
615
616       Returns the allocated menu identifier number (id if id >= 0).
617
618       See also removeItem(), changeItem(), setAccel(), and connectItem().
619

int QMenuData::insertItem ( const QIconSet & icon, const QPixmap & pixmap,

621       QPopupMenu * popup, int id = -1, int index = -1 )
622       This is an overloaded member function, provided for convenience. It
623       behaves essentially like the above function.
624
625       Inserts a menu item with icon icon, pixmap pixmap submenu popup,
626       optional id id, and optional index position. The icon will be displayed
627       to the left of the pixmap in the item.
628
629       The popup must be deleted by the programmer or by its parent widget. It
630       is not deleted when this menu item is removed or when the menu is
631       deleted.
632
633       Returns the allocated menu identifier number (id if id >= 0).
634
635       See also removeItem(), changeItem(), setAccel(), and connectItem().
636

int QMenuData::insertItem ( QWidget * widget, int id = -1, int index = -1 )

638       This is an overloaded member function, provided for convenience. It
639       behaves essentially like the above function.
640
641       Inserts a menu item that consists of the widget widget with optional id
642       id, and optional index position.
643
644       Ownership of widget is transferred to the popup menu or to the menu
645       bar.
646
647       Theoretically, any widget can be inserted into a popup menu. In
648       practice, this only makes sense with certain widgets.
649
650       If a widget is not focus-enabled (see QWidget::isFocusEnabled()), the
651       menu treats it as a separator; this means that the item is not
652       selectable and will never get focus. In this way you can, for example,
653       simply insert a QLabel if you need a popup menu with a title.
654
655       If the widget is focus-enabled it will get focus when the user
656       traverses the popup menu with the arrow keys. If the widget does not
657       accept ArrowUp and ArrowDown in its key event handler, the focus will
658       move back to the menu when the respective arrow key is hit one more
659       time. This works with a QLineEdit, for example. If the widget accepts
660       the arrow key itself, it must also provide the possibility to put the
661       focus back on the menu again by calling QWidget::focusNextPrevChild().
662       Futhermore, if the embedded widget closes the menu when the user made a
663       selection, this can be done safely by calling:
664
665               if ( isVisible() &&
666                    parentWidget() &&
667                    parentWidget()->inherits("QPopupMenu") )
668                   parentWidget()->close();
669
670       Returns the allocated menu identifier number (id if id >= 0).
671
672       See also removeItem().
673

int QMenuData::insertItem ( const QIconSet & icon, QCustomMenuItem * custom,

675       int id = -1, int index = -1 )
676       This is an overloaded member function, provided for convenience. It
677       behaves essentially like the above function.
678
679       Inserts a custom menu item custom with an icon and with optional id id,
680       and optional index position.
681
682       This only works with popup menus. It is not supported for menu bars.
683       Ownership of custom is transferred to the popup menu.
684
685       If you want to connect a custom item to a slot, use connectItem().
686
687       Returns the allocated menu identifier number (id if id >= 0).
688
689       See also connectItem(), removeItem(), and QCustomMenuItem.
690

int QMenuData::insertItem ( QCustomMenuItem * custom, int id = -1, int index =

692       -1 )
693       This is an overloaded member function, provided for convenience. It
694       behaves essentially like the above function.
695
696       Inserts a custom menu item custom with optional id id, and optional
697       index position.
698
699       This only works with popup menus. It is not supported for menu bars.
700       Ownership of custom is transferred to the popup menu.
701
702       If you want to connect a custom item to a slot, use connectItem().
703
704       Returns the allocated menu identifier number (id if id >= 0).
705
706       See also connectItem(), removeItem(), and QCustomMenuItem.
707

int QMenuData::insertSeparator ( int index = -1 )

709       Inserts a separator at position index, and returns the menu identifier
710       number allocated to it. The separator becomes the last menu item if
711       index is negative.
712
713       In a popup menu a separator is rendered as a horizontal line. In a
714       Motif menu bar a separator is spacing, so the rest of the items
715       (normally just "Help") are drawn right-justified. In a Windows menu bar
716       separators are ignored (to comply with the Windows style guidelines).
717
718       Examples:
719

int QPopupMenu::insertTearOffHandle ( int id = -1, int index = -1 )

721       Inserts a tear-off handle into the menu. A tear-off handle is a special
722       menu item that creates a copy of the menu when the menu is selected.
723       This "torn-off" copy lives in a separate window. It contains the same
724       menu items as the original menu, with the exception of the tear-off
725       handle.
726
727       The handle item is assigned the identifier id or an automatically
728       generated identifier if id is < 0. The generated identifiers (negative
729       integers) are guaranteed to be unique within the entire application.
730
731       The index specifies the position in the menu. The tear-off handle is
732       appended at the end of the list if index is negative.
733
734       Example: menu/menu.cpp.
735

bool QPopupMenu::isCheckable () const

737       Returns TRUE if the display of check marks on menu items is enabled;
738       otherwise returns FALSE. See the "checkable" property for details.
739

bool QMenuData::isItemChecked ( int id ) const

741       Returns TRUE if the menu item with the id id has been checked;
742       otherwise returns FALSE.
743
744       See also setItemChecked().
745
746       Examples:
747

bool QMenuData::isItemEnabled ( int id ) const

749       Returns TRUE if the item with identifier id is enabled; otherwise
750       returns FALSE
751
752       See also setItemEnabled() and isItemVisible().
753

bool QMenuData::isItemVisible ( int id ) const

755       Returns TRUE if the menu item with the id id is visible; otherwise
756       returns FALSE.
757
758       See also setItemVisible().
759

int QPopupMenu::itemHeight ( int row ) const [protected]

761       Calculates the height in pixels of the item in row row.
762

int QPopupMenu::itemHeight ( QMenuItem * mi ) const [protected]

764       This is an overloaded member function, provided for convenience. It
765       behaves essentially like the above function.
766
767       Calculates the height in pixels of the menu item mi.
768

int QMenuData::itemParameter ( int id ) const

770       Returns the parameter of the activation signal of item id.
771
772       If no parameter has been specified for this item with
773       setItemParameter(), the value defaults to id.
774
775       See also connectItem(), disconnectItem(), and setItemParameter().
776

QPixmap * QMenuData::pixmap ( int id ) const

778       Returns the pixmap that has been set for menu item id, or 0 if no
779       pixmap has been set.
780
781       See also changeItem(), text(), and iconSet().
782

void QPopupMenu::popup ( const QPoint & pos, int indexAtPoint = -1 )

784       Displays the popup menu so that the item number indexAtPoint will be at
785       the specified global position pos. To translate a widget's local
786       coordinates into global coordinates, use QWidget::mapToGlobal().
787
788       When positioning a popup with exec() or popup(), bear in mind that you
789       cannot rely on the popup menu's current size(). For performance
790       reasons, the popup adapts its size only when necessary, so in many
791       cases, the size before and after the show is different. Instead, use
792       sizeHint(). It calculates the proper size depending on the menu's
793       current contents.
794
795       Example: listviews/listviews.cpp.
796

void QMenuData::removeItem ( int id )

798       Removes the menu item that has the identifier id.
799
800       See also removeItemAt() and clear().
801
802       Example: chart/chartform.cpp.
803

void QMenuData::removeItemAt ( int index )

805       Removes the menu item at position index.
806
807       See also removeItem() and clear().
808

void QMenuData::setAccel ( const QKeySequence & key, int id )

810       Sets the accelerator key for the menu item id to key.
811
812       An accelerator key consists of a key code and a combination of the
813       modifiers SHIFT, CTRL, ALT or UNICODE_ACCEL (OR'ed or added). The
814       header file qnamespace.h contains a list of key codes.
815
816       Defining an accelerator key produces a text that is added to the menu
817       item; for instance, CTRL + Key_O produces "Ctrl+O". The text is
818       formatted differently for different platforms.
819
820       Note that keyboard accelerators in Qt are not application-global,
821       instead they are bound to a certain top-level window. For example,
822       accelerators in QPopupMenu items only work for menus that are
823       associated with a certain window. This is true for popup menus that
824       live in a menu bar since their accelerators will then be installed in
825       the menu bar itself. This also applies to stand-alone popup menus that
826       have a top-level widget in their parentWidget() chain. The menu will
827       then install its accelerator object on that top-level widget. For all
828       other cases use an independent QAccel object.
829
830       Example:
831
832               QMenuBar *mainMenu = new QMenuBar;
833               QPopupMenu *fileMenu = new QPopupMenu;       // file sub menu
834               fileMenu->insertItem( "Open Document", 67 ); // add "Open" item
835               fileMenu->setAccel( CTRL + Key_O, 67 );      // Ctrl+O to open
836               fileMenu->insertItem( "Quit", 69 );          // add "Quit" item
837               fileMenu->setAccel( CTRL + ALT + Key_Delete, 69 ); // add Alt+Del to quit
838               mainMenu->insertItem( "File", fileMenu );    // add the file menu
839
840       If you need to translate accelerators, use tr() with a string:
841
842               fileMenu->setAccel( tr("Ctrl+O"), 67 );
843
844       You can also specify the accelerator in the insertItem() function. You
845       may prefer to use QAction to associate accelerators with menu items.
846
847       See also accel(), insertItem(), QAccel, and QAction.
848
849       Example: menu/menu.cpp.
850

void QPopupMenu::setActiveItem ( int i ) [virtual]

852       Sets the currently active item to index i and repaints as necessary.
853

void QPopupMenu::setCheckable ( bool ) [virtual]

855       Sets whether the display of check marks on menu items is enabled. See
856       the "checkable" property for details.
857

void QMenuData::setItemChecked ( int id, bool check )

859       If check is TRUE, checks the menu item with id id; otherwise unchecks
860       the menu item with id id. Calls QPopupMenu::setCheckable( TRUE ) if
861       necessary.
862
863       See also isItemChecked().
864
865       Examples:
866

void QMenuData::setItemEnabled ( int id, bool enable )

868       If enable is TRUE, enables the menu item with identifier id; otherwise
869       disables the menu item with identifier id.
870
871       See also isItemEnabled().
872
873       Examples:
874

bool QMenuData::setItemParameter ( int id, int param )

876       Sets the parameter of the activation signal of item id to param.
877
878       If any receiver takes an integer parameter, this value is passed.
879
880       See also connectItem(), disconnectItem(), and itemParameter().
881
882       Example: mdi/application.cpp.
883

void QMenuData::setItemVisible ( int id, bool visible )

885       If visible is TRUE, shows the menu item with id id; otherwise hides the
886       menu item with id id.
887
888       See also isItemVisible() and isItemEnabled().
889

void QMenuData::setWhatsThis ( int id, const QString & text )

891       Sets text as What's This help for the menu item with identifier id.
892
893       See also whatsThis().
894
895       Examples:
896

QString QMenuData::text ( int id ) const

898       Returns the text that has been set for menu item id, or QString::null
899       if no text has been set.
900
901       See also changeItem(), pixmap(), and iconSet().
902
903       Examples:
904

void QPopupMenu::updateItem ( int id ) [virtual]

906       Updates the item with identity id.
907
908       Reimplemented from QMenuData.
909

QString QMenuData::whatsThis ( int id ) const

911       Returns the What's This help text for the item with identifier id or
912       QString::null if no text has yet been defined.
913
914       See also setWhatsThis().
915
916   Property Documentation

bool checkable

918       This property holds whether the display of check marks on menu items is
919       enabled.
920
921       When TRUE, the display of check marks on menu items is enabled.
922       Checking is always enabled when in Windows-style.
923
924       See also QMenuData::setItemChecked().
925
926       Set this property's value with setCheckable() and get this property's
927       value with isCheckable().
928
929

SEE ALSO

931       http://doc.trolltech.com/qpopupmenu.html
932       http://www.trolltech.com/faq/tech.html
933
935       Copyright 1992-2007 Trolltech ASA, http://www.trolltech.com.  See the
936       license file included in the distribution for a complete license
937       statement.
938

AUTHOR

940       Generated automatically from the source code.
941

BUGS

943       If you find a bug in Qt, please report it as described in
944       http://doc.trolltech.com/bughowto.html.  Good bug reports help us to
945       help you. Thank you.
946
947       The definitive Qt documentation is provided in HTML format; it is
948       located at $QTDIR/doc/html and can be read using Qt Assistant or with a
949       web browser. This man page is provided as a convenience for those users
950       who prefer man pages, although this format is not officially supported
951       by Trolltech.
952
953       If you find errors in this manual page, please report them to qt-
954       bugs@trolltech.com.  Please include the name of the manual page
955       (qpopupmenu.3qt) and the Qt version (3.3.8).
956
957
958
959Trolltech AS                    2 February 2007                QPopupMenu(3qt)
Impressum