1/* This file is part of the KDE project
2 Copyright (C) 2003 Daniel Molkentin <molkentin@kde.org>
3 Copyright (C) 2003 David Faure <faure@kde.org>
4
5 This library is free software; you can redistribute it and/or
6 modify it under the terms of the GNU Library General Public
7 License as published by the Free Software Foundation; either
8 version 2 of the License, or (at your option) any later version.
9
10 This library is distributed in the hope that it will be useful,
11 but WITHOUT ANY WARRANTY; without even the implied warranty of
12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 Library General Public License for more details.
14
15 You should have received a copy of the GNU Library General Public License
16 along with this library; see the file COPYING.LIB. If not, write to
17 the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
18 Boston, MA 02110-1301, USA.
19 */
20
21#ifndef KPARTS_STATUSBAREXTENSION_H
22#define KPARTS_STATUSBAREXTENSION_H
23
24#include <QtGui/QWidget>
25
26#include <kparts/kparts_export.h>
27#include <QtCore/QList>
28
29class KStatusBar;
30class KMainWindow;
31class QEvent;
32
33namespace KParts
34{
35
36 class ReadOnlyPart;
37
38 // Defined in impl
39 class StatusBarItem;
40 class StatusBarExtensionPrivate;
41
42
43 /**
44 * @short an extension for KParts that allows more sophisticated statusbar handling
45 *
46 * Every part can use this class to customize the statusbar as long as it is active.
47 * Add items via addStatusBarItem and remove an item with removeStatusBarItem.
48 *
49 * IMPORTANT: do NOT add any items immediately after constructing the extension.
50 * Give the application time to set the statusbar in the extension if necessary.
51 */
52 class KPARTS_EXPORT StatusBarExtension : public QObject
53 {
54 Q_OBJECT
55
56 public:
57 StatusBarExtension( KParts::ReadOnlyPart *parent );
58 ~StatusBarExtension();
59
60 /**
61 * This adds a widget to the statusbar for this part.
62 * If you use this method instead of using statusBar() directly,
63 * this extension will take care of removing the items when the parts GUI
64 * is deactivated and will re-add them when it is reactivated.
65 * The parameters are the same as QStatusBar::addWidget().
66 *
67 * Note that you can't use KStatusBar methods (inserting text items by id)
68 * but you can create a KStatusBarLabel with a dummy id instead, and use
69 * it directly in order to get the same look and feel.
70 *
71 * @param widget the widget to add
72 * @param stretch the stretch factor. 0 for a minimum size.
73 * @param permanent passed to QStatusBar::addWidget as the "permanent" bool.
74 * Note that the item isn't really permanent though, it goes away when
75 * the part is unactivated. This simply controls where temporary messages
76 * hide the @p widget, and whether it's added to the left or to the right side.
77 *
78 * @Note that the widget does not technically become a child of the
79 * StatusBarExtension in a QObject sense. However, it @em will be deleted
80 * when the StatusBarExtension is deleted.
81 *
82 * IMPORTANT: do NOT add any items immediately after constructing the extension.
83 * Give the application time to set the statusbar in the extension if necessary.
84 */
85 void addStatusBarItem( QWidget * widget, int stretch, bool permanent );
86
87 /**
88 * Remove a widget from the statusbar for this part.
89 */
90 void removeStatusBarItem( QWidget * widget );
91
92 /**
93 * @return the statusbar of the KMainWindow in which this part is currently embedded.
94 * WARNING: this could return 0L
95 */
96 KStatusBar* statusBar() const;
97
98 /**
99 * This allows the hosting application to set a particular KStatusBar
100 * for this part. If it doesn't do this, the statusbar used will be
101 * the one of the KMainWindow in which the part is embedded.
102 * Konqueror uses this to assign a view-statusbar to the part.
103 * The part should never call this method!
104 */
105 void setStatusBar( KStatusBar* status );
106
107 /**
108 * Queries @p obj for a child object which inherits from this
109 * BrowserExtension class. Convenience method.
110 */
111 static StatusBarExtension *childObject( QObject *obj );
112
113 /** @internal */
114 virtual bool eventFilter( QObject *watched, QEvent* ev );
115
116 private:
117 // for future extensions
118 friend class StatusBarExtensionPrivate;
119 StatusBarExtensionPrivate* const d;
120 };
121
122}
123#endif // KPARTS_STATUSBAREXTENSION_H
124
125// vim: ts=2 sw=2 et
126