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 | */ |
44 | class QUICKCHARTS_EXPORT PieChart : public Chart |
45 | { |
46 | Q_OBJECT |
47 | QML_ELEMENT |
48 | |
49 | public: |
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 | |
157 | protected: |
158 | QSGNode *updatePaintNode(QSGNode *node, UpdatePaintNodeData *data) override; |
159 | void onDataChanged() override; |
160 | |
161 | private: |
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 | |