1/* This file is part of the KDE libraries
2 Copyright (C) 1997 Mark Donohoe (donohoe@kde.org)
3 Copyright (C) 1997, 1998 1998 Sven Radej (sven@lisa.exp.univie.ac.at)
4 Copyright (C) 2007 Aron Boström (aron.bostrom@gmail.com)
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 KSTATUSBAR_H
23#define KSTATUSBAR_H
24
25#include <kdeui_export.h>
26#include <QtGui/QStatusBar>
27
28class QObject;
29class QEvent;
30class KStatusBarPrivate;
31
32/**
33 * @short %KDE statusbar widget
34 *
35 * Display status messages.
36 *
37 * You can insert text labels or custom widgets. Their geometry is managed
38 * internally. KStatusBar resizes itself, but positioning is left to
39 * KMainWindow (or to you, if you don't use KMainWindow ).
40 *
41 * A special type of item is a message which is a temporary text-message
42 * displayed on top of other items in full-width. Messages are visible for
43 * specified time, or until you call the slot QStatusBar::clearMessage(). See
44 * QStatusBar::showMessage for details.
45 *
46 * It is useful to connect the KActionCollection signals to the
47 * QStatusBar::showMessage slots.
48 *
49 * KStatusBar inherits QStatusBar, you can freely use all QStatusBar
50 * methods.
51 *
52 * Empty text items are not visible. They will become visible when you change
53 * (add) text.
54 *
55 * @author Mark Donohoe <donohoe@kde.org> and Sven Radej <radej@kde.org>
56
57 * @see KActionCollection
58 */
59class KDEUI_EXPORT KStatusBar : public QStatusBar
60{
61 Q_OBJECT
62
63public:
64 /**
65 * Constructs a status bar. @p parent is usually KMainWindow.
66 */
67 explicit KStatusBar( QWidget* parent = 0 );
68
69 /**
70 * Destructor.
71 *
72 * Deletes all internal objects.
73 */
74 ~KStatusBar();
75
76 /**
77 * Inserts a temporary text label into the status bar.
78 * Parameter @p stretch is passed to QStatusBar::addWidget .
79 *
80 * @param text The label's text string.
81 * @param id id of item
82 * @param stretch stretch passed to QStatusBar::addWidget
83 *
84 * @see QStatusbar::addWidget
85 *
86 */
87 void insertItem(const QString& text, int id, int stretch=0 );
88
89 /**
90 * Inserts a permanent text label into the status bar.
91 * Parameter @p stretch is passed to QStatusBar::addWidget .
92 *
93 * @param text The label's text string.
94 * @param id id of item
95 * @param stretch stretch passed to QStatusBar::addPermanentWidget
96 *
97 * @see QStatusbar::addPermanentWidget
98 *
99 */
100 void insertPermanentItem(const QString& text, int id, int stretch=0 );
101
102 /**
103 * Inserts a fixed width temporary text label into status bar. The width
104 * will be set according to @p text, but will remain fixed even if you
105 * change text. You can change fixed width by calling setItemFixed.
106 *
107 * @param text The label's text string
108 * @param id id of item
109 */
110 void insertFixedItem(const QString& text, int id);
111
112 /**
113 * Inserts a fixed width permanent text label into status bar. The width
114 * will be set according to @p text, but will remain fixed even if you
115 * change text. You can change fixed width by calling setItemFixed.
116 *
117 * @param text The label's text string
118 * @param id id of item
119 */
120 void insertPermanentFixedItem(const QString& text, int id);
121
122 /**
123 * Removes an item.
124 *
125 * @param id The item to remove.
126 */
127 void removeItem( int id );
128
129 /**
130 * Returns true if an item with @p id exists already in KStatusBar,
131 * otherwise returns false.
132 *
133 * @param id id of the item
134 */
135 bool hasItem( int id ) const;
136
137 /**
138 * The text of an item, if it exists.
139 */
140 QString itemText( int id ) const;
141
142 /**
143 * Changes the text in a status bar field.
144 *
145 * The item will be resized to fit the text. If you change text to be empty,
146 * item will not be visible (until you add some text).
147 *
148 * @param text The label's text string
149 * @param id The id of item.
150 */
151 void changeItem( const QString& text, int id );
152
153 /**
154 * Sets the alignment of item @p id. By default all fields are aligned
155 * @p AlignHCenter | @p AlignVCenter. See QLabel::setAlignment for details.
156 *
157 */
158 void setItemAlignment(int id, Qt::Alignment alignment);
159
160 /**
161 * Sets item @p id to have fixed width. This cannot be undone, but you can
162 * always set new fixed width.
163 *
164 * @param id id of item
165 * @param width fixed width in pixels. Default -1 is to adapt to text width.
166 */
167 void setItemFixed(int id, int width=-1);
168
169Q_SIGNALS:
170
171 /**
172 * Emitted when mouse is pressed over item @p id.
173 *
174 * Connect to this signal if you want to respond to mouse press events.
175 *
176 */
177 void pressed( int );
178
179 /**
180 * Emitted when mouse is released over item @p id.
181 *
182 * Connect to this signal if you want to respond to mouse release events (clicks).
183 */
184 void released( int );
185
186protected:
187 bool eventFilter(QObject* object, QEvent *event);
188
189private:
190 KStatusBarPrivate* const d;
191};
192
193#endif // KSTATUSBAR_H
194
195