1/*
2 * This file is part of KQuickCharts
3 * SPDX-FileCopyrightText: 2019 Arjen Hiemstra <ahiemstra@heimr.nl>
4 *
5 * SPDX-License-Identifier: LGPL-2.1-only OR LGPL-3.0-only OR LicenseRef-KDE-Accepted-LGPL
6 */
7
8#ifndef PIECHART_H
9#define PIECHART_H
10
11#include <memory>
12
13#include "Chart.h"
14#include "RangeGroup.h"
15
16/*!
17 * \qmltype PieChart
18 * \inherits Chart
19 * \inqmlmodule org.kde.quickcharts
20 *
21 * \brief An item to render a pie chart.
22 *
23 * This item will render a Pie chart based on the valueSources supplied to it.
24 * By default it will set indexingMode to IndexSourceValues, meaning that it
25 * will use the individual values of the valueSources to render sections of the
26 * chart.
27 *
28 * \section1 Usage example
29 *
30 * \snippet piechart.qml example
31 *
32 * \image piechart.png The resulting pie chart.
33 *
34 * \section1 Multiple Value Sources
35 *
36 * Multiple valueSources are rendered as consecutive pie charts in the same
37 * item. The first valueSource will become the outermost circle and consecutive
38 * valueSources will be rendered as continuously smaller circles. When rendering
39 * multiple value sources, filled will only affect the last value source. All
40 * other value sources will be rendered according to thickness, with spacing
41 * amount of space between them.
42 *
43 */
44class QUICKCHARTS_EXPORT PieChart : public Chart
45{
46 Q_OBJECT
47 QML_ELEMENT
48
49public:
50 explicit PieChart(QQuickItem *parent = nullptr);
51 /*!
52 * \qmlproperty real PieChart::range.from
53 * \qmlproperty real PieChart::range.to
54 * \qmlproperty bool PieChart::range.automatic
55 * \qmlproperty real PieChart::range.distance
56 * \qmlproperty real PieChart::range.minimum
57 * \qmlproperty real PieChart::range.increment
58 *
59 * The range of values to display in this PieChart.
60 *
61 * from: The start of this range. The default is 0.
62 *
63 * to: The end of this range. The default is 100.
64 *
65 * automatic: Whether to determine the range based on values of a chart. If true (the default), from and to are ignored and instead calculated from the
66 * minimum and maximum values of a chart's valueSources.
67 *
68 * distance: The distance between from and to
69 *
70 * minimum: The minimum size of the range. This is mostly relevant when automatic is true. Setting this value will
71 * ensure that the range will never be smaller than this value. The default
72 * is std::numeric_limits<qreal>::min, which means minimum is disabled.
73 *
74 * increment: The amount with which the range increases. The total range will be limited to a multiple of this value. This is mostly useful when automatic
75 * is true. The default is 0.0, which means do not limit the range increment.
76 *
77 * When set to "automatic", the values will be divided across the entire
78 * chart.
79 */
80 Q_PROPERTY(RangeGroup *range READ range CONSTANT)
81 RangeGroup *range() const;
82 /*!
83 * \qmlproperty bool PieChart::filled
84 * \brief Whether to use a filled pie or not.
85 *
86 * If true, the last pie rendered will be rendered as a filled circle.
87 * The default is false.
88 */
89 Q_PROPERTY(bool filled READ filled WRITE setFilled NOTIFY filledChanged)
90 bool filled() const;
91 void setFilled(bool newFilled);
92 Q_SIGNAL void filledChanged();
93 /*!
94 * \qmlproperty real PieChart::thickness
95 * \brief The thickness of an individual pie, in pixels.
96 *
97 * If filled is set, this is ignored for the last pie. The default is 10px.
98 */
99 Q_PROPERTY(qreal thickness READ thickness WRITE setThickness NOTIFY thicknessChanged)
100 qreal thickness() const;
101 void setThickness(qreal newThickness);
102 Q_SIGNAL void thicknessChanged();
103 /*!
104 * \qmlproperty real PieChart::spacing
105 * \brief The amount of spacing between pies when rendering multiple value sources.
106 *
107 * The default is 0.
108 */
109 Q_PROPERTY(qreal spacing READ spacing WRITE setSpacing NOTIFY spacingChanged)
110 qreal spacing() const;
111 void setSpacing(qreal newSpacing);
112 Q_SIGNAL void spacingChanged();
113 /*!
114 * \qmlproperty color PieChart::backgroundColor
115 * \brief Sets a color to use to fill remaining space on the pie.
116 *
117 * The default is transparent.
118 */
119 Q_PROPERTY(QColor backgroundColor READ backgroundColor WRITE setBackgroundColor NOTIFY backgroundColorChanged)
120 QColor backgroundColor() const;
121 void setBackgroundColor(const QColor &color);
122 Q_SIGNAL void backgroundColorChanged();
123 /*!
124 * \qmlproperty real PieChart::fromAngle
125 * \brief The starting angle of the arc used for the entire pie.
126 *
127 * When set, instead of rendering a full circle, the pie will be rendered as
128 * an arc. The default is 0.
129 */
130 Q_PROPERTY(qreal fromAngle READ fromAngle WRITE setFromAngle NOTIFY fromAngleChanged)
131 qreal fromAngle() const;
132 void setFromAngle(qreal newFromAngle);
133 Q_SIGNAL void fromAngleChanged();
134 /*!
135 * \qmlproperty real PieChart::toAngle
136 * \brief The end angle of the arc used for the entire pie.
137 *
138 * When set, instead of rendering a full circle, the pie will be rendered as
139 * an arc. The default is 360.
140 */
141 Q_PROPERTY(qreal toAngle READ toAngle WRITE setToAngle NOTIFY toAngleChanged)
142 qreal toAngle() const;
143 void setToAngle(qreal newToAngle);
144 Q_SIGNAL void toAngleChanged();
145 /*!
146 * \qmlproperty bool PieChart::smoothEnds
147 * \brief Smooth the ends of pie sections.
148 *
149 * When true, this will try to smooth the ends of sections. This works best
150 * when filled is false. The default is false.
151 */
152 Q_PROPERTY(bool smoothEnds READ smoothEnds WRITE setSmoothEnds NOTIFY smoothEndsChanged)
153 bool smoothEnds() const;
154 void setSmoothEnds(bool newSmoothEnds);
155 Q_SIGNAL void smoothEndsChanged();
156
157protected:
158 QSGNode *updatePaintNode(QSGNode *node, UpdatePaintNodeData *data) override;
159 void onDataChanged() override;
160
161private:
162 std::unique_ptr<RangeGroup> m_range;
163 bool m_filled = false;
164 qreal m_thickness = 10.0;
165 qreal m_spacing = 0.0;
166 QColor m_backgroundColor = Qt::transparent;
167 qreal m_fromAngle = 0.0;
168 qreal m_toAngle = 360.0;
169 bool m_smoothEnds = false;
170
171 QList<QList<qreal>> m_sections;
172 QList<QList<QColor>> m_colors;
173};
174
175#endif // PIECHART_H
176

source code of kquickcharts/src/PieChart.h