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 | |
28 | class 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 | */ |
44 | class 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 | |
59 | public: |
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 | |
213 | protected: |
214 | // Reimplemented from QWidget |
215 | virtual void paintEvent(QPaintEvent *event); |
216 | virtual void changeEvent(QEvent *event); |
217 | |
218 | private: |
219 | /** |
220 | * @internal |
221 | */ |
222 | class Private; |
223 | Private *const d; |
224 | }; |
225 | |
226 | #endif |
227 | |