source: trunk/doc/html/qtabbar.html

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

reference documentation added
File size: 19.7 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/qtabbar.cpp:168 -->
3<html>
4<head>
5<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
6<title>QTabBar 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>QTabBar Class Reference</h1>
33
34<p>The QTabBar class provides a tab bar, e.g. for use in tabbed dialogs.
35<a href="#details">More...</a>
36<p><tt>#include &lt;<a href="qtabbar-h.html">qtabbar.h</a>&gt;</tt>
37<p>Inherits <a href="qwidget.html">QWidget</a>.
38<p><a href="qtabbar-members.html">List of all member functions.</a>
39<h2>Public Members</h2>
40<ul>
41<li class=fn><a href="#QTabBar"><b>QTabBar</b></a> ( QWidget&nbsp;*&nbsp;parent = 0, const&nbsp;char&nbsp;*&nbsp;name = 0 )</li>
42<li class=fn><a href="#~QTabBar"><b>~QTabBar</b></a> ()</li>
43<li class=fn>enum <a href="#Shape-enum"><b>Shape</b></a> { RoundedAbove, RoundedBelow, TriangularAbove, TriangularBelow }</li>
44<li class=fn>Shape <a href="#shape"><b>shape</b></a> () const</li>
45<li class=fn>virtual void <a href="#setShape"><b>setShape</b></a> ( Shape )</li>
46<li class=fn>virtual int <a href="#addTab"><b>addTab</b></a> ( QTab&nbsp;*&nbsp;newTab )</li>
47<li class=fn>virtual int <a href="#insertTab"><b>insertTab</b></a> ( QTab&nbsp;*&nbsp;newTab, int&nbsp;index = -1 )</li>
48<li class=fn>virtual void <a href="#removeTab"><b>removeTab</b></a> ( QTab&nbsp;*&nbsp;t )</li>
49<li class=fn>virtual void <a href="#setTabEnabled"><b>setTabEnabled</b></a> ( int&nbsp;id, bool&nbsp;enabled )</li>
50<li class=fn>bool <a href="#isTabEnabled"><b>isTabEnabled</b></a> ( int&nbsp;id ) const</li>
51<li class=fn>int <a href="#currentTab"><b>currentTab</b></a> () const</li>
52<li class=fn>int <a href="#keyboardFocusTab"><b>keyboardFocusTab</b></a> () const</li>
53<li class=fn>QTab * <a href="#tab"><b>tab</b></a> ( int&nbsp;id ) const</li>
54<li class=fn>QTab * <a href="#tabAt"><b>tabAt</b></a> ( int&nbsp;index ) const</li>
55<li class=fn>int <a href="#indexOf"><b>indexOf</b></a> ( int&nbsp;id ) const</li>
56<li class=fn>int <a href="#count"><b>count</b></a> () const</li>
57<li class=fn>virtual void <a href="#layoutTabs"><b>layoutTabs</b></a> ()</li>
58<li class=fn>virtual QTab * <a href="#selectTab"><b>selectTab</b></a> ( const&nbsp;QPoint&nbsp;&amp;&nbsp;p ) const</li>
59<li class=fn>void <a href="#removeToolTip"><b>removeToolTip</b></a> ( int&nbsp;index )</li>
60<li class=fn>void <a href="#setToolTip"><b>setToolTip</b></a> ( int&nbsp;index, const&nbsp;QString&nbsp;&amp;&nbsp;tip )</li>
61<li class=fn>QString <a href="#toolTip"><b>toolTip</b></a> ( int&nbsp;index ) const</li>
62</ul>
63<h2>Public Slots</h2>
64<ul>
65<li class=fn>virtual void <a href="#setCurrentTab"><b>setCurrentTab</b></a> ( int )</li>
66<li class=fn>virtual void <a href="#setCurrentTab-2"><b>setCurrentTab</b></a> ( QTab&nbsp;*&nbsp;tab )</li>
67</ul>
68<h2>Signals</h2>
69<ul>
70<li class=fn>void <a href="#selected"><b>selected</b></a> ( int&nbsp;id )</li>
71<li class=fn>void <a href="#layoutChanged"><b>layoutChanged</b></a> ()</li>
72</ul>
73<h2>Properties</h2>
74<ul>
75<li class=fn>int <a href="#count-prop"><b>count</b></a>&nbsp;- the number of tabs in the tab bar &nbsp;<em>(read only)</em></li>
76<li class=fn>int <a href="#currentTab-prop"><b>currentTab</b></a>&nbsp;- the id of the tab bar's visible tab</li>
77<li class=fn>int <a href="#keyboardFocusTab-prop"><b>keyboardFocusTab</b></a>&nbsp;- the id of the tab that has the keyboard focus &nbsp;<em>(read only)</em></li>
78<li class=fn>Shape <a href="#shape-prop"><b>shape</b></a>&nbsp;- the shape of the tabs in the tab bar</li>
79</ul>
80<h2>Protected Members</h2>
81<ul>
82<li class=fn>virtual void <a href="#paint"><b>paint</b></a> ( QPainter&nbsp;*&nbsp;p, QTab&nbsp;*&nbsp;t, bool&nbsp;selected ) const</li>
83<li class=fn>virtual void <a href="#paintLabel"><b>paintLabel</b></a> ( QPainter&nbsp;*&nbsp;p, const&nbsp;QRect&nbsp;&amp;&nbsp;br, QTab&nbsp;*&nbsp;t, bool&nbsp;has_focus ) const</li>
84<li class=fn>virtual void <a href="#paintEvent"><b>paintEvent</b></a> ( QPaintEvent&nbsp;*&nbsp;e )</li>
85<li class=fn>QPtrList&lt;QTab&gt; * <a href="#tabList"><b>tabList</b></a> ()</li>
86</ul>
87<hr><a name="details"></a><h2>Detailed Description</h2>
88
89
90The QTabBar class provides a tab bar, e.g. for use in tabbed dialogs.
91<p>
92<p> QTabBar is straightforward to use; it draws the tabs using one of
93the predefined <a href="#Shape-enum">shapes</a>, and emits a
94signal when a tab is selected. It can be subclassed to tailor the
95look and feel. Qt also provides a ready-made <a href="qtabwidget.html">QTabWidget</a> and a
96<a href="qtabdialog.html">QTabDialog</a>.
97<p> The choice of tab shape is a matter of taste, although tab dialogs
98(for preferences and similar) invariably use <a href="#Shape-enum">RoundedAbove</a>;
99nobody uses <a href="#Shape-enum">TriangularAbove</a>. Tab controls in windows other than
100dialogs almost always use either <a href="#Shape-enum">RoundedBelow</a> or <a href="#Shape-enum">TriangularBelow</a>. Many spreadsheets and other tab controls in which
101all the pages are essentially similar use <a href="#Shape-enum">TriangularBelow</a>,
102whereas <a href="#Shape-enum">RoundedBelow</a> is used mostly when the pages are
103different (e.g. a multi-page tool palette).
104<p> The most important part of QTabBar's API is the <a href="#selected">selected</a>() signal.
105This is emitted whenever the selected page changes (even at
106startup, when the selected page changes from 'none'). There is
107also a slot, <a href="#setCurrentTab">setCurrentTab</a>(), which can be used to select a page
108programmatically.
109<p> QTabBar creates automatic accelerator keys in the manner of
110<a href="qbutton.html">QButton</a>; e.g. if a tab's label is "&amp;Graphics", Alt+G becomes an
111accelerator key for switching to that tab.
112<p> The following virtual functions may need to be reimplemented:
113<ul>
114<li> <a href="#paint">paint</a>() paints a single tab. <a href="#paintEvent">paintEvent</a>() calls paint() for
115each tab so that any overlap will look right.
116<li> <a href="#addTab">addTab</a>() creates a new tab and adds it to the bar.
117<li> <a href="#selectTab">selectTab</a>() decides which tab, if any, the user selects with the mouse.
118</ul>
119<p> The index of the current tab is returned by <a href="#currentTab">currentTab</a>(). The tab
120with a particular index is returned by <a href="#tabAt">tabAt</a>(), the tab with a
121particular id is returned by <a href="#tab">tab</a>(). The index of a tab is returned
122by <a href="#indexOf">indexOf</a>(). The current tab can be set by index or tab pointer
123using one of the <a href="#setCurrentTab">setCurrentTab</a>() functions.
124<p> <img src=qtabbar-m.png> <img src=qtabbar-w.png>
125<p>See also <a href="advanced.html">Advanced Widgets</a>.
126
127<hr><h2>Member Type Documentation</h2>
128<h3 class=fn><a name="Shape-enum"></a>QTabBar::Shape</h3>
129
130<p> This enum type lists the built-in shapes supported by QTabBar:
131<ul>
132<li><tt>QTabBar::RoundedAbove</tt> - the normal rounded look above the pages
133<li><tt>QTabBar::RoundedBelow</tt> - the normal rounded look below the pages
134<li><tt>QTabBar::TriangularAbove</tt> - triangular tabs above the pages (very
135unusual; included for completeness)
136<li><tt>QTabBar::TriangularBelow</tt> - triangular tabs similar to those used in
137the Excel spreadsheet, for example
138</ul>
139<hr><h2>Member Function Documentation</h2>
140<h3 class=fn><a name="QTabBar"></a>QTabBar::QTabBar ( <a href="qwidget.html">QWidget</a>&nbsp;*&nbsp;parent = 0, const&nbsp;char&nbsp;*&nbsp;name = 0 )
141</h3>
142Constructs a new, empty tab bar; the <em>parent</em> and <em>name</em>
143arguments are passed on to the <a href="qwidget.html">QWidget</a> constructor.
144
145<h3 class=fn><a name="~QTabBar"></a>QTabBar::~QTabBar ()
146</h3>
147Destroys the tab control, freeing memory used.
148
149<h3 class=fn>int <a name="addTab"></a>QTabBar::addTab ( <a href="qtab.html">QTab</a>&nbsp;*&nbsp;newTab )<tt> [virtual]</tt>
150</h3>
151Adds the tab, <em>newTab</em>, to the tab control.
152<p> Sets <em>newTab</em>'s id to a new id and places the tab just to the
153right of the existing tabs. If the tab's label contains an
154ampersand, the letter following the ampersand is used as an
155accelerator for the tab, e.g. if the label is "Bro&amp;wse" then
156Alt+W becomes an accelerator which will move the focus to this
157tab. Returns the id.
158<p> <p>See also <a href="#insertTab">insertTab</a>().
159
160<h3 class=fn>int <a name="count"></a>QTabBar::count () const
161</h3><p>Returns the number of tabs in the tab bar.
162See the <a href="qtabbar.html#count-prop">"count"</a> property for details.
163<h3 class=fn>int <a name="currentTab"></a>QTabBar::currentTab () const
164</h3><p>Returns the id of the tab bar's visible tab.
165See the <a href="qtabbar.html#currentTab-prop">"currentTab"</a> property for details.
166<h3 class=fn>int <a name="indexOf"></a>QTabBar::indexOf ( int&nbsp;id ) const
167</h3>
168Returns the position index of the tab with id <em>id</em> or -1 if no
169tab has this <em>id</em>.
170<p> <p>See also <a href="#tabAt">tabAt</a>().
171
172<h3 class=fn>int <a name="insertTab"></a>QTabBar::insertTab ( <a href="qtab.html">QTab</a>&nbsp;*&nbsp;newTab, int&nbsp;index = -1 )<tt> [virtual]</tt>
173</h3>
174Inserts the tab, <em>newTab</em>, into the tab control.
175<p> If <em>index</em> is not specified, the tab is simply appended.
176Otherwise it's inserted at the specified position.
177<p> Sets <em>newTab</em>'s id to a new id. If the tab's label contains an
178ampersand, the letter following the ampersand is used as an
179accelerator for the tab, e.g. if the label is "Bro&amp;wse" then
180Alt+W becomes an accelerator which will move the focus to this
181tab. Returns the id.
182<p> <p>See also <a href="#addTab">addTab</a>().
183
184<h3 class=fn>bool <a name="isTabEnabled"></a>QTabBar::isTabEnabled ( int&nbsp;id ) const
185</h3>
186Returns TRUE if the tab with id <em>id</em> exists and is enabled;
187otherwise returns FALSE.
188<p> <p>See also <a href="#setTabEnabled">setTabEnabled</a>().
189
190<h3 class=fn>int <a name="keyboardFocusTab"></a>QTabBar::keyboardFocusTab () const
191</h3><p>Returns the id of the tab that has the keyboard focus.
192See the <a href="qtabbar.html#keyboardFocusTab-prop">"keyboardFocusTab"</a> property for details.
193<h3 class=fn>void <a name="layoutChanged"></a>QTabBar::layoutChanged ()<tt> [signal]</tt>
194</h3>
195
196<p> QTabBar emits the signal whenever the layout of the tab bar has
197been recalculated, for example when the contents of a tab change.
198
199<h3 class=fn>void <a name="layoutTabs"></a>QTabBar::layoutTabs ()<tt> [virtual]</tt>
200</h3>
201Lays out all existing tabs according to their label and their
202iconset.
203
204<h3 class=fn>void <a name="paint"></a>QTabBar::paint ( <a href="qpainter.html">QPainter</a>&nbsp;*&nbsp;p, <a href="qtab.html">QTab</a>&nbsp;*&nbsp;t, bool&nbsp;selected ) const<tt> [virtual protected]</tt>
205</h3>
206Paints the tab <em>t</em> using painter <em>p</em>. If and only if <em>selected</em>
207is TRUE, <em>t</em> is drawn currently selected.
208<p> This virtual function may be reimplemented to change the look of
209QTabBar. If you decide to reimplement it, you may also need to
210reimplement <a href="qwidget.html#sizeHint">sizeHint</a>().
211
212<h3 class=fn>void <a name="paintEvent"></a>QTabBar::paintEvent ( <a href="qpaintevent.html">QPaintEvent</a>&nbsp;*&nbsp;e )<tt> [virtual protected]</tt>
213</h3>
214Repaints the tab row. All the painting is done by <a href="#paint">paint</a>();
215<a href="#paintEvent">paintEvent</a>() only decides which tabs need painting and in what
216order. The event is passed in <em>e</em>.
217<p> <p>See also <a href="#paint">paint</a>().
218
219<p>Reimplemented from <a href="qwidget.html#paintEvent">QWidget</a>.
220<h3 class=fn>void <a name="paintLabel"></a>QTabBar::paintLabel ( <a href="qpainter.html">QPainter</a>&nbsp;*&nbsp;p, const&nbsp;<a href="qrect.html">QRect</a>&nbsp;&amp;&nbsp;br, <a href="qtab.html">QTab</a>&nbsp;*&nbsp;t, bool&nbsp;has_focus ) const<tt> [virtual protected]</tt>
221</h3>
222Paints the label of tab <em>t</em> centered in rectangle <em>br</em> using
223painter <em>p</em>. A focus indication is drawn if <em>has_focus</em> is TRUE.
224
225<h3 class=fn>void <a name="removeTab"></a>QTabBar::removeTab ( <a href="qtab.html">QTab</a>&nbsp;*&nbsp;t )<tt> [virtual]</tt>
226</h3>
227Removes tab <em>t</em> from the tab control, and deletes the tab.
228
229<h3 class=fn>void <a name="removeToolTip"></a>QTabBar::removeToolTip ( int&nbsp;index )
230</h3>
231Removes the tool tip for the tab at index position <em>index</em>.
232
233<h3 class=fn><a href="qtab.html">QTab</a>&nbsp;* <a name="selectTab"></a>QTabBar::selectTab ( const&nbsp;<a href="qpoint.html">QPoint</a>&nbsp;&amp;&nbsp;p ) const<tt> [virtual]</tt>
234</h3>
235This virtual function is called by the mouse event handlers to
236determine which tab is pressed. The default implementation returns
237a pointer to the tab whose bounding rectangle contains <em>p</em>, if
238exactly one tab's bounding rectangle contains <em>p</em>. Otherwise it
239returns 0.
240<p> <p>See also <a href="qwidget.html#mousePressEvent">mousePressEvent</a>() and <a href="qwidget.html#mouseReleaseEvent">mouseReleaseEvent</a>().
241
242<h3 class=fn>void <a name="selected"></a>QTabBar::selected ( int&nbsp;id )<tt> [signal]</tt>
243</h3>
244
245<p> QTabBar emits this signal whenever any tab is selected, whether by
246the program or by the user. The argument <em>id</em> is the id of the
247tab as returned by <a href="#addTab">addTab</a>().
248<p> <a href="qwidget.html#show">show</a>() is guaranteed to emit this signal; you can display your
249page in a slot connected to this signal.
250
251<h3 class=fn>void <a name="setCurrentTab"></a>QTabBar::setCurrentTab ( int )<tt> [virtual slot]</tt>
252</h3><p>Sets the id of the tab bar's visible tab.
253See the <a href="qtabbar.html#currentTab-prop">"currentTab"</a> property for details.
254<h3 class=fn>void <a name="setCurrentTab-2"></a>QTabBar::setCurrentTab ( <a href="qtab.html">QTab</a>&nbsp;*&nbsp;tab )<tt> [virtual slot]</tt>
255</h3>
256This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
257<p> Raises <em>tab</em> and emits the <a href="#selected">selected</a>() signal unless the tab was
258already current.
259<p> <p>See also <a href="#currentTab-prop">currentTab</a> and <a href="#selected">selected</a>().
260
261<h3 class=fn>void <a name="setShape"></a>QTabBar::setShape ( <a href="qtabbar.html#Shape-enum">Shape</a> )<tt> [virtual]</tt>
262</h3><p>Sets the shape of the tabs in the tab bar.
263See the <a href="qtabbar.html#shape-prop">"shape"</a> property for details.
264<h3 class=fn>void <a name="setTabEnabled"></a>QTabBar::setTabEnabled ( int&nbsp;id, bool&nbsp;enabled )<tt> [virtual]</tt>
265</h3>
266Enables tab <em>id</em> if <em>enabled</em> is TRUE or disables it if <em>enabled</em> is FALSE. If <em>id</em> is currently selected,
267<a href="#setTabEnabled">setTabEnabled</a>(FALSE) makes another tab selected.
268<p> setTabEnabled() updates the display if this causes a change in <em>id</em>'s status.
269<p> <p>See also <a href="qwidget.html#update">update</a>() and <a href="#isTabEnabled">isTabEnabled</a>().
270
271<h3 class=fn>void <a name="setToolTip"></a>QTabBar::setToolTip ( int&nbsp;index, const&nbsp;<a href="qstring.html">QString</a>&nbsp;&amp;&nbsp;tip )
272</h3>
273Sets the tool tip for the tab at index position <em>index</em> to <em>tip</em>.
274
275<h3 class=fn><a href="qtabbar.html#Shape-enum">Shape</a> <a name="shape"></a>QTabBar::shape () const
276</h3><p>Returns the shape of the tabs in the tab bar.
277See the <a href="qtabbar.html#shape-prop">"shape"</a> property for details.
278<h3 class=fn><a href="qtab.html">QTab</a>&nbsp;* <a name="tab"></a>QTabBar::tab ( int&nbsp;id ) const
279</h3>
280Returns the tab with id <em>id</em> or 0 if there is no such tab.
281<p> <p>See also <a href="#count-prop">count</a>.
282
283<h3 class=fn><a href="qtab.html">QTab</a>&nbsp;* <a name="tabAt"></a>QTabBar::tabAt ( int&nbsp;index ) const
284</h3>
285Returns the tab at position <em>index</em>.
286<p> <p>See also <a href="#indexOf">indexOf</a>().
287
288<h3 class=fn><a href="qptrlist.html">QPtrList</a>&lt;QTab&gt;&nbsp;* <a name="tabList"></a>QTabBar::tabList ()<tt> [protected]</tt>
289</h3>
290The list of <a href="qtab.html">QTab</a> objects in the tab bar.
291<p> This list is unlikely to be in the order that the QTab elements
292appear visually. One way of iterating over the tabs is like this:
293<pre>
294 for ( uint i = 0; i &lt; myTabBar-&gt;count(); ++i ) {
295 nextTab = myTabBar-&gt;tabAt( i );
296 // do something with nextTab
297 }
298 </pre>
299
300
301<h3 class=fn><a href="qstring.html">QString</a> <a name="toolTip"></a>QTabBar::toolTip ( int&nbsp;index ) const
302</h3>
303Returns the tool tip for the tab at index position <em>index</em>.
304
305<hr><h2>Property Documentation</h2>
306<h3 class=fn>int <a name="count-prop"></a>count</h3>
307<p>This property holds the number of tabs in the tab bar.
308<p>Get this property's value with <a href="#count">count</a>().
309<p><p>See also <a href="#tab">tab</a>().
310
311<h3 class=fn>int <a name="currentTab-prop"></a>currentTab</h3>
312<p>This property holds the id of the tab bar's visible tab.
313<p>If no tab page is currently visible, the property's value is -1.
314Even if the property's value is not -1, you cannot assume that the
315user can see the relevant page, or that the tab is enabled. When
316you need to display something the value of this property
317represents the best page to display.
318<p> When this property is set to <em>id</em>, it will raise the tab with the
319id <em>id</em> and emit the <a href="#selected">selected</a>() signal.
320<p> <p>See also <a href="#selected">selected</a>() and <a href="#isTabEnabled">isTabEnabled</a>().
321
322<p>Set this property's value with <a href="#setCurrentTab">setCurrentTab</a>() and get this property's value with <a href="#currentTab">currentTab</a>().
323<h3 class=fn>int <a name="keyboardFocusTab-prop"></a>keyboardFocusTab</h3>
324<p>This property holds the id of the tab that has the <a href="focus.html#keyboard-focus">keyboard focus</a>.
325<p>This property contains the id of the tab that has the keyboard
326focus or -1 if the tab bar does not have the keyboard focus.
327
328<p>Get this property's value with <a href="#keyboardFocusTab">keyboardFocusTab</a>().
329<h3 class=fn><a href="qtabbar.html#Shape-enum">Shape</a> <a name="shape-prop"></a>shape</h3>
330<p>This property holds the shape of the tabs in the tab bar.
331<p>The value of this property is one of the following: <a href="#Shape-enum">RoundedAbove</a> (default), <a href="#Shape-enum">RoundedBelow</a>, <a href="#Shape-enum">TriangularAbove</a> or <a href="#Shape-enum">TriangularBelow</a>.
332<p> <p>See also <a href="#Shape-enum">Shape</a>.
333
334<p>Set this property's value with <a href="#setShape">setShape</a>() and get this property's value with <a href="#shape">shape</a>().
335<!-- eof -->
336<hr><p>
337This file is part of the <a href="index.html">Qt toolkit</a>.
338Copyright &copy; 1995-2007
339<a href="http://www.trolltech.com/">Trolltech</a>. All Rights Reserved.<p><address><hr><div align=center>
340<table width=100% cellspacing=0 border=0><tr>
341<td>Copyright &copy; 2007
342<a href="troll.html">Trolltech</a><td align=center><a href="trademarks.html">Trademarks</a>
343<td align=right><div align=right>Qt 3.3.8</div>
344</table></div></address></body>
345</html>
Note: See TracBrowser for help on using the repository browser.