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

source code of kwidgetsaddons/src/kcapacitybar.h