KQuickCharts

PieChart.h
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 * An item to render a pie chart.
18 *
19 * This item will render a Pie chart based on the [valueSources] supplied to it.
20 * By default it will set [indexingMode] to [IndexSourceValues], meaning that it
21 * will use the individual values of the valueSources to render sections of the
22 * chart.
23 *
24 * [valueSources]: \ref Chart::valueSources
25 * [indexingMode]: \ref Chart::indexingMode
26 * [IndexSourceValues]: \ref Chart::IndexingMode
27 *
28 * ### Usage example
29 *
30 * \snippet snippets/piechart.qml example
31 *
32 * \image html piechart.png "The resulting pie chart."
33 *
34 * ### 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 * [filled]: \ref PieChart::filled
44 * [thickness]: \ref PieChart::thickness
45 * [spacing]: \ref PieChart::spacing
46 *
47 */
48class QUICKCHARTS_EXPORT PieChart : public Chart
49{
50 Q_OBJECT
51 QML_ELEMENT
52
53public:
54 explicit PieChart(QQuickItem *parent = nullptr);
55
56 /**
57 * The range of values to display in this PieChart.
58 *
59 * When set to "automatic", the values will be divided across the entire
60 * chart.
61 *
62 * \sa RangeGroup
63 */
64 Q_PROPERTY(RangeGroup *range READ range CONSTANT)
65 RangeGroup *range() const;
66 /**
67 * Whether to use a filled pie or not.
68 *
69 * If true, the last pie rendered will be rendered as a filled circle.
70 * The default is false.
71 */
72 Q_PROPERTY(bool filled READ filled WRITE setFilled NOTIFY filledChanged)
73 bool filled() const;
74 void setFilled(bool newFilled);
75 Q_SIGNAL void filledChanged();
76 /**
77 * The thickness of an individual pie, in pixels.
78 *
79 * If filled is set, this is ignored for the last pie. The default is 10px.
80 */
81 Q_PROPERTY(qreal thickness READ thickness WRITE setThickness NOTIFY thicknessChanged)
82 qreal thickness() const;
83 void setThickness(qreal newThickness);
84 Q_SIGNAL void thicknessChanged();
85 /**
86 * The amount of spacing between pies when rendering multiple value sources.
87 *
88 * The default is 0.
89 */
90 Q_PROPERTY(qreal spacing READ spacing WRITE setSpacing NOTIFY spacingChanged)
91 qreal spacing() const;
92 void setSpacing(qreal newSpacing);
93 Q_SIGNAL void spacingChanged();
94 /**
95 * Sets a colour to use to fill remaining space on the pie.
96 *
97 * The default is transparent.
98 */
99 Q_PROPERTY(QColor backgroundColor READ backgroundColor WRITE setBackgroundColor NOTIFY backgroundColorChanged)
100 QColor backgroundColor() const;
101 void setBackgroundColor(const QColor &color);
102 Q_SIGNAL void backgroundColorChanged();
103 /**
104 * The starting angle of the arc used for the entire pie.
105 *
106 * When set, instead of rendering a full circle, the pie will be rendered as
107 * an arc. The default is 0.
108 */
109 Q_PROPERTY(qreal fromAngle READ fromAngle WRITE setFromAngle NOTIFY fromAngleChanged)
110 qreal fromAngle() const;
111 void setFromAngle(qreal newFromAngle);
112 Q_SIGNAL void fromAngleChanged();
113 /**
114 * The end angle of the arc used for the entire pie. When set, instead of
115 * rendering a full circle, the pie will be rendered as an arc. The default
116 * is 360.
117 */
118 Q_PROPERTY(qreal toAngle READ toAngle WRITE setToAngle NOTIFY toAngleChanged)
119 qreal toAngle() const;
120 void setToAngle(qreal newToAngle);
121 Q_SIGNAL void toAngleChanged();
122 /**
123 * Smooth the ends of pie sections.
124 *
125 * When true, this will try to smooth the ends of sections. This works best
126 * when [filled] is false. The default is false.
127 *
128 * [filled]: \ref PieChart::filled
129 */
130 Q_PROPERTY(bool smoothEnds READ smoothEnds WRITE setSmoothEnds NOTIFY smoothEndsChanged)
131 bool smoothEnds() const;
132 void setSmoothEnds(bool newSmoothEnds);
133 Q_SIGNAL void smoothEndsChanged();
134
135protected:
136 /**
137 * Reimplemented from QQuickItem.
138 */
139 QSGNode *updatePaintNode(QSGNode *node, UpdatePaintNodeData *data) override;
140 /**
141 * Reimplemented from Chart.
142 */
143 void onDataChanged() override;
144
145private:
146 std::unique_ptr<RangeGroup> m_range;
147 bool m_filled = false;
148 qreal m_thickness = 10.0;
149 qreal m_spacing = 0.0;
150 QColor m_backgroundColor = Qt::transparent;
151 qreal m_fromAngle = 0.0;
152 qreal m_toAngle = 360.0;
153 bool m_smoothEnds = false;
154
155 QList<QList<qreal>> m_sections;
156 QList<QList<QColor>> m_colors;
157};
158
159#endif // PIECHART_H
Abstract base class for all charts.
Definition Chart.h:22
virtual void onDataChanged()=0
Called when the data of a value source changes.
An item to render a pie chart.
Definition PieChart.h:49
An object that can be used as a grouped property to provide a value range for charts.
Definition RangeGroup.h:25
Q_PROPERTY(...)
virtual QSGNode * updatePaintNode(QSGNode *oldNode, UpdatePaintNodeData *updatePaintNodeData)
transparent
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Tue Mar 26 2024 11:13:57 by doxygen 1.10.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.