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 CHART_H
9#define CHART_H
10
11#include <QQuickItem>
12#include <qqmlregistration.h>
13
14#include "datasource/ChartDataSource.h"
15
16#include "quickcharts_export.h"
17
18/*!
19 * \qmltype Chart
20 * \inqmlmodule org.kde.quickcharts
21 *
22 * \brief Abstract base class for all charts.
23 */
24class QUICKCHARTS_EXPORT Chart : public QQuickItem
25{
26 Q_OBJECT
27 QML_ELEMENT
28 QML_UNCREATABLE("Base class")
29
30public:
31 using DataSourcesProperty = QQmlListProperty<ChartDataSource>;
32
33 /*!
34 * \enum Chart::IndexingMode
35 *
36 * How to index color and name sources relative to the different value sources.
37 *
38 * \value IndexSourceValues
39 * Index each value, restart indexing for each value source.
40 * \value IndexEachSource
41 * Index each value source, never index individual values.
42 * \value IndexAllValues
43 * Index each value, continuing with the index for each value source.
44 */
45 enum IndexingMode {
46 IndexSourceValues = 1,
47 IndexEachSource,
48 IndexAllValues
49 };
50 Q_ENUM(IndexingMode)
51
52 explicit Chart(QQuickItem *parent = nullptr);
53 ~Chart() override = default;
54
55 /*!
56 * \qmlproperty ChartDataSource Chart::nameSource
57 * \brief The data source to use for names of chart items.
58 */
59 Q_PROPERTY(ChartDataSource *nameSource READ nameSource WRITE setNameSource NOTIFY nameSourceChanged)
60 ChartDataSource *nameSource() const;
61 void setNameSource(ChartDataSource *nameSource);
62 Q_SIGNAL void nameSourceChanged();
63
64 /*!
65 * \qmlproperty ChartDataSource Chart::shortNameSource
66 * \brief The data source to use for short names of chart items.
67 */
68 Q_PROPERTY(ChartDataSource *shortNameSource READ shortNameSource WRITE setShortNameSource NOTIFY shortNameSourceChanged)
69 ChartDataSource *shortNameSource() const;
70 void setShortNameSource(ChartDataSource *shortNameSource);
71 Q_SIGNAL void shortNameSourceChanged();
72
73 /*!
74 * \qmlproperty ChartDataSource Chart::colorSource
75 * \brief The data source to use for colors of chart items.
76 */
77 Q_PROPERTY(ChartDataSource *colorSource READ colorSource WRITE setColorSource NOTIFY colorSourceChanged)
78 ChartDataSource *colorSource() const;
79 void setColorSource(ChartDataSource *colorSource);
80 Q_SIGNAL void colorSourceChanged();
81
82 /*!
83 * \qmlproperty list<ChartDataSource> Chart::valueSources
84 * \brief The data sources providing the data this chart needs to render.
85 */
86 Q_PROPERTY(QQmlListProperty<ChartDataSource> valueSources READ valueSourcesProperty NOTIFY valueSourcesChanged)
87 DataSourcesProperty valueSourcesProperty();
88 QList<ChartDataSource *> valueSources() const;
89 Q_SIGNAL void valueSourcesChanged();
90 Q_INVOKABLE void insertValueSource(int index, ChartDataSource *source);
91 Q_INVOKABLE void removeValueSource(int index);
92 Q_INVOKABLE void removeValueSource(QObject *source);
93
94 /*!
95 * \qmlproperty enumeration Chart::indexingMode
96 * \qmlenumeratorsfrom Chart::IndexingMode
97 * \brief The indexing mode used for indexing colors and names.
98 *
99 * The default value is \c{Chart.IndexEachSource}.
100 */
101 Q_PROPERTY(IndexingMode indexingMode READ indexingMode WRITE setIndexingMode NOTIFY indexingModeChanged)
102 IndexingMode indexingMode() const;
103 void setIndexingMode(IndexingMode newIndexingMode);
104 Q_SIGNAL void indexingModeChanged();
105
106 /*!
107 * \qmlproperty int Chart::highlight
108 * \brief The index of a value source to highlight.
109 *
110 * Highlighting is dependant on Chart type, but will generally mean that
111 * other value sources are rendered with lower opacity.
112 *
113 * By default, this is -1 which means nothing is highlighted.
114 */
115 Q_PROPERTY(int highlight READ highlight WRITE setHighlight NOTIFY highlightChanged RESET resetHighlight)
116 int highlight() const;
117 void setHighlight(int highlight);
118 void resetHighlight();
119 Q_SIGNAL void highlightChanged();
120
121 Q_SIGNAL void dataChanged();
122
123protected:
124 /*!
125 * \brief Called when the data of a value source changes.
126 *
127 * This method should be reimplemented by subclasses. It is called whenever
128 * the data of one of the value sources changes. Subclasses should use this
129 * to make sure that they update whatever internal state they use for
130 * rendering, then call update() to schedule rendering the item.
131 */
132 virtual void onDataChanged() = 0;
133
134 void componentComplete() override;
135
136 /*!
137 * \brief Desaturate and de-emphasise a color.
138 *
139 * Mainly intended as a standard for ensuring everything but the highlighted
140 * item is desaturated.
141 */
142 QColor desaturate(const QColor &input);
143
144private:
145 static void appendSource(DataSourcesProperty *list, ChartDataSource *source);
146 static qsizetype sourceCount(DataSourcesProperty *list);
147 static ChartDataSource *source(DataSourcesProperty *list, qsizetype index);
148 static void clearSources(DataSourcesProperty *list);
149 static void replaceSource(DataSourcesProperty *list, qsizetype index, ChartDataSource *source);
150 static void removeLastSource(DataSourcesProperty *list);
151
152 ChartDataSource *m_nameSource = nullptr;
153 ChartDataSource *m_shortNameSource = nullptr;
154 ChartDataSource *m_colorSource = nullptr;
155 QList<ChartDataSource *> m_valueSources;
156 IndexingMode m_indexingMode = IndexEachSource;
157 int m_highlight = -1;
158};
159
160#endif // CHART_H
161

source code of kquickcharts/src/Chart.h