source: trunk/doc/html/qpopupmenu.html

Last change on this file was 190, checked in by rudi, 14 years ago

reference documentation added
File size: 61.4 KB
Line 
1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
2<!-- /home/espenr/tmp/qt-3.3.8-espenr-2499/qt-x11-free-3.3.8/src/widgets/qpopupmenu.cpp:126 -->
3<html>
4<head>
5<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
6<title>QPopupMenu Class</title>
7<style type="text/css"><!--
8fn { margin-left: 1cm; text-indent: -1cm; }
9a:link { color: #004faf; text-decoration: none }
10a:visited { color: #672967; text-decoration: none }
11body { background: #ffffff; color: black; }
12--></style>
13</head>
14<body>
15
16<table border="0" cellpadding="0" cellspacing="0" width="100%">
17<tr bgcolor="#E5E5E5">
18<td valign=center>
19 <a href="index.html">
20<font color="#004faf">Home</font></a>
21 | <a href="classes.html">
22<font color="#004faf">All&nbsp;Classes</font></a>
23 | <a href="mainclasses.html">
24<font color="#004faf">Main&nbsp;Classes</font></a>
25 | <a href="annotated.html">
26<font color="#004faf">Annotated</font></a>
27 | <a href="groups.html">
28<font color="#004faf">Grouped&nbsp;Classes</font></a>
29 | <a href="functions.html">
30<font color="#004faf">Functions</font></a>
31</td>
32<td align="right" valign="center"><img src="logo32.png" align="right" width="64" height="32" border="0"></td></tr></table><h1 align=center>QPopupMenu Class Reference</h1>
33
34<p>The QPopupMenu class provides a popup menu widget.
35<a href="#details">More...</a>
36<p><tt>#include &lt;<a href="qpopupmenu-h.html">qpopupmenu.h</a>&gt;</tt>
37<p>Inherits <a href="qframe.html">QFrame</a> and <a href="qmenudata.html">QMenuData</a>.
38<p><a href="qpopupmenu-members.html">List of all member functions.</a>
39<h2>Public Members</h2>
40<ul>
41<li class=fn><a href="#QPopupMenu"><b>QPopupMenu</b></a> ( QWidget&nbsp;*&nbsp;parent = 0, const&nbsp;char&nbsp;*&nbsp;name = 0 )</li>
42<li class=fn><a href="#~QPopupMenu"><b>~QPopupMenu</b></a> ()</li>
43<li class=fn>void <a href="#popup"><b>popup</b></a> ( const&nbsp;QPoint&nbsp;&amp;&nbsp;pos, int&nbsp;indexAtPoint = -1 )</li>
44<li class=fn>virtual void <a href="#updateItem"><b>updateItem</b></a> ( int&nbsp;id )</li>
45<li class=fn>virtual void <a href="#setCheckable"><b>setCheckable</b></a> ( bool )</li>
46<li class=fn>bool <a href="#isCheckable"><b>isCheckable</b></a> () const</li>
47<li class=fn>int <a href="#exec"><b>exec</b></a> ()</li>
48<li class=fn>int <a href="#exec-2"><b>exec</b></a> ( const&nbsp;QPoint&nbsp;&amp;&nbsp;pos, int&nbsp;indexAtPoint = 0 )</li>
49<li class=fn>virtual void <a href="#setActiveItem"><b>setActiveItem</b></a> ( int&nbsp;i )</li>
50<li class=fn>int <a href="#idAt"><b>idAt</b></a> ( int&nbsp;index ) const</li>
51<li class=fn>int <a href="#idAt-2"><b>idAt</b></a> ( const&nbsp;QPoint&nbsp;&amp;&nbsp;pos ) const</li>
52<li class=fn>int <a href="#insertTearOffHandle"><b>insertTearOffHandle</b></a> ( int&nbsp;id = -1, int&nbsp;index = -1 )</li>
53</ul>
54<h2>Signals</h2>
55<ul>
56<li class=fn>void <a href="#activated"><b>activated</b></a> ( int&nbsp;id )</li>
57<li class=fn>void <a href="#highlighted"><b>highlighted</b></a> ( int&nbsp;id )</li>
58<li class=fn>void <a href="#aboutToShow"><b>aboutToShow</b></a> ()</li>
59<li class=fn>void <a href="#aboutToHide"><b>aboutToHide</b></a> ()</li>
60</ul>
61<h2>Important Inherited Members</h2>
62<ul>
63<li class=fn>int <a href="#insertItem"><b>insertItem</b></a> ( const&nbsp;QString&nbsp;&amp;&nbsp;text, const&nbsp;QObject&nbsp;*&nbsp;receiver, const&nbsp;char&nbsp;*&nbsp;member, const&nbsp;QKeySequence&nbsp;&amp;&nbsp;accel = 0, int&nbsp;id = -1, int&nbsp;index = -1 )</li>
64<li class=fn>int <a href="#insertItem-2"><b>insertItem</b></a> ( const&nbsp;QIconSet&nbsp;&amp;&nbsp;icon, const&nbsp;QString&nbsp;&amp;&nbsp;text, const&nbsp;QObject&nbsp;*&nbsp;receiver, const&nbsp;char&nbsp;*&nbsp;member, const&nbsp;QKeySequence&nbsp;&amp;&nbsp;accel = 0, int&nbsp;id = -1, int&nbsp;index = -1 )</li>
65<li class=fn>int <a href="#insertItem-3"><b>insertItem</b></a> ( const&nbsp;QPixmap&nbsp;&amp;&nbsp;pixmap, const&nbsp;QObject&nbsp;*&nbsp;receiver, const&nbsp;char&nbsp;*&nbsp;member, const&nbsp;QKeySequence&nbsp;&amp;&nbsp;accel = 0, int&nbsp;id = -1, int&nbsp;index = -1 )</li>
66<li class=fn>int <a href="#insertItem-4"><b>insertItem</b></a> ( const&nbsp;QIconSet&nbsp;&amp;&nbsp;icon, const&nbsp;QPixmap&nbsp;&amp;&nbsp;pixmap, const&nbsp;QObject&nbsp;*&nbsp;receiver, const&nbsp;char&nbsp;*&nbsp;member, const&nbsp;QKeySequence&nbsp;&amp;&nbsp;accel = 0, int&nbsp;id = -1, int&nbsp;index = -1 )</li>
67<li class=fn>int <a href="#insertItem-5"><b>insertItem</b></a> ( const&nbsp;QString&nbsp;&amp;&nbsp;text, int&nbsp;id = -1, int&nbsp;index = -1 )</li>
68<li class=fn>int <a href="#insertItem-6"><b>insertItem</b></a> ( const&nbsp;QIconSet&nbsp;&amp;&nbsp;icon, const&nbsp;QString&nbsp;&amp;&nbsp;text, int&nbsp;id = -1, int&nbsp;index = -1 )</li>
69<li class=fn>int <a href="#insertItem-7"><b>insertItem</b></a> ( const&nbsp;QString&nbsp;&amp;&nbsp;text, QPopupMenu&nbsp;*&nbsp;popup, int&nbsp;id = -1, int&nbsp;index = -1 )</li>
70<li class=fn>int <a href="#insertItem-8"><b>insertItem</b></a> ( const&nbsp;QIconSet&nbsp;&amp;&nbsp;icon, const&nbsp;QString&nbsp;&amp;&nbsp;text, QPopupMenu&nbsp;*&nbsp;popup, int&nbsp;id = -1, int&nbsp;index = -1 )</li>
71<li class=fn>int <a href="#insertItem-9"><b>insertItem</b></a> ( const&nbsp;QPixmap&nbsp;&amp;&nbsp;pixmap, int&nbsp;id = -1, int&nbsp;index = -1 )</li>
72<li class=fn>int <a href="#insertItem-a"><b>insertItem</b></a> ( const&nbsp;QIconSet&nbsp;&amp;&nbsp;icon, const&nbsp;QPixmap&nbsp;&amp;&nbsp;pixmap, int&nbsp;id = -1, int&nbsp;index = -1 )</li>
73<li class=fn>int <a href="#insertItem-b"><b>insertItem</b></a> ( const&nbsp;QPixmap&nbsp;&amp;&nbsp;pixmap, QPopupMenu&nbsp;*&nbsp;popup, int&nbsp;id = -1, int&nbsp;index = -1 )</li>
74<li class=fn>int <a href="#insertItem-c"><b>insertItem</b></a> ( const&nbsp;QIconSet&nbsp;&amp;&nbsp;icon, const&nbsp;QPixmap&nbsp;&amp;&nbsp;pixmap, QPopupMenu&nbsp;*&nbsp;popup, int&nbsp;id = -1, int&nbsp;index = -1 )</li>
75<li class=fn>int <a href="#insertItem-d"><b>insertItem</b></a> ( QWidget&nbsp;*&nbsp;widget, int&nbsp;id = -1, int&nbsp;index = -1 )</li>
76<li class=fn>int <a href="#insertItem-e"><b>insertItem</b></a> ( const&nbsp;QIconSet&nbsp;&amp;&nbsp;icon, QCustomMenuItem&nbsp;*&nbsp;custom, int&nbsp;id = -1, int&nbsp;index = -1 )</li>
77<li class=fn>int <a href="#insertItem-f"><b>insertItem</b></a> ( QCustomMenuItem&nbsp;*&nbsp;custom, int&nbsp;id = -1, int&nbsp;index = -1 )</li>
78<li class=fn>int <a href="#insertSeparator"><b>insertSeparator</b></a> ( int&nbsp;index = -1 )</li>
79<li class=fn>void <a href="#removeItem"><b>removeItem</b></a> ( int&nbsp;id )</li>
80<li class=fn>void <a href="#removeItemAt"><b>removeItemAt</b></a> ( int&nbsp;index )</li>
81<li class=fn>void <a href="#clear"><b>clear</b></a> ()</li>
82<li class=fn>QKeySequence <a href="#accel"><b>accel</b></a> ( int&nbsp;id ) const</li>
83<li class=fn>void <a href="#setAccel"><b>setAccel</b></a> ( const&nbsp;QKeySequence&nbsp;&amp;&nbsp;key, int&nbsp;id )</li>
84<li class=fn>QIconSet * <a href="#iconSet"><b>iconSet</b></a> ( int&nbsp;id ) const</li>
85<li class=fn>QString <a href="#text"><b>text</b></a> ( int&nbsp;id ) const</li>
86<li class=fn>QPixmap * <a href="#pixmap"><b>pixmap</b></a> ( int&nbsp;id ) const</li>
87<li class=fn>void <a href="#setWhatsThis"><b>setWhatsThis</b></a> ( int&nbsp;id, const&nbsp;QString&nbsp;&amp;&nbsp;text )</li>
88<li class=fn>QString <a href="#whatsThis"><b>whatsThis</b></a> ( int&nbsp;id ) const</li>
89<li class=fn>void <a href="#changeItem"><b>changeItem</b></a> ( int&nbsp;id, const&nbsp;QString&nbsp;&amp;&nbsp;text )</li>
90<li class=fn>void <a href="#changeItem-2"><b>changeItem</b></a> ( int&nbsp;id, const&nbsp;QPixmap&nbsp;&amp;&nbsp;pixmap )</li>
91<li class=fn>void <a href="#changeItem-3"><b>changeItem</b></a> ( int&nbsp;id, const&nbsp;QIconSet&nbsp;&amp;&nbsp;icon, const&nbsp;QString&nbsp;&amp;&nbsp;text )</li>
92<li class=fn>void <a href="#changeItem-4"><b>changeItem</b></a> ( int&nbsp;id, const&nbsp;QIconSet&nbsp;&amp;&nbsp;icon, const&nbsp;QPixmap&nbsp;&amp;&nbsp;pixmap )</li>
93<li class=fn>bool <a href="#isItemEnabled"><b>isItemEnabled</b></a> ( int&nbsp;id ) const</li>
94<li class=fn>void <a href="#setItemEnabled"><b>setItemEnabled</b></a> ( int&nbsp;id, bool&nbsp;enable )</li>
95<li class=fn>bool <a href="#isItemChecked"><b>isItemChecked</b></a> ( int&nbsp;id ) const</li>
96<li class=fn>void <a href="#setItemChecked"><b>setItemChecked</b></a> ( int&nbsp;id, bool&nbsp;check )</li>
97<li class=fn>bool <a href="#isItemVisible"><b>isItemVisible</b></a> ( int&nbsp;id ) const</li>
98<li class=fn>void <a href="#setItemVisible"><b>setItemVisible</b></a> ( int&nbsp;id, bool&nbsp;visible )</li>
99<li class=fn>bool <a href="#connectItem"><b>connectItem</b></a> ( int&nbsp;id, const&nbsp;QObject&nbsp;*&nbsp;receiver, const&nbsp;char&nbsp;*&nbsp;member )</li>
100<li class=fn>bool <a href="#disconnectItem"><b>disconnectItem</b></a> ( int&nbsp;id, const&nbsp;QObject&nbsp;*&nbsp;receiver, const&nbsp;char&nbsp;*&nbsp;member )</li>
101<li class=fn>bool <a href="#setItemParameter"><b>setItemParameter</b></a> ( int&nbsp;id, int&nbsp;param )</li>
102<li class=fn>int <a href="#itemParameter"><b>itemParameter</b></a> ( int&nbsp;id ) const</li>
103</ul>
104<h2>Properties</h2>
105<ul>
106<li class=fn>bool <a href="#checkable-prop"><b>checkable</b></a>&nbsp;- whether the display of check marks on menu items is enabled</li>
107</ul>
108<h2>Protected Members</h2>
109<ul>
110<li class=fn>int <a href="#itemHeight"><b>itemHeight</b></a> ( int&nbsp;row ) const</li>
111<li class=fn>int <a href="#itemHeight-2"><b>itemHeight</b></a> ( QMenuItem&nbsp;*&nbsp;mi ) const</li>
112<li class=fn>void <a href="#drawItem"><b>drawItem</b></a> ( QPainter&nbsp;*&nbsp;p, int&nbsp;tab_, QMenuItem&nbsp;*&nbsp;mi, bool&nbsp;act, int&nbsp;x, int&nbsp;y, int&nbsp;w, int&nbsp;h )</li>
113<li class=fn>virtual void <a href="#drawContents"><b>drawContents</b></a> ( QPainter&nbsp;*&nbsp;p )</li>
114<li class=fn>int <a href="#columns"><b>columns</b></a> () const</li>
115</ul>
116<hr><a name="details"></a><h2>Detailed Description</h2>
117
118
119The QPopupMenu class provides a popup menu widget.
120<p>
121
122
123<p> A popup menu widget is a selection menu. It can be either a
124pull-down menu in a menu bar or a standalone context (popup) menu.
125Pull-down menus are shown by the menu bar when the user clicks on
126the respective item or presses the specified shortcut key. Use
127<a href="qmenudata.html#insertItem">QMenuBar::insertItem</a>() to insert a popup menu into a menu bar.
128Show a context menu either asynchronously with <a href="#popup">popup</a>() or
129synchronously with <a href="#exec">exec</a>().
130<p> Technically, a popup menu consists of a list of menu items. You
131add items with <a href="qmenudata.html#insertItem">insertItem</a>(). An item is either a string, a pixmap
132or a custom item that provides its own drawing function (see
133<a href="qcustommenuitem.html">QCustomMenuItem</a>). In addition, items can have an optional icon
134drawn on the very left side and an accelerator key such as
135"Ctrl+X".
136<p> There are three kinds of menu items: separators, menu items that
137perform an action and menu items that show a submenu. Separators
138are inserted with <a href="qmenudata.html#insertSeparator">insertSeparator</a>(). For submenus, you pass a
139pointer to a QPopupMenu in your call to insertItem(). All other
140items are considered action items.
141<p> When inserting action items you usually specify a receiver and a
142slot. The receiver will be notifed whenever the item is selected.
143In addition, QPopupMenu provides two signals, <a href="#activated">activated</a>() and
144<a href="#highlighted">highlighted</a>(), which signal the identifier of the respective menu
145item. It is sometimes practical to connect several items to one
146slot. To distinguish between them, specify a slot that takes an
147integer argument and use <a href="qmenudata.html#setItemParameter">setItemParameter</a>() to associate a unique
148value with each item.
149<p> You clear a popup menu with <a href="qmenudata.html#clear">clear</a>() and remove single items with
150<a href="qmenudata.html#removeItem">removeItem</a>() or <a href="qmenudata.html#removeItemAt">removeItemAt</a>().
151<p> A popup menu can display check marks for certain items when
152enabled with <a href="#setCheckable">setCheckable</a>(TRUE). You check or uncheck items with
153<a href="qmenudata.html#setItemChecked">setItemChecked</a>().
154<p> Items are either enabled or disabled. You toggle their state with
155<a href="qmenudata.html#setItemEnabled">setItemEnabled</a>(). Just before a popup menu becomes visible, it
156emits the <a href="#aboutToShow">aboutToShow</a>() signal. You can use this signal to set the
157correct enabled/disabled states of all menu items before the user
158sees it. The corresponding <a href="#aboutToHide">aboutToHide</a>() signal is emitted when
159the menu hides again.
160<p> You can provide What's This? help for single menu items with
161<a href="qmenudata.html#setWhatsThis">setWhatsThis</a>(). See <a href="qwhatsthis.html">QWhatsThis</a> for general information about this
162kind of lightweight online help.
163<p> For ultimate flexibility, you can also add entire widgets as items
164into a popup menu (for example, a color selector).
165<p> A QPopupMenu can also provide a tear-off menu. A tear-off menu is
166a top-level window that contains a copy of the menu. This makes it
167possible for the user to "tear off" frequently used menus and
168position them in a convenient place on the screen. If you want
169that functionality for a certain menu, insert a tear-off handle
170with <a href="#insertTearOffHandle">insertTearOffHandle</a>(). When using tear-off menus, bear in
171mind that the concept isn't typically used on Microsoft Windows so
172users may not be familiar with it. Consider using a <a href="qtoolbar.html">QToolBar</a>
173instead. Tear-off menus cannot contain custom widgets; if the
174original menu contains a custom widget item, this item is omitted.
175<p> <a href="menu-example.html">menu/menu.cpp</a> is an example of
176<a href="qmenubar.html">QMenuBar</a> and QPopupMenu use.
177<p>
178<p> <img src=qpopmenu-m.png> <img src=qpopmenu-w.png>
179<p> <p>See also <a href="qmenubar.html">QMenuBar</a>, <a href="guibooks.html#fowler">GUI Design Handbook: Menu, Drop-Down and
180 Pop-Up</a>, <a href="application.html">Main Window and Related Classes</a>, and <a href="basic.html">Basic Widgets</a>.
181
182<hr><h2>Member Function Documentation</h2>
183<h3 class=fn><a name="QPopupMenu"></a>QPopupMenu::QPopupMenu ( <a href="qwidget.html">QWidget</a>&nbsp;*&nbsp;parent = 0, const&nbsp;char&nbsp;*&nbsp;name = 0 )
184</h3>
185Constructs a popup menu called <em>name</em> with parent <em>parent</em>.
186<p> Although a popup menu is always a top-level widget, if a parent is
187passed the popup menu will be deleted when that parent is
188destroyed (as with any other <a href="qobject.html">QObject</a>).
189
190<h3 class=fn><a name="~QPopupMenu"></a>QPopupMenu::~QPopupMenu ()
191</h3>
192Destroys the popup menu.
193
194<h3 class=fn>void <a name="aboutToHide"></a>QPopupMenu::aboutToHide ()<tt> [signal]</tt>
195</h3>
196
197<p> This signal is emitted just before the popup menu is hidden after
198it has been displayed.
199<p> <b>Warning:</b> Do not open a widget in a slot connected to this signal.
200<p> <p>See also <a href="#aboutToShow">aboutToShow</a>(), <a href="qmenudata.html#setItemEnabled">setItemEnabled</a>(), <a href="qmenudata.html#setItemChecked">setItemChecked</a>(), <a href="qmenudata.html#insertItem">insertItem</a>(), and <a href="qmenudata.html#removeItem">removeItem</a>().
201
202<h3 class=fn>void <a name="aboutToShow"></a>QPopupMenu::aboutToShow ()<tt> [signal]</tt>
203</h3>
204
205<p> This signal is emitted just before the popup menu is displayed.
206You can connect it to any slot that sets up the menu contents
207(e.g. to ensure that the right items are enabled).
208<p> <p>See also <a href="#aboutToHide">aboutToHide</a>(), <a href="qmenudata.html#setItemEnabled">setItemEnabled</a>(), <a href="qmenudata.html#setItemChecked">setItemChecked</a>(), <a href="qmenudata.html#insertItem">insertItem</a>(), and <a href="qmenudata.html#removeItem">removeItem</a>().
209
210<p>Example: <a href="mdi-example.html#x2048">mdi/application.cpp</a>.
211<h3 class=fn><a href="qkeysequence.html">QKeySequence</a> <a name="accel"></a>QMenuData::accel ( int&nbsp;id ) const
212</h3>
213Returns the accelerator key that has been defined for the menu
214item <em>id</em>, or 0 if it has no accelerator key or if there is no
215such menu item.
216<p> <p>See also <a href="qmenudata.html#setAccel">setAccel</a>(), <a href="qaccel.html">QAccel</a>, and <a href="qnamespace-h.html">qnamespace.h</a>.
217
218<h3 class=fn>void <a name="activated"></a>QPopupMenu::activated ( int&nbsp;id )<tt> [signal]</tt>
219</h3>
220
221<p> This signal is emitted when a menu item is selected; <em>id</em> is the
222id of the selected item.
223<p> Normally, you connect each menu item to a single slot using
224<a href="qmenudata.html#insertItem">QMenuData::insertItem</a>(), but sometimes you will want to connect
225several items to a single slot (most often if the user selects
226from an array). This signal is useful in such cases.
227<p> <p>See also <a href="#highlighted">highlighted</a>() and <a href="qmenudata.html#insertItem">QMenuData::insertItem</a>().
228
229<p>Examples: <a href="grapher-nsplugin-example.html#x2767">grapher/grapher.cpp</a>, <a href="helpviewer-example.html#x1004">helpviewer/helpwindow.cpp</a>, <a href="qdir-example.html#x1835">qdir/qdir.cpp</a>, <a href="qwerty-example.html#x386">qwerty/qwerty.cpp</a>, <a href="scrollview-example.html#x642">scrollview/scrollview.cpp</a>, and <a href="showimg-example.html#x1341">showimg/showimg.cpp</a>.
230<h3 class=fn>void <a name="changeItem"></a>QMenuData::changeItem ( int&nbsp;id, const&nbsp;<a href="qstring.html">QString</a>&nbsp;&amp;&nbsp;text )
231</h3>
232Changes the text of the menu item <em>id</em> to <em>text</em>. If the item
233has an icon, the icon remains unchanged.
234<p> <p>See also <a href="qmenudata.html#text">text</a>().
235
236<h3 class=fn>void <a name="changeItem-2"></a>QMenuData::changeItem ( int&nbsp;id, const&nbsp;<a href="qpixmap.html">QPixmap</a>&nbsp;&amp;&nbsp;pixmap )
237</h3>
238This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
239<p> Changes the pixmap of the menu item <em>id</em> to the pixmap <em>pixmap</em>.
240If the item has an icon, the icon is unchanged.
241<p> <p>See also <a href="qmenudata.html#pixmap">pixmap</a>().
242
243<h3 class=fn>void <a name="changeItem-3"></a>QMenuData::changeItem ( int&nbsp;id, const&nbsp;<a href="qiconset.html">QIconSet</a>&nbsp;&amp;&nbsp;icon, const&nbsp;<a href="qstring.html">QString</a>&nbsp;&amp;&nbsp;text )
244</h3>
245This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
246<p> Changes the iconset and text of the menu item <em>id</em> to the <em>icon</em>
247and <em>text</em> respectively.
248<p> <p>See also <a href="qmenudata.html#pixmap">pixmap</a>().
249
250<h3 class=fn>void <a name="changeItem-4"></a>QMenuData::changeItem ( int&nbsp;id, const&nbsp;<a href="qiconset.html">QIconSet</a>&nbsp;&amp;&nbsp;icon, const&nbsp;<a href="qpixmap.html">QPixmap</a>&nbsp;&amp;&nbsp;pixmap )
251</h3>
252This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
253<p> Changes the iconset and pixmap of the menu item <em>id</em> to <em>icon</em>
254and <em>pixmap</em> respectively.
255<p> <p>See also <a href="qmenudata.html#pixmap">pixmap</a>().
256
257<h3 class=fn>void <a name="clear"></a>QMenuData::clear ()
258</h3>
259Removes all menu items.
260<p> <p>See also <a href="qmenudata.html#removeItem">removeItem</a>() and <a href="qmenudata.html#removeItemAt">removeItemAt</a>().
261
262<p>Examples: <a href="mdi-example.html#x2029">mdi/application.cpp</a> and <a href="qwerty-example.html#x370">qwerty/qwerty.cpp</a>.
263<h3 class=fn>int <a name="columns"></a>QPopupMenu::columns () const<tt> [protected]</tt>
264</h3>
265If a popup menu does not fit on the screen it lays itself out so
266that it does fit. It is style dependent what layout means (for
267example, on Windows it will use multiple columns).
268<p> This functions returns the number of columns necessary.
269<p> <p>See also <a href="qwidget.html#sizeHint-prop">sizeHint</a>.
270
271<h3 class=fn>bool <a name="connectItem"></a>QMenuData::connectItem ( int&nbsp;id, const&nbsp;<a href="qobject.html">QObject</a>&nbsp;*&nbsp;receiver, const&nbsp;char&nbsp;*&nbsp;member )
272</h3>
273Connects the menu item with identifier <em>id</em> to <em>receiver</em>'s <em>member</em> slot or signal.
274<p> The receiver's slot (or signal) is activated when the menu item is
275activated.
276<p> <p>See also <a href="qmenudata.html#disconnectItem">disconnectItem</a>() and <a href="qmenudata.html#setItemParameter">setItemParameter</a>().
277
278<p>Example: <a href="menu-example.html#x1868">menu/menu.cpp</a>.
279<h3 class=fn>bool <a name="disconnectItem"></a>QMenuData::disconnectItem ( int&nbsp;id, const&nbsp;<a href="qobject.html">QObject</a>&nbsp;*&nbsp;receiver, const&nbsp;char&nbsp;*&nbsp;member )
280</h3>
281Disconnects the <em>receiver</em>'s <em>member</em> from the menu item with
282identifier <em>id</em>.
283<p> All connections are removed when the menu data object is
284destroyed.
285<p> <p>See also <a href="qmenudata.html#connectItem">connectItem</a>() and <a href="qmenudata.html#setItemParameter">setItemParameter</a>().
286
287<h3 class=fn>void <a name="drawContents"></a>QPopupMenu::drawContents ( <a href="qpainter.html">QPainter</a>&nbsp;*&nbsp;p )<tt> [virtual protected]</tt>
288</h3>
289Draws all menu items using painter <em>p</em>.
290
291<p>Reimplemented from <a href="qframe.html#drawContents">QFrame</a>.
292<h3 class=fn>void <a name="drawItem"></a>QPopupMenu::drawItem ( <a href="qpainter.html">QPainter</a>&nbsp;*&nbsp;p, int&nbsp;tab_, QMenuItem&nbsp;*&nbsp;mi, bool&nbsp;act, int&nbsp;x, int&nbsp;y, int&nbsp;w, int&nbsp;h )<tt> [protected]</tt>
293</h3>
294Draws menu item <em>mi</em> in the area <em>x</em>, <em>y</em>, <em>w</em>, <em>h</em>, using
295painter <em>p</em>. The item is drawn active if <em>act</em> is TRUE or drawn
296inactive if <em>act</em> is FALSE. The rightmost <em>tab_</em> pixels are used
297for accelerator text.
298<p> <p>See also <a href="qstyle.html#drawControl">QStyle::drawControl</a>().
299
300<h3 class=fn>int <a name="exec"></a>QPopupMenu::exec ()
301</h3>
302Executes this popup synchronously.
303<p> This is equivalent to <tt>exec(mapToGlobal(QPoint(0,0)))</tt>. In most
304situations you'll want to specify the position yourself, for
305example at the current mouse position:
306<pre>
307 <a href="#exec">exec</a>(QCursor::<a href="qcursor.html#pos">pos</a>());
308 </pre>
309
310or aligned to a widget:
311<pre>
312 <a href="#exec">exec</a>(somewidget.mapToGlobal(QPoint(0,0)));
313 </pre>
314
315
316<p>Examples: <a href="fileiconview-example.html#x866">fileiconview/qfileiconview.cpp</a>, <a href="menu-example.html#x1878">menu/menu.cpp</a>, and <a href="scribble-example.html#x923">scribble/scribble.cpp</a>.
317<h3 class=fn>int <a name="exec-2"></a>QPopupMenu::exec ( const&nbsp;<a href="qpoint.html">QPoint</a>&nbsp;&amp;&nbsp;pos, int&nbsp;indexAtPoint = 0 )
318</h3>
319This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
320<p> Executes this popup synchronously.
321<p> Opens the popup menu so that the item number <em>indexAtPoint</em> will
322be at the specified <em>global</em> position <em>pos</em>. To translate a
323widget's local coordinates into global coordinates, use
324<a href="qwidget.html#mapToGlobal">QWidget::mapToGlobal</a>().
325<p> The return code is the id of the selected item in either the popup
326menu or one of its submenus, or -1 if no item is selected
327(normally because the user pressed Esc).
328<p> Note that all signals are emitted as usual. If you connect a menu
329item to a slot and call the menu's <a href="#exec">exec</a>(), you get the result both
330via the signal-slot connection and in the return value of exec().
331<p> Common usage is to position the popup at the current mouse
332position:
333<pre>
334 <a href="#exec">exec</a>( QCursor::<a href="qcursor.html#pos">pos</a>() );
335 </pre>
336
337or aligned to a widget:
338<pre>
339 <a href="#exec">exec</a>( somewidget.mapToGlobal(QPoint(0, 0)) );
340 </pre>
341
342<p> When positioning a popup with exec() or <a href="#popup">popup</a>(), bear in mind that
343you cannot rely on the popup menu's current <a href="qwidget.html#size">size</a>(). For
344performance reasons, the popup adapts its size only when
345necessary. So in many cases, the size before and after the show is
346different. Instead, use <a href="qwidget.html#sizeHint">sizeHint</a>(). It calculates the proper size
347depending on the menu's current contents.
348<p> <p>See also <a href="#popup">popup</a>() and <a href="qwidget.html#sizeHint-prop">sizeHint</a>.
349
350<h3 class=fn>void <a name="highlighted"></a>QPopupMenu::highlighted ( int&nbsp;id )<tt> [signal]</tt>
351</h3>
352
353<p> This signal is emitted when a menu item is highlighted; <em>id</em> is
354the id of the highlighted item.
355<p> <p>See also <a href="#activated">activated</a>() and <a href="qmenudata.html#insertItem">QMenuData::insertItem</a>().
356
357<h3 class=fn><a href="qiconset.html">QIconSet</a>&nbsp;* <a name="iconSet"></a>QMenuData::iconSet ( int&nbsp;id ) const
358</h3>
359Returns the icon set that has been set for menu item <em>id</em>, or 0
360if no icon set has been set.
361<p> <p>See also <a href="qmenudata.html#changeItem">changeItem</a>(), <a href="qmenudata.html#text">text</a>(), and <a href="qmenudata.html#pixmap">pixmap</a>().
362
363<h3 class=fn>int <a name="idAt"></a>QPopupMenu::idAt ( int&nbsp;index ) const
364</h3>
365
366<p> Returns the identifier of the menu item at position <em>index</em> in
367the internal list, or -1 if <em>index</em> is out of range.
368<p> <p>See also <a href="qmenudata.html#setId">QMenuData::setId</a>() and <a href="qmenudata.html#indexOf">QMenuData::indexOf</a>().
369
370<p>Example: <a href="scrollview-example.html#x643">scrollview/scrollview.cpp</a>.
371<h3 class=fn>int <a name="idAt-2"></a>QPopupMenu::idAt ( const&nbsp;<a href="qpoint.html">QPoint</a>&nbsp;&amp;&nbsp;pos ) const
372</h3>
373This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
374<p> Returns the id of the item at <em>pos</em>, or -1 if there is no item
375there or if it is a separator.
376
377<h3 class=fn>int <a name="insertItem"></a>QMenuData::insertItem ( const&nbsp;<a href="qstring.html">QString</a>&nbsp;&amp;&nbsp;text, const&nbsp;<a href="qobject.html">QObject</a>&nbsp;*&nbsp;receiver, const&nbsp;char&nbsp;*&nbsp;member, const&nbsp;<a href="qkeysequence.html">QKeySequence</a>&nbsp;&amp;&nbsp;accel = 0, int&nbsp;id = -1, int&nbsp;index = -1 )
378</h3>
379The family of <a href="qmenudata.html#insertItem">insertItem</a>() functions inserts menu items into a
380popup menu or a menu bar.
381<p> A menu item is usually either a text string or a pixmap, both with
382an optional icon or keyboard accelerator. For special cases it is
383also possible to insert custom items (see <a href="qcustommenuitem.html">QCustomMenuItem</a>) or
384even widgets into popup menus.
385<p> Some insertItem() members take a popup menu as an additional
386argument. Use this to insert submenus into existing menus or
387pulldown menus into a menu bar.
388<p> The number of insert functions may look confusing, but they are
389actually quite simple to use.
390<p> This default version inserts a menu item with the text <em>text</em>,
391the accelerator key <em>accel</em>, an id and an optional index and
392connects it to the slot <em>member</em> in the object <em>receiver</em>.
393<p> Example:
394<pre>
395 <a href="qmenubar.html">QMenuBar</a> *mainMenu = new <a href="qmenubar.html">QMenuBar</a>;
396 QPopupMenu *fileMenu = new QPopupMenu;
397 fileMenu-&gt;<a href="qmenudata.html#insertItem">insertItem</a>( "New", myView, SLOT(newFile()), CTRL+Key_N );
398 fileMenu-&gt;<a href="qmenudata.html#insertItem">insertItem</a>( "Open", myView, SLOT(open()), CTRL+Key_O );
399 mainMenu-&gt;<a href="qmenudata.html#insertItem">insertItem</a>( "File", fileMenu );
400 </pre>
401
402<p> Not all insert functions take an object/slot parameter or an
403accelerator key. Use <a href="qmenudata.html#connectItem">connectItem</a>() and <a href="qmenudata.html#setAccel">setAccel</a>() on those items.
404<p> If you need to translate accelerators, use <a href="qobject.html#tr">tr</a>() with the text and
405accelerator. (For translations use a string <a href="qkeysequence.html">key
406 sequence</a>.):
407<pre>
408 fileMenu-&gt;insertItem( <a href="qobject.html#tr">tr</a>("Open"), myView, SLOT(open()),
409 <a href="qobject.html#tr">tr</a>("Ctrl+O") );
410 </pre>
411
412<p> In the example above, pressing Ctrl+O or selecting "Open" from the
413menu activates the myView->open() function.
414<p> Some insert functions take a <a href="qiconset.html">QIconSet</a> parameter to specify the
415little menu item icon. Note that you can always pass a <a href="qpixmap.html">QPixmap</a>
416object instead.
417<p> The <em>id</em> specifies the identification number associated with the
418menu item. Note that only positive values are valid, as a negative
419value will make Qt select a unique id for the item.
420<p> The <em>index</em> specifies the position in the menu. The menu item is
421appended at the end of the list if <em>index</em> is negative.
422<p> Note that keyboard accelerators in Qt are not application-global,
423instead they are bound to a certain top-level window. For example,
424accelerators in QPopupMenu items only work for menus that are
425associated with a certain window. This is true for popup menus
426that live in a menu bar since their accelerators will then be
427installed in the menu bar itself. This also applies to stand-alone
428popup menus that have a top-level widget in their <a href="qwidget.html#parentWidget">parentWidget</a>()
429chain. The menu will then install its accelerator object on that
430top-level widget. For all other cases use an independent <a href="qaccel.html">QAccel</a>
431object.
432<p> <b>Warning:</b> Be careful when passing a literal 0 to <a href="qmenudata.html#insertItem">insertItem</a>()
433because some C++ compilers choose the wrong overloaded function.
434Cast the 0 to what you mean, e.g. <tt>(QObject*)0</tt>.
435<p> <b>Warning:</b> On Mac OS X, items that connect to a slot that are inserted into a
436menubar will not function as we use the native menubar that knows nothing
437about signals or slots. Instead insert the items into a popup menu and
438insert the popup menu into the menubar. This may be fixed in a future Qt
439version.
440<p> Returns the allocated <a href="qmenudata.html#menu-identifier">menu identifier</a> number (<em>id</em> if <em>id</em> >= 0).
441<p> <p>See also <a href="qmenudata.html#removeItem">removeItem</a>(), <a href="qmenudata.html#changeItem">changeItem</a>(), <a href="qmenudata.html#setAccel">setAccel</a>(), <a href="qmenudata.html#connectItem">connectItem</a>(), <a href="qaccel.html">QAccel</a>, and <a href="qnamespace-h.html">qnamespace.h</a>.
442
443<p>Examples: <a href="addressbook-example.html#x569">addressbook/mainwindow.cpp</a>, <a href="canvas-example.html#x2936">canvas/canvas.cpp</a>, <a href="menu-example.html#x1869">menu/menu.cpp</a>, <a href="qwerty-example.html#x371">qwerty/qwerty.cpp</a>, <a href="scrollview-example.html#x634">scrollview/scrollview.cpp</a>, <a href="showimg-example.html#x1327">showimg/showimg.cpp</a>, and <a href="sound-example.html#x2810">sound/sound.cpp</a>.
444<h3 class=fn>int <a name="insertItem-2"></a>QMenuData::insertItem ( const&nbsp;<a href="qiconset.html">QIconSet</a>&nbsp;&amp;&nbsp;icon, const&nbsp;<a href="qstring.html">QString</a>&nbsp;&amp;&nbsp;text, const&nbsp;<a href="qobject.html">QObject</a>&nbsp;*&nbsp;receiver, const&nbsp;char&nbsp;*&nbsp;member, const&nbsp;<a href="qkeysequence.html">QKeySequence</a>&nbsp;&amp;&nbsp;accel = 0, int&nbsp;id = -1, int&nbsp;index = -1 )
445</h3>
446This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
447<p> Inserts a menu item with icon <em>icon</em>, text <em>text</em>, accelerator
448<em>accel</em>, optional id <em>id</em>, and optional <em>index</em> position. The
449menu item is connected it to the <em>receiver</em>'s <em>member</em> slot. The
450icon will be displayed to the left of the text in the item.
451<p> Returns the allocated <a href="qmenudata.html#menu-identifier">menu identifier</a> number (<em>id</em> if <em>id</em> >= 0).
452<p> <p>See also <a href="qmenudata.html#removeItem">removeItem</a>(), <a href="qmenudata.html#changeItem">changeItem</a>(), <a href="qmenudata.html#setAccel">setAccel</a>(), <a href="qmenudata.html#connectItem">connectItem</a>(), <a href="qaccel.html">QAccel</a>, and <a href="qnamespace-h.html">qnamespace.h</a>.
453
454<h3 class=fn>int <a name="insertItem-3"></a>QMenuData::insertItem ( const&nbsp;<a href="qpixmap.html">QPixmap</a>&nbsp;&amp;&nbsp;pixmap, const&nbsp;<a href="qobject.html">QObject</a>&nbsp;*&nbsp;receiver, const&nbsp;char&nbsp;*&nbsp;member, const&nbsp;<a href="qkeysequence.html">QKeySequence</a>&nbsp;&amp;&nbsp;accel = 0, int&nbsp;id = -1, int&nbsp;index = -1 )
455</h3>
456This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
457<p> Inserts a menu item with pixmap <em>pixmap</em>, accelerator <em>accel</em>,
458optional id <em>id</em>, and optional <em>index</em> position. The menu item
459is connected it to the <em>receiver</em>'s <em>member</em> slot. The icon will
460be displayed to the left of the text in the item.
461<p> To look best when being highlighted as a menu item, the pixmap
462should provide a mask (see <a href="qpixmap.html#mask">QPixmap::mask</a>()).
463<p> Returns the allocated <a href="qmenudata.html#menu-identifier">menu identifier</a> number (<em>id</em> if <em>id</em> >= 0).
464<p> <p>See also <a href="qmenudata.html#removeItem">removeItem</a>(), <a href="qmenudata.html#changeItem">changeItem</a>(), <a href="qmenudata.html#setAccel">setAccel</a>(), and <a href="qmenudata.html#connectItem">connectItem</a>().
465
466<h3 class=fn>int <a name="insertItem-4"></a>QMenuData::insertItem ( const&nbsp;<a href="qiconset.html">QIconSet</a>&nbsp;&amp;&nbsp;icon, const&nbsp;<a href="qpixmap.html">QPixmap</a>&nbsp;&amp;&nbsp;pixmap, const&nbsp;<a href="qobject.html">QObject</a>&nbsp;*&nbsp;receiver, const&nbsp;char&nbsp;*&nbsp;member, const&nbsp;<a href="qkeysequence.html">QKeySequence</a>&nbsp;&amp;&nbsp;accel = 0, int&nbsp;id = -1, int&nbsp;index = -1 )
467</h3>
468This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
469<p> Inserts a menu item with icon <em>icon</em>, pixmap <em>pixmap</em>,
470accelerator <em>accel</em>, optional id <em>id</em>, and optional <em>index</em>
471position. The icon will be displayed to the left of the pixmap in
472the item. The item is connected to the <em>member</em> slot in the <em>receiver</em> object.
473<p> To look best when being highlighted as a menu item, the pixmap
474should provide a mask (see <a href="qpixmap.html#mask">QPixmap::mask</a>()).
475<p> Returns the allocated <a href="qmenudata.html#menu-identifier">menu identifier</a> number (<em>id</em> if <em>id</em> >= 0).
476<p> <p>See also <a href="qmenudata.html#removeItem">removeItem</a>(), <a href="qmenudata.html#changeItem">changeItem</a>(), <a href="qmenudata.html#setAccel">setAccel</a>(), <a href="qmenudata.html#connectItem">connectItem</a>(), <a href="qaccel.html">QAccel</a>, and <a href="qnamespace-h.html">qnamespace.h</a>.
477
478<h3 class=fn>int <a name="insertItem-5"></a>QMenuData::insertItem ( const&nbsp;<a href="qstring.html">QString</a>&nbsp;&amp;&nbsp;text, int&nbsp;id = -1, int&nbsp;index = -1 )
479</h3>
480This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
481<p> Inserts a menu item with text <em>text</em>, optional id <em>id</em>, and
482optional <em>index</em> position.
483<p> Returns the allocated <a href="qmenudata.html#menu-identifier">menu identifier</a> number (<em>id</em> if <em>id</em> >= 0).
484<p> <p>See also <a href="qmenudata.html#removeItem">removeItem</a>(), <a href="qmenudata.html#changeItem">changeItem</a>(), <a href="qmenudata.html#setAccel">setAccel</a>(), and <a href="qmenudata.html#connectItem">connectItem</a>().
485
486<h3 class=fn>int <a name="insertItem-6"></a>QMenuData::insertItem ( const&nbsp;<a href="qiconset.html">QIconSet</a>&nbsp;&amp;&nbsp;icon, const&nbsp;<a href="qstring.html">QString</a>&nbsp;&amp;&nbsp;text, int&nbsp;id = -1, int&nbsp;index = -1 )
487</h3>
488This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
489<p> Inserts a menu item with icon <em>icon</em>, text <em>text</em>, optional id
490<em>id</em>, and optional <em>index</em> position. The icon will be displayed
491to the left of the text in the item.
492<p> Returns the allocated <a href="qmenudata.html#menu-identifier">menu identifier</a> number (<em>id</em> if <em>id</em> >= 0).
493<p> <p>See also <a href="qmenudata.html#removeItem">removeItem</a>(), <a href="qmenudata.html#changeItem">changeItem</a>(), <a href="qmenudata.html#setAccel">setAccel</a>(), and <a href="qmenudata.html#connectItem">connectItem</a>().
494
495<h3 class=fn>int <a name="insertItem-7"></a>QMenuData::insertItem ( const&nbsp;<a href="qstring.html">QString</a>&nbsp;&amp;&nbsp;text, <a href="qpopupmenu.html">QPopupMenu</a>&nbsp;*&nbsp;popup, int&nbsp;id = -1, int&nbsp;index = -1 )
496</h3>
497This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
498<p> Inserts a menu item with text <em>text</em>, submenu <em>popup</em>, optional
499id <em>id</em>, and optional <em>index</em> position.
500<p> The <em>popup</em> must be deleted by the programmer or by its parent
501widget. It is not deleted when this menu item is removed or when
502the menu is deleted.
503<p> Returns the allocated <a href="qmenudata.html#menu-identifier">menu identifier</a> number (<em>id</em> if <em>id</em> >= 0).
504<p> <p>See also <a href="qmenudata.html#removeItem">removeItem</a>(), <a href="qmenudata.html#changeItem">changeItem</a>(), <a href="qmenudata.html#setAccel">setAccel</a>(), and <a href="qmenudata.html#connectItem">connectItem</a>().
505
506<h3 class=fn>int <a name="insertItem-8"></a>QMenuData::insertItem ( const&nbsp;<a href="qiconset.html">QIconSet</a>&nbsp;&amp;&nbsp;icon, const&nbsp;<a href="qstring.html">QString</a>&nbsp;&amp;&nbsp;text, <a href="qpopupmenu.html">QPopupMenu</a>&nbsp;*&nbsp;popup, int&nbsp;id = -1, int&nbsp;index = -1 )
507</h3>
508This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
509<p> Inserts a menu item with icon <em>icon</em>, text <em>text</em>, submenu <em>popup</em>, optional id <em>id</em>, and optional <em>index</em> position. The icon
510will be displayed to the left of the text in the item.
511<p> The <em>popup</em> must be deleted by the programmer or by its parent
512widget. It is not deleted when this menu item is removed or when
513the menu is deleted.
514<p> Returns the allocated <a href="qmenudata.html#menu-identifier">menu identifier</a> number (<em>id</em> if <em>id</em> >= 0).
515<p> <p>See also <a href="qmenudata.html#removeItem">removeItem</a>(), <a href="qmenudata.html#changeItem">changeItem</a>(), <a href="qmenudata.html#setAccel">setAccel</a>(), and <a href="qmenudata.html#connectItem">connectItem</a>().
516
517<h3 class=fn>int <a name="insertItem-9"></a>QMenuData::insertItem ( const&nbsp;<a href="qpixmap.html">QPixmap</a>&nbsp;&amp;&nbsp;pixmap, int&nbsp;id = -1, int&nbsp;index = -1 )
518</h3>
519This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
520<p> Inserts a menu item with pixmap <em>pixmap</em>, optional id <em>id</em>, and
521optional <em>index</em> position.
522<p> To look best when being highlighted as a menu item, the pixmap
523should provide a mask (see <a href="qpixmap.html#mask">QPixmap::mask</a>()).
524<p> Returns the allocated <a href="qmenudata.html#menu-identifier">menu identifier</a> number (<em>id</em> if <em>id</em> >= 0).
525<p> <p>See also <a href="qmenudata.html#removeItem">removeItem</a>(), <a href="qmenudata.html#changeItem">changeItem</a>(), <a href="qmenudata.html#setAccel">setAccel</a>(), and <a href="qmenudata.html#connectItem">connectItem</a>().
526
527<h3 class=fn>int <a name="insertItem-a"></a>QMenuData::insertItem ( const&nbsp;<a href="qiconset.html">QIconSet</a>&nbsp;&amp;&nbsp;icon, const&nbsp;<a href="qpixmap.html">QPixmap</a>&nbsp;&amp;&nbsp;pixmap, int&nbsp;id = -1, int&nbsp;index = -1 )
528</h3>
529This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
530<p> Inserts a menu item with icon <em>icon</em>, pixmap <em>pixmap</em>, optional
531id <em>id</em>, and optional <em>index</em> position. The icon will be
532displayed to the left of the pixmap in the item.
533<p> Returns the allocated <a href="qmenudata.html#menu-identifier">menu identifier</a> number (<em>id</em> if <em>id</em> >= 0).
534<p> <p>See also <a href="qmenudata.html#removeItem">removeItem</a>(), <a href="qmenudata.html#changeItem">changeItem</a>(), <a href="qmenudata.html#setAccel">setAccel</a>(), and <a href="qmenudata.html#connectItem">connectItem</a>().
535
536<h3 class=fn>int <a name="insertItem-b"></a>QMenuData::insertItem ( const&nbsp;<a href="qpixmap.html">QPixmap</a>&nbsp;&amp;&nbsp;pixmap, <a href="qpopupmenu.html">QPopupMenu</a>&nbsp;*&nbsp;popup, int&nbsp;id = -1, int&nbsp;index = -1 )
537</h3>
538This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
539<p> Inserts a menu item with pixmap <em>pixmap</em>, submenu <em>popup</em>,
540optional id <em>id</em>, and optional <em>index</em> position.
541<p> The <em>popup</em> must be deleted by the programmer or by its parent
542widget. It is not deleted when this menu item is removed or when
543the menu is deleted.
544<p> Returns the allocated <a href="qmenudata.html#menu-identifier">menu identifier</a> number (<em>id</em> if <em>id</em> >= 0).
545<p> <p>See also <a href="qmenudata.html#removeItem">removeItem</a>(), <a href="qmenudata.html#changeItem">changeItem</a>(), <a href="qmenudata.html#setAccel">setAccel</a>(), and <a href="qmenudata.html#connectItem">connectItem</a>().
546
547<h3 class=fn>int <a name="insertItem-c"></a>QMenuData::insertItem ( const&nbsp;<a href="qiconset.html">QIconSet</a>&nbsp;&amp;&nbsp;icon, const&nbsp;<a href="qpixmap.html">QPixmap</a>&nbsp;&amp;&nbsp;pixmap, <a href="qpopupmenu.html">QPopupMenu</a>&nbsp;*&nbsp;popup, int&nbsp;id = -1, int&nbsp;index = -1 )
548</h3>
549This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
550<p> Inserts a menu item with icon <em>icon</em>, pixmap <em>pixmap</em> submenu <em>popup</em>, optional id <em>id</em>, and optional <em>index</em> position. The icon
551will be displayed to the left of the pixmap in the item.
552<p> The <em>popup</em> must be deleted by the programmer or by its parent
553widget. It is not deleted when this menu item is removed or when
554the menu is deleted.
555<p> Returns the allocated <a href="qmenudata.html#menu-identifier">menu identifier</a> number (<em>id</em> if <em>id</em> >= 0).
556<p> <p>See also <a href="qmenudata.html#removeItem">removeItem</a>(), <a href="qmenudata.html#changeItem">changeItem</a>(), <a href="qmenudata.html#setAccel">setAccel</a>(), and <a href="qmenudata.html#connectItem">connectItem</a>().
557
558<h3 class=fn>int <a name="insertItem-d"></a>QMenuData::insertItem ( <a href="qwidget.html">QWidget</a>&nbsp;*&nbsp;widget, int&nbsp;id = -1, int&nbsp;index = -1 )
559</h3>
560This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
561<p> Inserts a menu item that consists of the widget <em>widget</em> with
562optional id <em>id</em>, and optional <em>index</em> position.
563<p> Ownership of <em>widget</em> is transferred to the popup menu or to the
564menu bar.
565<p> Theoretically, any widget can be inserted into a popup menu. In
566practice, this only makes sense with certain widgets.
567<p> If a widget is not focus-enabled (see
568<a href="qwidget.html#isFocusEnabled">QWidget::isFocusEnabled</a>()), the menu treats it as a separator;
569this means that the item is not selectable and will never get
570focus. In this way you can, for example, simply insert a <a href="qlabel.html">QLabel</a> if
571you need a popup menu with a title.
572<p> If the widget is focus-enabled it will get focus when the user
573traverses the popup menu with the arrow keys. If the widget does
574not accept <tt>ArrowUp</tt> and <tt>ArrowDown</tt> in its key event handler,
575the focus will move back to the menu when the respective arrow key
576is hit one more time. This works with a <a href="qlineedit.html">QLineEdit</a>, for example. If
577the widget accepts the arrow key itself, it must also provide the
578possibility to put the focus back on the menu again by calling
579<a href="qwidget.html#focusNextPrevChild">QWidget::focusNextPrevChild</a>(). Futhermore, if the embedded widget
580closes the menu when the user made a selection, this can be done
581safely by calling:
582<pre>
583 if ( <a href="qwidget.html#isVisible">isVisible</a>() &amp;&amp;
584 <a href="qwidget.html#parentWidget">parentWidget</a>() &amp;&amp;
585 <a href="qwidget.html#parentWidget">parentWidget</a>()-&gt;inherits("QPopupMenu") )
586 <a href="qwidget.html#parentWidget">parentWidget</a>()-&gt;close();
587 </pre>
588
589<p> Returns the allocated <a href="qmenudata.html#menu-identifier">menu identifier</a> number (<em>id</em> if <em>id</em> >= 0).
590<p> <p>See also <a href="qmenudata.html#removeItem">removeItem</a>().
591
592<h3 class=fn>int <a name="insertItem-e"></a>QMenuData::insertItem ( const&nbsp;<a href="qiconset.html">QIconSet</a>&nbsp;&amp;&nbsp;icon, <a href="qcustommenuitem.html">QCustomMenuItem</a>&nbsp;*&nbsp;custom, int&nbsp;id = -1, int&nbsp;index = -1 )
593</h3>
594This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
595<p> Inserts a custom menu item <em>custom</em> with an <em>icon</em> and with
596optional id <em>id</em>, and optional <em>index</em> position.
597<p> This only works with popup menus. It is not supported for menu
598bars. Ownership of <em>custom</em> is transferred to the popup menu.
599<p> If you want to connect a custom item to a slot, use <a href="qmenudata.html#connectItem">connectItem</a>().
600<p> Returns the allocated <a href="qmenudata.html#menu-identifier">menu identifier</a> number (<em>id</em> if <em>id</em> >= 0).
601<p> <p>See also <a href="qmenudata.html#connectItem">connectItem</a>(), <a href="qmenudata.html#removeItem">removeItem</a>(), and <a href="qcustommenuitem.html">QCustomMenuItem</a>.
602
603<h3 class=fn>int <a name="insertItem-f"></a>QMenuData::insertItem ( <a href="qcustommenuitem.html">QCustomMenuItem</a>&nbsp;*&nbsp;custom, int&nbsp;id = -1, int&nbsp;index = -1 )
604</h3>
605This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
606<p> Inserts a custom menu item <em>custom</em> with optional id <em>id</em>, and
607optional <em>index</em> position.
608<p> This only works with popup menus. It is not supported for menu
609bars. Ownership of <em>custom</em> is transferred to the popup menu.
610<p> If you want to connect a custom item to a slot, use <a href="qmenudata.html#connectItem">connectItem</a>().
611<p> Returns the allocated <a href="qmenudata.html#menu-identifier">menu identifier</a> number (<em>id</em> if <em>id</em> >= 0).
612<p> <p>See also <a href="qmenudata.html#connectItem">connectItem</a>(), <a href="qmenudata.html#removeItem">removeItem</a>(), and <a href="qcustommenuitem.html">QCustomMenuItem</a>.
613
614<h3 class=fn>int <a name="insertSeparator"></a>QMenuData::insertSeparator ( int&nbsp;index = -1 )
615</h3>
616Inserts a separator at position <em>index</em>, and returns the <a href="qmenudata.html#menu-identifier">menu identifier</a>
617number allocated to it. The separator becomes the last menu item if
618<em>index</em> is negative.
619<p> In a popup menu a separator is rendered as a horizontal line. In a
620<a href="motif-extension.html#Motif">Motif</a> menu bar a separator is spacing, so the rest of the items
621(normally just "Help") are drawn right-justified. In a Windows
622menu bar separators are ignored (to comply with the Windows style
623guidelines).
624
625<p>Examples: <a href="addressbook-example.html#x570">addressbook/mainwindow.cpp</a>, <a href="menu-example.html#x1870">menu/menu.cpp</a>, <a href="progress-example.html#x69">progress/progress.cpp</a>, <a href="qwerty-example.html#x372">qwerty/qwerty.cpp</a>, <a href="scrollview-example.html#x635">scrollview/scrollview.cpp</a>, <a href="showimg-example.html#x1328">showimg/showimg.cpp</a>, and <a href="sound-example.html#x2811">sound/sound.cpp</a>.
626<h3 class=fn>int <a name="insertTearOffHandle"></a>QPopupMenu::insertTearOffHandle ( int&nbsp;id = -1, int&nbsp;index = -1 )
627</h3>
628Inserts a tear-off handle into the menu. A tear-off handle is a
629special menu item that creates a copy of the menu when the menu is
630selected. This "torn-off" copy lives in a separate window. It
631contains the same menu items as the original menu, with the
632exception of the tear-off handle.
633<p> The handle item is assigned the identifier <em>id</em> or an
634automatically generated identifier if <em>id</em> is < 0. The generated
635identifiers (negative integers) are guaranteed to be unique within
636the entire application.
637<p> The <em>index</em> specifies the position in the menu. The tear-off
638handle is appended at the end of the list if <em>index</em> is negative.
639
640<p>Example: <a href="menu-example.html#x1879">menu/menu.cpp</a>.
641<h3 class=fn>bool <a name="isCheckable"></a>QPopupMenu::isCheckable () const
642</h3><p>Returns TRUE if the display of check marks on menu items is enabled; otherwise returns FALSE.
643See the <a href="qpopupmenu.html#checkable-prop">"checkable"</a> property for details.
644<h3 class=fn>bool <a name="isItemChecked"></a>QMenuData::isItemChecked ( int&nbsp;id ) const
645</h3>
646Returns TRUE if the menu item with the id <em>id</em> has been checked;
647otherwise returns FALSE.
648<p> <p>See also <a href="qmenudata.html#setItemChecked">setItemChecked</a>().
649
650<p>Examples: <a href="canvas-example.html#x2938">canvas/canvas.cpp</a>, <a href="progress-example.html#x70">progress/progress.cpp</a>, and <a href="showimg-example.html#x1329">showimg/showimg.cpp</a>.
651<h3 class=fn>bool <a name="isItemEnabled"></a>QMenuData::isItemEnabled ( int&nbsp;id ) const
652</h3>
653Returns TRUE if the item with identifier <em>id</em> is enabled;
654otherwise returns FALSE
655<p> <p>See also <a href="qmenudata.html#setItemEnabled">setItemEnabled</a>() and <a href="qmenudata.html#isItemVisible">isItemVisible</a>().
656
657<h3 class=fn>bool <a name="isItemVisible"></a>QMenuData::isItemVisible ( int&nbsp;id ) const
658</h3>
659Returns TRUE if the menu item with the id <em>id</em> is visible;
660otherwise returns FALSE.
661<p> <p>See also <a href="qmenudata.html#setItemVisible">setItemVisible</a>().
662
663<h3 class=fn>int <a name="itemHeight"></a>QPopupMenu::itemHeight ( int&nbsp;row ) const<tt> [protected]</tt>
664</h3>
665Calculates the height in pixels of the item in row <em>row</em>.
666
667<h3 class=fn>int <a name="itemHeight-2"></a>QPopupMenu::itemHeight ( QMenuItem&nbsp;*&nbsp;mi ) const<tt> [protected]</tt>
668</h3>
669This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
670<p> Calculates the height in pixels of the menu item <em>mi</em>.
671
672<h3 class=fn>int <a name="itemParameter"></a>QMenuData::itemParameter ( int&nbsp;id ) const
673</h3>
674Returns the parameter of the activation signal of item <em>id</em>.
675<p> If no parameter has been specified for this item with
676<a href="qmenudata.html#setItemParameter">setItemParameter</a>(), the value defaults to <em>id</em>.
677<p> <p>See also <a href="qmenudata.html#connectItem">connectItem</a>(), <a href="qmenudata.html#disconnectItem">disconnectItem</a>(), and <a href="qmenudata.html#setItemParameter">setItemParameter</a>().
678
679<h3 class=fn><a href="qpixmap.html">QPixmap</a>&nbsp;* <a name="pixmap"></a>QMenuData::pixmap ( int&nbsp;id ) const
680</h3>
681Returns the pixmap that has been set for menu item <em>id</em>, or 0 if
682no pixmap has been set.
683<p> <p>See also <a href="qmenudata.html#changeItem">changeItem</a>(), <a href="qmenudata.html#text">text</a>(), and <a href="qmenudata.html#iconSet">iconSet</a>().
684
685<h3 class=fn>void <a name="popup"></a>QPopupMenu::popup ( const&nbsp;<a href="qpoint.html">QPoint</a>&nbsp;&amp;&nbsp;pos, int&nbsp;indexAtPoint = -1 )
686</h3>
687Displays the popup menu so that the item number <em>indexAtPoint</em>
688will be at the specified <em>global</em> position <em>pos</em>. To translate a
689widget's local coordinates into global coordinates, use
690<a href="qwidget.html#mapToGlobal">QWidget::mapToGlobal</a>().
691<p> When positioning a popup with <a href="#exec">exec</a>() or <a href="#popup">popup</a>(), bear in mind that
692you cannot rely on the popup menu's current <a href="qwidget.html#size">size</a>(). For
693performance reasons, the popup adapts its size only when
694necessary, so in many cases, the size before and after the show is
695different. Instead, use <a href="qwidget.html#sizeHint">sizeHint</a>(). It calculates the proper size
696depending on the menu's current contents.
697
698<p>Example: <a href="listviews-example.html#x159">listviews/listviews.cpp</a>.
699<h3 class=fn>void <a name="removeItem"></a>QMenuData::removeItem ( int&nbsp;id )
700</h3>
701
702<p> Removes the menu item that has the identifier <em>id</em>.
703<p> <p>See also <a href="qmenudata.html#removeItemAt">removeItemAt</a>() and <a href="qmenudata.html#clear">clear</a>().
704
705<p>Example: <a href="canvas-chart-example.html#x2885">chart/chartform.cpp</a>.
706<h3 class=fn>void <a name="removeItemAt"></a>QMenuData::removeItemAt ( int&nbsp;index )
707</h3>
708Removes the menu item at position <em>index</em>.
709<p> <p>See also <a href="qmenudata.html#removeItem">removeItem</a>() and <a href="qmenudata.html#clear">clear</a>().
710
711<h3 class=fn>void <a name="setAccel"></a>QMenuData::setAccel ( const&nbsp;<a href="qkeysequence.html">QKeySequence</a>&nbsp;&amp;&nbsp;key, int&nbsp;id )
712</h3>
713Sets the accelerator key for the menu item <em>id</em> to <em>key</em>.
714<p> An accelerator key consists of a key code and a combination of the
715modifiers <a href="qt.html#Modifier-enum">SHIFT</a>, <a href="qt.html#Modifier-enum">CTRL</a>, <a href="qt.html#Modifier-enum">ALT</a> or <a href="qt.html#Modifier-enum">UNICODE_ACCEL</a> (OR'ed or
716added). The header file <a href="qnamespace-h.html">qnamespace.h</a> contains a list of key
717codes.
718<p> Defining an accelerator key produces a text that is added to the
719menu item; for instance, <a href="qt.html#Modifier-enum">CTRL</a> + <a href="qt.html#Key-enum">Key_O</a> produces "Ctrl+O". The
720text is formatted differently for different platforms.
721<p> Note that keyboard accelerators in Qt are not application-global,
722instead they are bound to a certain top-level window. For example,
723accelerators in QPopupMenu items only work for menus that are
724associated with a certain window. This is true for popup menus
725that live in a menu bar since their accelerators will then be
726installed in the menu bar itself. This also applies to stand-alone
727popup menus that have a top-level widget in their <a href="qwidget.html#parentWidget">parentWidget</a>()
728chain. The menu will then install its accelerator object on that
729top-level widget. For all other cases use an independent <a href="qaccel.html">QAccel</a>
730object.
731<p> Example:
732<pre>
733 <a href="qmenubar.html">QMenuBar</a> *mainMenu = new <a href="qmenubar.html">QMenuBar</a>;
734 QPopupMenu *fileMenu = new QPopupMenu; // file sub menu
735 fileMenu-&gt;<a href="qmenudata.html#insertItem">insertItem</a>( "Open Document", 67 ); // add "Open" item
736 fileMenu-&gt;<a href="qmenudata.html#setAccel">setAccel</a>( CTRL + Key_O, 67 ); // Ctrl+O to open
737 fileMenu-&gt;<a href="qmenudata.html#insertItem">insertItem</a>( "Quit", 69 ); // add "Quit" item
738 fileMenu-&gt;<a href="qmenudata.html#setAccel">setAccel</a>( CTRL + ALT + Key_Delete, 69 ); // add Alt+Del to quit
739 mainMenu-&gt;<a href="qmenudata.html#insertItem">insertItem</a>( "File", fileMenu ); // add the file menu
740 </pre>
741
742<p> If you need to translate accelerators, use <a href="qobject.html#tr">tr</a>() with a string:
743<pre>
744 fileMenu-&gt;setAccel( <a href="qobject.html#tr">tr</a>("Ctrl+O"), 67 );
745 </pre>
746
747<p> You can also specify the accelerator in the <a href="qmenudata.html#insertItem">insertItem</a>() function.
748You may prefer to use <a href="qaction.html">QAction</a> to associate accelerators with menu
749items.
750<p> <p>See also <a href="qmenudata.html#accel">accel</a>(), <a href="qmenudata.html#insertItem">insertItem</a>(), <a href="qaccel.html">QAccel</a>, and <a href="qaction.html">QAction</a>.
751
752<p>Example: <a href="menu-example.html#x1871">menu/menu.cpp</a>.
753<h3 class=fn>void <a name="setActiveItem"></a>QPopupMenu::setActiveItem ( int&nbsp;i )<tt> [virtual]</tt>
754</h3>
755Sets the currently active item to index <em>i</em> and repaints as necessary.
756
757<h3 class=fn>void <a name="setCheckable"></a>QPopupMenu::setCheckable ( bool )<tt> [virtual]</tt>
758</h3><p>Sets whether the display of check marks on menu items is enabled.
759See the <a href="qpopupmenu.html#checkable-prop">"checkable"</a> property for details.
760<h3 class=fn>void <a name="setItemChecked"></a>QMenuData::setItemChecked ( int&nbsp;id, bool&nbsp;check )
761</h3>
762If <em>check</em> is TRUE, checks the menu item with id <em>id</em>; otherwise
763unchecks the menu item with id <em>id</em>. Calls
764<a href="#setCheckable">QPopupMenu::setCheckable</a>( TRUE ) if necessary.
765<p> <p>See also <a href="qmenudata.html#isItemChecked">isItemChecked</a>().
766
767<p>Examples: <a href="canvas-example.html#x2939">canvas/canvas.cpp</a>, <a href="grapher-nsplugin-example.html#x2749">grapher/grapher.cpp</a>, <a href="mdi-example.html#x2032">mdi/application.cpp</a>, <a href="menu-example.html#x1872">menu/menu.cpp</a>, <a href="progress-example.html#x71">progress/progress.cpp</a>, <a href="scrollview-example.html#x636">scrollview/scrollview.cpp</a>, and <a href="showimg-example.html#x1330">showimg/showimg.cpp</a>.
768<h3 class=fn>void <a name="setItemEnabled"></a>QMenuData::setItemEnabled ( int&nbsp;id, bool&nbsp;enable )
769</h3>
770If <em>enable</em> is TRUE, enables the menu item with identifier <em>id</em>;
771otherwise disables the menu item with identifier <em>id</em>.
772<p> <p>See also <a href="qmenudata.html#isItemEnabled">isItemEnabled</a>().
773
774<p>Examples: <a href="mdi-example.html#x2033">mdi/application.cpp</a>, <a href="menu-example.html#x1873">menu/menu.cpp</a>, <a href="progress-example.html#x72">progress/progress.cpp</a>, and <a href="showimg-example.html#x1331">showimg/showimg.cpp</a>.
775<h3 class=fn>bool <a name="setItemParameter"></a>QMenuData::setItemParameter ( int&nbsp;id, int&nbsp;param )
776</h3>
777Sets the parameter of the activation signal of item <em>id</em> to <em>param</em>.
778<p> If any receiver takes an integer parameter, this value is passed.
779<p> <p>See also <a href="qmenudata.html#connectItem">connectItem</a>(), <a href="qmenudata.html#disconnectItem">disconnectItem</a>(), and <a href="qmenudata.html#itemParameter">itemParameter</a>().
780
781<p>Example: <a href="mdi-example.html#x2034">mdi/application.cpp</a>.
782<h3 class=fn>void <a name="setItemVisible"></a>QMenuData::setItemVisible ( int&nbsp;id, bool&nbsp;visible )
783</h3>
784If <em>visible</em> is TRUE, shows the menu item with id <em>id</em>; otherwise
785hides the menu item with id <em>id</em>.
786<p> <p>See also <a href="qmenudata.html#isItemVisible">isItemVisible</a>() and <a href="qmenudata.html#isItemEnabled">isItemEnabled</a>().
787
788<h3 class=fn>void <a name="setWhatsThis"></a>QMenuData::setWhatsThis ( int&nbsp;id, const&nbsp;<a href="qstring.html">QString</a>&nbsp;&amp;&nbsp;text )
789</h3>
790Sets <em>text</em> as What's This help for the menu item with identifier
791<em>id</em>.
792<p> <p>See also <a href="qmenudata.html#whatsThis">whatsThis</a>().
793
794<p>Examples: <a href="simple-application-example.html#x1554">application/application.cpp</a>, <a href="helpsystem-example.html#x2689">helpsystem/mainwindow.cpp</a>, and <a href="mdi-example.html#x2035">mdi/application.cpp</a>.
795<h3 class=fn><a href="qstring.html">QString</a> <a name="text"></a>QMenuData::text ( int&nbsp;id ) const
796</h3>
797Returns the text that has been set for menu item <em>id</em>, or
798<a href="qstring.html#QString-null">QString::null</a> if no text has been set.
799<p> <p>See also <a href="qmenudata.html#changeItem">changeItem</a>(), <a href="qmenudata.html#pixmap">pixmap</a>(), and <a href="qmenudata.html#iconSet">iconSet</a>().
800
801<p>Examples: <a href="qdir-example.html#x1831">qdir/qdir.cpp</a> and <a href="showimg-example.html#x1332">showimg/showimg.cpp</a>.
802<h3 class=fn>void <a name="updateItem"></a>QPopupMenu::updateItem ( int&nbsp;id )<tt> [virtual]</tt>
803</h3>
804Updates the item with identity <em>id</em>.
805
806<p>Reimplemented from <a href="qmenudata.html#updateItem">QMenuData</a>.
807<h3 class=fn><a href="qstring.html">QString</a> <a name="whatsThis"></a>QMenuData::whatsThis ( int&nbsp;id ) const
808</h3>
809Returns the What's This help text for the item with identifier <em>id</em> or <a href="qstring.html#QString-null">QString::null</a> if no text has yet been defined.
810<p> <p>See also <a href="qmenudata.html#setWhatsThis">setWhatsThis</a>().
811
812<hr><h2>Property Documentation</h2>
813<h3 class=fn>bool <a name="checkable-prop"></a>checkable</h3>
814<p>This property holds whether the display of check marks on menu items is enabled.
815<p>When TRUE, the display of check marks on menu items is enabled.
816Checking is always enabled when in Windows-style.
817<p> <p>See also <a href="qmenudata.html#setItemChecked">QMenuData::setItemChecked</a>().
818
819<p>Set this property's value with <a href="#setCheckable">setCheckable</a>() and get this property's value with <a href="#isCheckable">isCheckable</a>().
820<!-- eof -->
821<hr><p>
822This file is part of the <a href="index.html">Qt toolkit</a>.
823Copyright &copy; 1995-2007
824<a href="http://www.trolltech.com/">Trolltech</a>. All Rights Reserved.<p><address><hr><div align=center>
825<table width=100% cellspacing=0 border=0><tr>
826<td>Copyright &copy; 2007
827<a href="troll.html">Trolltech</a><td align=center><a href="trademarks.html">Trademarks</a>
828<td align=right><div align=right>Qt 3.3.8</div>
829</table></div></address></body>
830</html>
Note: See TracBrowser for help on using the repository browser.