1/*
2 * This file is part of the KDE project
3 * Copyright (C) 2008 Rafael Fernández López <ereslibre@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 KCAPACITYBAR_H
22#define KCAPACITYBAR_H
23
24#include <QtGui/QWidget>
25
26#include <kdeui_export.h>
27
28class QPaintEvent;
29
30/**
31 * @brief This widget shows a bar which is filled to show the level of usage of
32 * a certain device.
33 *
34 * This widget represents a bar which goal is to show the level of usage of a
35 * device. Its look is similar to a progress bar, but different, because this
36 * widget does not want to give a notion of progress.
37 *
38 * @since 4.2
39 *
40 * \image html kcapacitybar.png "KDE Capacity Bar"
41 *
42 * @author Rafael Fernández López <ereslibre@kde.org>
43 */
44class KDEUI_EXPORT KCapacityBar
45 : public QWidget
46{
47 Q_OBJECT
48
49 Q_PROPERTY(int value READ value WRITE setValue)
50 Q_PROPERTY(QString text READ text WRITE setText)
51 Q_PROPERTY(DrawTextMode drawTextMode READ drawTextMode WRITE setDrawTextMode)
52 Q_PROPERTY(bool fillFullBlocks READ fillFullBlocks WRITE setFillFullBlocks)
53 Q_PROPERTY(bool continuous READ continuous WRITE setContinuous)
54 Q_PROPERTY(int barHeight READ barHeight WRITE setBarHeight)
55 Q_PROPERTY(Qt::Alignment horizontalTextAlignment READ horizontalTextAlignment
56 WRITE setHorizontalTextAlignment)
57 Q_ENUMS(DrawTextMode)
58
59public:
60 enum DrawTextMode {
61 DrawTextInline = 0, ///< If any text set, draw it into the capacity bar
62 DrawTextOutline ///< If any text set, draw it out of the capacity bar
63 };
64
65 /**
66 * Capacity bar constructor.
67 *
68 * @param drawTextMode If any text set, whether to draw it into the capacity bar
69 * or not.
70 * @param parent The parent of the widget.
71 */
72 explicit KCapacityBar(DrawTextMode drawTextMode = DrawTextOutline, QWidget *parent = 0);
73 ~KCapacityBar();
74
75 /**
76 * Capacity bar fill value.
77 *
78 * @param value This parameter can take values from 0 to 100.
79 *
80 * @note Its value is 0 by default.
81 */
82 void setValue(int value);
83
84 /**
85 * @return The fill value of the capacity bar.
86 */
87 int value() const;
88
89 /**
90 * Sets the text for the capacity bar.
91 *
92 * @param text The text that the capacity bar will show.
93 *
94 * @note This is an empty string by default.
95 */
96 void setText(const QString &text);
97
98 /**
99 * @return The text that the capacity bar will show.
100 */
101 QString text() const;
102
103 /**
104 * When the capacity bar is non-continuous, sets whether the last block
105 * shown should be drawn full or can be cut off (depending on the capacity
106 * bar width, and the value set on it).
107 *
108 * @param fillFullBlocks If true, the last block drawn will be fully filled,
109 * on other case, the last block drawn could be cut off.
110 *
111 * @note This method is only relevant if the capacity bar is in
112 * non-continuous mode.
113 *
114 * @note Its value is true by default.
115 *
116 * @see setContinuous, continuous
117 */
118 void setFillFullBlocks(bool fillFullBlocks);
119
120 /**
121 * @return Whether the last block shown can be cut off when necessary.
122 */
123 bool fillFullBlocks() const;
124
125 /**
126 * Sets whether the fill of the capacity bar should be continuous or in
127 * block mode.
128 *
129 * @param continuous If true, the fill of the capacity bar is done in a
130 * continuous way. In other case, the fill is done with
131 * separated blocks.
132 *
133 * @note Its value is true by default.
134 */
135 void setContinuous(bool continuous);
136
137 /**
138 * @return Whether the fill of the capacity bar should be continuous or
139 * block-based.
140 */
141 bool continuous() const;
142
143 /**
144 * Sets the height (in pixels) of the bar.
145 *
146 * @param barHeight The preferred height (in pixels) of the capacity bar.
147 *
148 * @note If you set a certain text and the capacity bar is in inline mode,
149 * the height of the bar will be the maximum of the font height and
150 * this value.
151 *
152 * @note If you set a certain text and the capacity bar is in outline mode,
153 * the height of the whole capacity bar will be bigger than this
154 * value. Take in count the height of this widget is got from adding
155 * the bar height, the font metrics height and a small separator
156 * between the bar and the outline text.
157 *
158 * @note Its value is 12 pixels by default.
159 */
160 void setBarHeight(int barHeight);
161
162 /**
163 * @return The preferred height of the capacity bar.
164 */
165 int barHeight() const;
166
167 /**
168 * If the capacity bar is in outline text mode, draw the text with
169 * @p textAlignment alignment.
170 *
171 * @param textAlignment Sets the horizontal alignment for the text if
172 * the capacity bar is in outline text mode.
173 *
174 * @note If @p textAlignemt contains vertical alignment flags, they will be
175 * ignored.
176 *
177 * @note If the capacity bar is in inline text mode, the text is always
178 * centered, and both vertical and horizontal flags set through this
179 * method are ignored.
180 *
181 * @note Its value is centered by default.
182 */
183 void setHorizontalTextAlignment(Qt::Alignment textAlignment);
184
185 /**
186 * @return The horizontal alignment for the text that will be drawn.
187 */
188 Qt::Alignment horizontalTextAlignment() const;
189
190 /**
191 * Set the way text is drawn if any is set
192 *
193 * @param drawTextMode If any text set, whether to draw it into the capacity bar
194 * or not.
195 */
196 void setDrawTextMode(DrawTextMode mode);
197
198 /**
199 * The way text is drawn, inside the capacity bar or outside of it
200 */
201 DrawTextMode drawTextMode() const;
202
203 /**
204 * This method allows you to draw the widget, directly, for example on
205 * item delegates. You only need the painter object and the rect where
206 * this widget should be drawn.
207 */
208 void drawCapacityBar(QPainter *p, const QRect &rect) const;
209
210 // Reimplemented from QWidget
211 virtual QSize minimumSizeHint() const;
212
213protected:
214 // Reimplemented from QWidget
215 virtual void paintEvent(QPaintEvent *event);
216 virtual void changeEvent(QEvent *event);
217
218private:
219 /**
220 * @internal
221 */
222 class Private;
223 Private *const d;
224};
225
226#endif
227