1/* This file is part of the KDE libraries
2 Copyright (C) 2003 Stephan Binner <binner@kde.org>
3 Copyright (C) 2003 Zack Rusin <zack@kde.org>
4 Copyright (C) 2009 Urs Wolfer <uwolfer @ kde.org>
5
6 This library is free software; you can redistribute it and/or
7 modify it under the terms of the GNU Library General Public
8 License as published by the Free Software Foundation; either
9 version 2 of the License, or (at your option) any later version.
10
11 This library is distributed in the hope that it will be useful,
12 but WITHOUT ANY WARRANTY; without even the implied warranty of
13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14 Library General Public License for more details.
15
16 You should have received a copy of the GNU Library General Public License
17 along with this library; see the file COPYING.LIB. If not, write to
18 the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
19 Boston, MA 02110-1301, USA.
20*/
21
22#ifndef KTABWIDGET_H
23#define KTABWIDGET_H
24
25#include <kdeui_export.h>
26
27#include <QtGui/QTabWidget>
28
29class QTab;
30
31/**
32 * \brief A widget containing multiple tabs
33 *
34 * It extends the Qt QTabWidget, providing extra optionally features such as close buttons when you hover
35 * over the icon in the tab, and also adds functionality such as responding to mouse wheel scroll events to switch
36 * the active tab.
37 *
38 * It is recommended to use KTabWidget instead of QTabWidget unless you have a good reason not to.
39 *
40 * See also the QTabWidget documentation.
41 *
42 * \image html ktabwidget.png "KDE Tab Widget"
43 */
44class KDEUI_EXPORT KTabWidget : public QTabWidget //krazy:exclude=qclasses
45{
46 Q_OBJECT
47#ifndef KDE_NO_DEPRECATED
48 Q_PROPERTY( bool tabReorderingEnabled READ isTabReorderingEnabled WRITE setTabReorderingEnabled )
49 Q_PROPERTY( bool hoverCloseButton READ hoverCloseButton WRITE setHoverCloseButton )
50 Q_PROPERTY( bool hoverCloseButtonDelayed READ hoverCloseButtonDelayed WRITE setHoverCloseButtonDelayed )
51 Q_PROPERTY( bool closeButtonEnabled READ isCloseButtonEnabled WRITE setCloseButtonEnabled )
52 Q_PROPERTY( bool tabCloseActivatePrevious READ tabCloseActivatePrevious WRITE setTabCloseActivatePrevious )
53#endif
54 Q_PROPERTY( bool automaticResizeTabs READ automaticResizeTabs WRITE setAutomaticResizeTabs )
55
56 public:
57
58 /**
59 * Creates a new tab widget.
60 *
61 * @param parent The parent widgets.
62 * @param flags The Qt window flags @see QWidget.
63 */
64 explicit KTabWidget( QWidget *parent = 0, Qt::WindowFlags flags = 0 );
65
66 /**
67 * Destroys the tab widget.
68 */
69 virtual ~KTabWidget();
70
71 /**
72 * Set the tab of the given widget to \a color.
73 * This is simply a convenience method for QTabBar::setTabTextColor.
74 */
75 void setTabTextColor( int index, const QColor& color );
76
77 /**
78 * Returns the tab color for the given widget.
79 * This is simply a convenience method for QTabBar::tabTextColor.
80 */
81 QColor tabTextColor( int index ) const;
82
83 /**
84 * Returns true if tab ordering with the middle mouse button
85 * has been enabled.
86 *
87 * @deprecated Use QTabWidget::isMovable() instead.
88 */
89#ifndef KDE_NO_DEPRECATED
90 KDE_DEPRECATED bool isTabReorderingEnabled() const;
91#endif
92
93 /**
94 * Returns true if the close button is shown on tabs
95 * when mouse is hovering over them.
96 *
97 * @deprecated Use QTabWidget::tabsClosable() instead.
98 */
99#ifndef KDE_NO_DEPRECATED
100 KDE_DEPRECATED bool hoverCloseButton() const;
101#endif
102
103 /**
104 * Returns true if the close button is shown on tabs
105 * after a delay.
106 *
107 * @deprecated Use QTabWidget::setTabsClosable() instead.
108 */
109#ifndef KDE_NO_DEPRECATED
110 KDE_DEPRECATED bool hoverCloseButtonDelayed() const;
111#endif
112
113 /**
114 * Returns true if the close button is shown on tabs.
115 *
116 * @since 4.1
117 *
118 * @deprecated Use QTabWidget::tabsClosable() instead.
119 */
120#ifndef KDE_NO_DEPRECATED
121 KDE_DEPRECATED bool isCloseButtonEnabled() const;
122#endif
123
124 /**
125 * Returns true if closing the current tab activates the previous
126 * actice tab instead of the one to the right.
127 *
128 * @deprecated Use tabBar()->selectionBehaviorOnRemove() instead.
129 */
130#ifndef KDE_NO_DEPRECATED
131 KDE_DEPRECATED bool tabCloseActivatePrevious() const;
132#endif
133
134 /**
135 * Returns true if calling setTitle() will resize tabs
136 * to the width of the tab bar.
137 */
138 bool automaticResizeTabs() const;
139
140 /**
141 * If \a hide is true, the tabbar is hidden along with any corner
142 * widgets.
143 */
144 void setTabBarHidden( bool hide );
145
146 /**
147 * Returns true if the tabbar was hidden by a call to setTabBarHidden( true ).
148 * Returns false if the widget itself is hidden, but no call to setTabBarHidden( true )
149 * has been made.
150 */
151 bool isTabBarHidden() const;
152
153 /**
154 Reimplemented for internal reasons.
155 *
156 virtual void insertTab( QWidget *, const QString &, int index = -1 );
157
158 *!
159 Reimplemented for internal reasons.
160 *
161 virtual void insertTab( QWidget *child, const QIcon& iconset,
162 const QString &label, int index = -1 );
163 *!
164 Reimplemented for internal reasons.
165 *
166 virtual void insertTab( QWidget *, QTab *, int index = -1 );*/
167
168 /**
169 * Reimplemented for internal reasons.
170 */
171 QString tabText( int ) const; // but it's not virtual...
172
173#ifdef KDE3_SUPPORT
174 /**
175 * @deprecated use tabText
176 */
177#ifndef KDE_NO_DEPRECATED
178 inline KDE_DEPRECATED QString label( int index ) const { return tabText( index ); }
179#endif
180
181 /**
182 * @deprecated use tabText
183 */
184#ifndef KDE_NO_DEPRECATED
185 inline KDE_DEPRECATED QString tabLabel( QWidget *w ) const { return tabText( indexOf( w ) ); }
186#endif
187
188 /**
189 * @deprecated use setTabText
190 */
191#ifndef KDE_NO_DEPRECATED
192 inline KDE_DEPRECATED void setTabLabel( QWidget *w, const QString &l ) { setTabText( indexOf( w ),l ); }
193#endif
194#endif
195
196 /**
197 * Reimplemented for internal reasons.
198 */
199 void setTabText( int , const QString & );
200
201 using QTabWidget::tabBar;
202
203 public Q_SLOTS:
204 /**
205 * Move a widget's tab from first to second specified index and emit
206 * signal movedTab( int, int ) afterwards.
207 */
208 virtual void moveTab( int, int );
209
210 /**
211 * Removes the widget, reimplemented for
212 * internal reasons (keeping labels in sync).
213 * @deprecated since 4.0
214 */
215 virtual QT_MOC_COMPAT void removePage ( QWidget * w );
216
217 /**
218 * Removes the widget, reimplemented for
219 * internal reasons (keeping labels in sync).
220 */
221 virtual void removeTab(int index); // but it's not virtual in QTabWidget...
222
223 /**
224 * If \a enable is true, tab reordering with middle button will be enabled.
225 *
226 * Note that once enabled you shouldn't rely on previously queried
227 * currentPageIndex() or indexOf( QWidget * ) values anymore.
228 *
229 * You can connect to signal movedTab(int, int) which will notify
230 * you from which index to which index a tab has been moved.
231 *
232 * @deprecated Use QTabWidget::setMovable() instead.
233 *
234 * Note, however, that QTabWidget::setMovable(true) disables
235 * dragging tabs out of the KTabBar (e.g., dragging the tab
236 * URL from Konqueror to another application)!
237 */
238#ifndef KDE_NO_DEPRECATED
239 QT_MOC_COMPAT void setTabReorderingEnabled( bool enable );
240#endif
241
242 /**
243 * If \a enable is true, a close button will be shown on mouse hover
244 * over tab icons which will emit signal closeRequest( QWidget * )
245 * when pressed.
246 *
247 * @deprecated Use QTabWidget::setTabsClosable() instead.
248 */
249#ifndef KDE_NO_DEPRECATED
250 QT_MOC_COMPAT void setHoverCloseButton( bool enable );
251#endif
252
253 /**
254 * If \a delayed is true, a close button will be shown on mouse hover
255 * over tab icons after mouse double click delay else immediately.
256 *
257 * @deprecated Use QTabWidget::setTabsClosable() instead.
258 */
259#ifndef KDE_NO_DEPRECATED
260 QT_MOC_COMPAT void setHoverCloseButtonDelayed( bool delayed );
261#endif
262
263 /**
264 * If enabled, a close button is available for each tab. The
265 * signal KTabWidget::closeRequest() is emitted, if the close button
266 * has been clicked.
267 *
268 * @since 4.1
269 *
270 * @deprecated Use QTabWidget::setTabsClosable() instead.
271 */
272#ifndef KDE_NO_DEPRECATED
273 QT_MOC_COMPAT void setCloseButtonEnabled( bool );
274#endif
275
276 /**
277 * If \a previous is true, closing the current tab activates the
278 * previous active tab instead of the one to the right.
279 *
280 * @deprecated Use tabBar()->setSelectionBehaviorOnRemove() instead.
281 */
282#ifndef KDE_NO_DEPRECATED
283 QT_MOC_COMPAT void setTabCloseActivatePrevious( bool previous );
284#endif
285
286 /**
287 * If \a enable is true, tabs will be resized to the width of the tab bar.
288 *
289 * Does not work reliably with "QTabWidget* foo=new KTabWidget()" and if
290 * you change tabs via the tabbar or by accessing tabs directly.
291 */
292 void setAutomaticResizeTabs( bool enable );
293
294 Q_SIGNALS:
295 /**
296 * Connect to this and set accept to true if you can and want to decode the event.
297 */
298 void testCanDecode(const QDragMoveEvent *e, bool &accept /* result */);
299
300 /**
301 * Received an event in the empty space beside tabbar. Usually creates a new tab.
302 * This signal is only possible after testCanDecode and positive accept result.
303 */
304 void receivedDropEvent( QDropEvent * );
305
306 /**
307 * Received an drop event on given widget's tab.
308 * This signal is only possible after testCanDecode and positive accept result.
309 */
310 void receivedDropEvent( QWidget *, QDropEvent * );
311
312 /**
313 * Request to start a drag operation on the given tab.
314 */
315 void initiateDrag( QWidget * );
316
317 /**
318 * The right mouse button was pressed over empty space besides tabbar.
319 */
320 void contextMenu( const QPoint & );
321
322 /**
323 * The right mouse button was pressed over a widget.
324 */
325 void contextMenu( QWidget *, const QPoint & );
326
327#ifndef KDE_NO_DEPRECATED
328 /**
329 * A tab was moved from first to second index. This signal is only
330 * possible after you have called setTabReorderingEnabled( true ).
331 */
332 void movedTab( int, int );
333#endif
334
335 /**
336 * A double left mouse button click was performed over empty space besides tabbar.
337 * The signal is emitted on the second press of the mouse button, before the release.
338 */
339 void mouseDoubleClick();
340
341 /**
342 * A double left mouse button click was performed over the widget.
343 * The signal is emitted on the second press of the mouse button, before the release.
344 */
345 void mouseDoubleClick( QWidget * );
346
347 /**
348 * A middle mouse button click was performed over empty space besides tabbar.
349 * The signal is emitted on the release of the mouse button.
350 */
351 void mouseMiddleClick();
352
353 /**
354 * A middle mouse button click was performed over the widget.
355 * The signal is emitted on the release of the mouse button.
356 */
357 void mouseMiddleClick( QWidget * );
358
359 /**
360 * The close button of a widget's tab was clicked. This signal is
361 * only possible after you have called setCloseButtonEnabled( true ).
362 */
363 void closeRequest( QWidget * );
364
365 protected:
366 virtual void mouseDoubleClickEvent( QMouseEvent* );
367 virtual void mousePressEvent( QMouseEvent* );
368 virtual void mouseReleaseEvent( QMouseEvent* );
369 virtual void dragEnterEvent( QDragEnterEvent* );
370 virtual void dragMoveEvent( QDragMoveEvent* );
371 virtual void dropEvent( QDropEvent* );
372 int tabBarWidthForMaxChars( int );
373#ifndef QT_NO_WHEELEVENT
374 virtual void wheelEvent( QWheelEvent* );
375#endif
376 virtual void resizeEvent( QResizeEvent* );
377 virtual void tabInserted( int );
378 virtual void tabRemoved ( int );
379
380 /**
381 * @deprecated This method has no effect and should not be called
382 */
383#ifndef KDE_NO_DEPRECATED
384 KDE_DEPRECATED void currentChanged( int );
385#endif
386
387 protected Q_SLOTS:
388 virtual void receivedDropEvent( int, QDropEvent* );
389 virtual void initiateDrag( int );
390 virtual void contextMenu( int, const QPoint& );
391 virtual void mouseDoubleClick( int );
392 virtual void mouseMiddleClick( int );
393 virtual void closeRequest( int );
394#ifndef QT_NO_WHEELEVENT
395 virtual void wheelDelta( int );
396#endif
397
398 private:
399 class Private;
400 Private * const d;
401
402 Q_PRIVATE_SLOT(d, void slotTabMoved(int, int))
403};
404
405#endif
406