1/*
2 This file is part of the KDE project
3 SPDX-FileCopyrightText: 2008 Rafael Fernández López <ereslibre@kde.org>
4
5 SPDX-License-Identifier: LGPL-2.0-or-later
6*/
7
8#ifndef KCAPACITYBAR_H
9#define KCAPACITYBAR_H
10
11#include <QStyle>
12#include <QWidget>
13#include <memory>
14
15#include <kwidgetsaddons_export.h>
16
17class QPaintEvent;
18
19/*!
20 * \class KCapacityBar
21 * \inmodule KWidgetsAddons
22 *
23 * \brief This widget shows a bar which is filled to show the level of usage of
24 * a certain device.
25 *
26 * This widget represents a bar which goal is to show the level of usage of a
27 * device. Its look is similar to a progress bar, but different, because this
28 * widget does not want to give a notion of progress.
29 *
30 * \since 4.2
31 *
32 * \image kcapacitybar.png "KCapacityBar Widget"
33 */
34class KWIDGETSADDONS_EXPORT KCapacityBar : public QWidget
35{
36 Q_OBJECT
37
38 /*!
39 * \property KCapacityBar::value
40 */
41 Q_PROPERTY(int value READ value WRITE setValue)
42
43 /*!
44 * \property KCapacityBar::text
45 */
46 Q_PROPERTY(QString text READ text WRITE setText)
47
48 /*!
49 * \property KCapacityBar::drawTextMode
50 */
51 Q_PROPERTY(DrawTextMode drawTextMode READ drawTextMode WRITE setDrawTextMode)
52
53 /*!
54 * \property KCapacityBar::fillFullBlocks
55 */
56 Q_PROPERTY(bool fillFullBlocks READ fillFullBlocks WRITE setFillFullBlocks)
57
58 /*!
59 * \property KCapacityBar::continuous
60 */
61 Q_PROPERTY(bool continuous READ continuous WRITE setContinuous)
62
63 /*!
64 * \property KCapacityBar::barHeight
65 */
66 Q_PROPERTY(int barHeight READ barHeight WRITE setBarHeight)
67
68 /*!
69 * \property KCapacityBar::horizontalTextAlignment
70 */
71 Q_PROPERTY(Qt::Alignment horizontalTextAlignment READ horizontalTextAlignment WRITE setHorizontalTextAlignment)
72
73public:
74 /*!
75 * \value DrawTextInline If any text set, draw it into the capacity bar
76 * \value DrawTextOutline If any text set, draw it out of the capacity bar
77 */
78 enum DrawTextMode {
79 DrawTextInline = 0,
80 DrawTextOutline,
81 };
82 Q_ENUM(DrawTextMode)
83
84 /*!
85 * Constructs a capacity bar with DrawTextOutline as draw text mode.
86 *
87 * \a parent The parent of the widget.
88 * \since 5.24
89 */
90 explicit KCapacityBar(QWidget *parent = nullptr);
91
92 /*!
93 * Capacity bar constructor.
94 *
95 * \a drawTextMode If any text set, whether to draw it into the capacity bar
96 * or not.
97 *
98 * \a parent The parent of the widget.
99 */
100 explicit KCapacityBar(DrawTextMode drawTextMode, QWidget *parent = nullptr);
101 ~KCapacityBar() override;
102
103 /*!
104 * Capacity bar fill value.
105 *
106 * \a value This parameter can take values from 0 to 100.
107 *
108 * Its value is 0 by default.
109 */
110 void setValue(int value);
111
112 /*!
113 * Returns the fill value of the capacity bar.
114 */
115 int value() const;
116
117 /*!
118 * Sets the text for the capacity bar.
119 *
120 * \a text The text that the capacity bar will show.
121 *
122 * This is an empty string by default.
123 */
124 void setText(const QString &text);
125
126 /*!
127 * Returns the text that the capacity bar will show.
128 */
129 QString text() const;
130
131 /*!
132 * When the capacity bar is non-continuous, sets whether the last block
133 * shown should be drawn full or can be cut off (depending on the capacity
134 * bar width, and the value set on it).
135 *
136 * \a fillFullBlocks If true, the last block drawn will be fully filled,
137 * on other case, the last block drawn could be cut off.
138 *
139 * \note This method is only relevant if the capacity bar is in
140 * non-continuous mode.
141 *
142 * Its value is true by default.
143 *
144 * \sa setContinuous, continuous
145 */
146 void setFillFullBlocks(bool fillFullBlocks);
147
148 /*!
149 * Returns whether the last block shown can be cut off when necessary.
150 */
151 bool fillFullBlocks() const;
152
153 /*!
154 * Sets whether the fill of the capacity bar should be continuous or in
155 * block mode.
156 *
157 * \a continuous If true, the fill of the capacity bar is done in a
158 * continuous way. In other case, the fill is done with
159 * separated blocks.
160 *
161 * \note Its value is true by default.
162 */
163 void setContinuous(bool continuous);
164
165 /*!
166 * Returns whether the fill of the capacity bar should be continuous or
167 * block-based.
168 */
169 bool continuous() const;
170
171 /*!
172 * Sets the height (in pixels) of the bar.
173 *
174 * \a barHeight The preferred height (in pixels) of the capacity bar.
175 *
176 * \note If you set a certain text and the capacity bar is in inline mode,
177 * the height of the bar will be the maximum of the font height and
178 * this value.
179 *
180 * \note If you set a certain text and the capacity bar is in outline mode,
181 * the height of the whole capacity bar will be bigger than this
182 * value. Take in count the height of this widget is got from adding
183 * the bar height, the font metrics height and a small separator
184 * between the bar and the outline text.
185 *
186 * \note Its value is 12 pixels by default.
187 */
188 void setBarHeight(int barHeight);
189
190 /*!
191 * Returns the preferred height of the capacity bar.
192 */
193 int barHeight() const;
194
195 /*!
196 * If the capacity bar is in outline text mode, draw the text with
197 * \a textAlignment alignment.
198 *
199 * \a textAlignment Sets the horizontal alignment for the text if
200 * the capacity bar is in outline text mode.
201 *
202 * \note If \a textAlignemt contains vertical alignment flags, they will be
203 * ignored.
204 *
205 * \note If the capacity bar is in inline text mode, the text is always
206 * centered, and both vertical and horizontal flags set through this
207 * method are ignored.
208 *
209 * \note Its value is centered by default.
210 */
211 void setHorizontalTextAlignment(Qt::Alignment textAlignment);
212
213 /*!
214 * Returns the horizontal alignment for the text that will be drawn.
215 */
216 Qt::Alignment horizontalTextAlignment() const;
217
218 /*!
219 * Set the way text is drawn if any is set
220 *
221 * \a mode If any text set, whether to draw it into the capacity bar
222 * or not.
223 */
224 void setDrawTextMode(DrawTextMode mode);
225
226 /*!
227 * The way text is drawn, inside the capacity bar or outside of it
228 */
229 DrawTextMode drawTextMode() const;
230
231 /*!
232 * This method allows you to draw the widget, directly, for example on
233 * item delegates. You only need the painter object and the rect where
234 * this widget should be drawn.
235 */
236 void drawCapacityBar(QPainter *p, const QRect &rect) const;
237
238 /*!
239 * This method allows you to draw the widget, directly, for example on
240 * item delegates. You need the painter object and the rect where
241 * this widget should be drawn, and the state that it should be painted in.
242 *
243 * For example, when in a selected delegate, setting the correct state
244 * ensures that the bar keeps sufficient contrast to the selection color.
245 *
246 * \since 6.12
247 */
248 void drawCapacityBar(QPainter *p, const QRect &rect, QStyle::State state) const;
249
250 // Reimplemented from QWidget
251 QSize minimumSizeHint() const override;
252
253protected:
254 void paintEvent(QPaintEvent *event) override;
255
256 void changeEvent(QEvent *event) override;
257
258private:
259 std::unique_ptr<class KCapacityBarPrivate> const d;
260};
261
262#endif
263

source code of kwidgetsaddons/src/kcapacitybar.h