Kstars

QRoundProgressBar.h
1/*
2 QRoundProgressBar - a circular progress bar Qt widget.
3
4 Sintegrial Technologies (c) 2015-now
5
6 The software is freeware and is distributed "as is" with the complete source codes.
7 Anybody is free to use it in any software projects, either commercial or non-commercial.
8 Please do not remove this copyright message and remain the name of the author unchanged.
9
10 It is very appreciated if you produce some feedback to us case you are going to use
11 the software.
12
13 Please send your questions, suggestions, and information about found issues to the
14
15 sintegrial@gmail.com
16
17*/
18
19#ifndef QROUNDPROGRESSBAR_H
20#define QROUNDPROGRESSBAR_H
21
22#include <QWidget>
23
24/**
25 * @brief The QRoundProgressBar class represents a circular progress bar and maintains its API
26 * similar to the *QProgressBar*.
27 *
28 * ### Styles
29 * QRoundProgressBar currently supports Donut, Pie and Line styles. See setBarStyle() for more details.
30 *
31 * ### Colors
32 * Generally QRoundProgressBar uses its palette and font attributes to define how it will look.
33 *
34 * The following \a QPalette members are considered:
35 * - *QPalette::Window* background of the whole widget (normally should be set to Qt::NoBrush)
36 * - *QPalette::Base* background of the non-filled progress bar area (should be set to Qt::NoBrush to make it transparent)
37 * - *QPalette::AlternateBase* background of the central circle where the text is shown (for \a Donut style)
38 * - *QPalette::Shadow* foreground of the non-filled progress bar area (i.e. border color)
39 * - *QPalette::Highlight* background of the filled progress bar area
40 * - *QPalette::Text* color of the text shown in the center
41 *
42 * Create a \a QPalette with given attributes and apply it via `setPalette()`.
43 *
44 * ### Color gradient
45 * \a Donut and \a Pie styles allow to use color gradient for currernt value area instead of plain brush fill.
46 * See setDataColors() for more details.
47 *
48 * ### Value text
49 * Value text is generally drawn inside the QRoundProgressBar using its `font()` and \a QPalette::Text role from its `palette()`.
50 *
51 * To define pattern of the text, use setFormat() function (see Qt's \a QProgressBar for more details).
52 *
53 * To define number of decimals to be shown, use setDecimals() function.
54 *
55 * ### Font
56 * To use own font for value text, apply it via `setFont()`.
57 *
58 * By default, font size will be adjusted automatically to fit the inner circle of the widget.
59 */
61{
63 public:
64 explicit QRoundProgressBar(QWidget *parent = nullptr);
65
66 static const int PositionLeft = 180;
67 static const int PositionTop = 90;
68 static const int PositionRight = 0;
69 static const int PositionBottom = -90;
70
71 /**
72 * @brief Return position (in degrees) of minimum value.
73 * \sa setNullPosition
74 */
75 double nullPosition() const { return m_nullPosition; }
76 /**
77 * @brief Defines position of minimum value.
78 * @param position position on the circle (in degrees) of minimum value
79 * \sa nullPosition
80 */
81 void setNullPosition(double position);
82
83 /**
84 * @brief The BarStyle enum defines general look of the progress bar.
85 */
87 {
88 /// Donut style (filled torus around the text)
90 /// Pie style (filled pie segment with the text in center)
92 /// Line style (thin round line around the text)
94 };
95 /**
96 * @brief Sets visual style of the widget.
97 * \sa barStyle
98 */
99 void setBarStyle(BarStyle style);
100 /**
101 * @brief Returns current progree bar style.
102 * \sa setBarStyle
103 */
104 BarStyle barStyle() const { return m_barStyle; }
105
106 /**
107 * @brief Sets width of the outline circle pen.
108 * @param penWidth width of the outline circle pen (in pixels)
109 */
110 void setOutlinePenWidth(double penWidth);
111 /**
112 * @brief Returns width of the outline circle pen.
113 */
114 double outlinePenWidth() const { return m_outlinePenWidth; }
115
116 /**
117 * @brief Sets width of the data circle pen.
118 * @param penWidth width of the data circle pen (in pixels)
119 */
120 void setDataPenWidth(double penWidth);
121 /**
122 * @brief Returns width of the data circle pen.
123 */
124 double dataPenWidth() const { return m_dataPenWidth; }
125
126 /**
127 * @brief Sets colors of the visible data and makes gradient brush from them.
128 * Gradient colors can be set for \a Donut and \a Pie styles (see setBarStyle() function).
129 *
130 * *Warning*: this function will override widget's `palette()` to set dynamically created gradient brush.
131 *
132 * @param stopPoints List of colors (should have at least 2 values, see Qt's \a QGradientStops for more details).
133 * Color value at point 0 corresponds to the minimum() value, while color value at point 1
134 * corresponds to the maximum(). Other colors will be distributed accordingly to the defined ranges (see setRange()).
135 */
136 void setDataColors(const QGradientStops &stopPoints);
137
138 /**
139 * @brief Defines the string used to generate the current text.
140 * If no format is set, no text will be shown.
141 * @param format see \a QProgressBar's format description
142 * \sa setDecimals
143 */
144 void setFormat(const QString &format);
145 /**
146 * @brief Sets format string to empty string. No text will be shown therefore.
147 * See setFormat() for more information.
148 */
149 void resetFormat();
150 /**
151 * @brief Returns the string used to generate the current text.
152 */
153 QString format() const { return m_format; }
154
155 /**
156 * @brief Sets number of decimals to show after the comma (default is 1).
157 * \sa setFormat
158 */
159 void setDecimals(int count);
160 /**
161 * @brief Returns number of decimals to show after the comma (default is 1).
162 * \sa setFormat, setDecimals
163 */
164 int decimals() const { return m_decimals; }
165
166 /**
167 * @brief Returns current value shown on the widget.
168 * \sa setValue()
169 */
170 double value() const { return m_value; }
171 /**
172 * @brief Returns minimum of the allowed value range.
173 * \sa setMinimum, setRange
174 */
175 double minimum() const { return m_min; }
176 /**
177 * @brief Returns maximum of the allowed value range.
178 * \sa setMaximum, setRange
179 */
180 double maximum() const { return m_max; }
181
182 public Q_SLOTS:
183 /**
184 * @brief Defines minimum und maximum of the allowed value range.
185 * If the current value does not fit into the range, it will be automatically adjusted.
186 * @param min minimum of the allowed value range
187 * @param max maximum of the allowed value range
188 */
189 void setRange(double min, double max);
190 /**
191 * @brief Defines minimum of the allowed value range.
192 * If the current value does not fit into the range, it will be automatically adjusted.
193 * @param min minimum of the allowed value range
194 * \sa setRange
195 */
196 void setMinimum(double min);
197 /**
198 * @brief Defines maximum of the allowed value range.
199 * If the current value does not fit into the range, it will be automatically adjusted.
200 * @param max maximum of the allowed value range
201 * \sa setRange
202 */
203 void setMaximum(double max);
204 /**
205 * @brief Sets a value which will be shown on the widget.
206 * @param val must be between minimum() and maximum()
207 */
208 void setValue(double val);
209 /**
210 * @brief Integer version of the previous slot.
211 * @param val must be between minimum() and maximum()
212 */
213 void setValue(int val);
214
215 protected:
216 void paintEvent(QPaintEvent *event) override;
217 virtual void drawBackground(QPainter &p, const QRectF &baseRect);
218 virtual void drawBase(QPainter &p, const QRectF &baseRect);
219 virtual void drawValue(QPainter &p, const QRectF &baseRect, double value, double arcLength);
220 virtual void calculateInnerRect(const QRectF &baseRect, double outerRadius, QRectF &innerRect, double &innerRadius);
221 virtual void drawInnerBackground(QPainter &p, const QRectF &innerRect);
222 virtual void drawText(QPainter &p, const QRectF &innerRect, double innerRadius, double value);
223 virtual QString valueToText(double value) const;
224 virtual void valueFormatChanged();
225
226 QSize minimumSizeHint() const override { return QSize(32, 32); }
227
228 bool hasHeightForWidth() const override { return true; }
229 int heightForWidth(int w) const override { return w; }
230
231 void rebuildDataBrushIfNeeded();
232
233 double m_min, m_max;
234 double m_value;
235
236 double m_nullPosition;
237 BarStyle m_barStyle;
238 double m_outlinePenWidth, m_dataPenWidth;
239
240 QGradientStops m_gradientData;
241 bool m_rebuildBrush;
242
243 QString m_format;
244 int m_decimals;
245
246 static const int UF_VALUE = 1;
247 static const int UF_PERCENT = 2;
248 static const int UF_MAX = 4;
249 int m_updateFlags;
250};
251
252#endif // QROUNDPROGRESSBAR_H
The QRoundProgressBar class represents a circular progress bar and maintains its API similar to the Q...
void setDataPenWidth(double penWidth)
Sets width of the data circle pen.
void setValue(double val)
Sets a value which will be shown on the widget.
void setMinimum(double min)
Defines minimum of the allowed value range.
BarStyle barStyle() const
Returns current progree bar style.
void setOutlinePenWidth(double penWidth)
Sets width of the outline circle pen.
void setDecimals(int count)
Sets number of decimals to show after the comma (default is 1).
double outlinePenWidth() const
Returns width of the outline circle pen.
double value() const
Returns current value shown on the widget.
void setMaximum(double max)
Defines maximum of the allowed value range.
double dataPenWidth() const
Returns width of the data circle pen.
void setBarStyle(BarStyle style)
Sets visual style of the widget.
void setFormat(const QString &format)
Defines the string used to generate the current text.
int decimals() const
Returns number of decimals to show after the comma (default is 1).
double minimum() const
Returns minimum of the allowed value range.
void setNullPosition(double position)
Defines position of minimum value.
QString format() const
Returns the string used to generate the current text.
void setRange(double min, double max)
Defines minimum und maximum of the allowed value range.
BarStyle
The BarStyle enum defines general look of the progress bar.
@ StylePie
Pie style (filled pie segment with the text in center)
@ StyleLine
Line style (thin round line around the text)
@ StyleDonut
Donut style (filled torus around the text)
void resetFormat()
Sets format string to empty string.
void setDataColors(const QGradientStops &stopPoints)
Sets colors of the visible data and makes gradient brush from them.
double nullPosition() const
Return position (in degrees) of minimum value.
double maximum() const
Returns maximum of the allowed value range.
Q_OBJECTQ_OBJECT
Q_SLOTSQ_SLOTS
QObject * parent() const const
virtual bool event(QEvent *event) override
QStyle * style() const const
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Fri Nov 22 2024 12:11:14 by doxygen 1.12.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.