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 | |
29 | class 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 | */ |
44 | class 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 ( const QPoint & ); |
321 | |
322 | /** |
323 | * The right mouse button was pressed over a widget. |
324 | */ |
325 | void ( 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 ( 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 | |