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 
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  */
60 class QRoundProgressBar : public QWidget
61 {
62  Q_OBJECT
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  */
86  enum BarStyle
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  */
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
Q_OBJECTQ_OBJECT
double maximum() const
Returns maximum of the allowed value range.
void setRange(double min, double max)
Defines minimum und maximum of the allowed value range.
void resetFormat()
Sets format string to empty string.
Q_SLOTSQ_SLOTS
@ StyleLine
Line style (thin round line around the text)
void setMaximum(double max)
Defines maximum of the allowed value range.
double outlinePenWidth() const
Returns width of the outline circle pen.
virtual bool event(QEvent *event) override
double dataPenWidth() const
Returns width of the data circle pen.
QString format() const
Returns the string used to generate the current text.
int decimals() const
Returns number of decimals to show after the comma (default is 1).
void setBarStyle(BarStyle style)
Sets visual style of the widget.
void setValue(double val)
Sets a value which will be shown on the widget.
void setNullPosition(double position)
Defines position of minimum value.
void setFormat(const QString &format)
Defines the string used to generate the current text.
QStyle * style() const const
@ StylePie
Pie style (filled pie segment with the text in center)
BarStyle
The BarStyle enum defines general look of the progress bar.
double value() const
Returns current value shown on the widget.
void setDataPenWidth(double penWidth)
Sets width of the data circle pen.
void setDecimals(int count)
Sets number of decimals to show after the comma (default is 1).
The QRoundProgressBar class represents a circular progress bar and maintains its API similar to the Q...
BarStyle barStyle() const
Returns current progree bar style.
double minimum() const
Returns minimum of the allowed value range.
void setDataColors(const QGradientStops &stopPoints)
Sets colors of the visible data and makes gradient brush from them.
void setOutlinePenWidth(double penWidth)
Sets width of the outline circle pen.
double nullPosition() const
Return position (in degrees) of minimum value.
QObject * parent() const const
@ StyleDonut
Donut style (filled torus around the text)
void setMinimum(double min)
Defines minimum of the allowed value range.
This file is part of the KDE documentation.
Documentation copyright © 1996-2022 The KDE developers.
Generated on Mon Aug 15 2022 04:04:04 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.