1 | // Copyright (C) 2016 The Qt Company Ltd. |
2 | // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GPL-3.0-only |
3 | |
4 | #undef QT_NO_FOREACH // this file contains unported legacy Q_FOREACH uses |
5 | |
6 | #include "q3dscatter.h" |
7 | #include "q3dscatter_p.h" |
8 | |
9 | QT_BEGIN_NAMESPACE |
10 | |
11 | /*! |
12 | * \class Q3DScatter |
13 | * \inmodule QtDataVisualization |
14 | * \brief The Q3DScatter class provides methods for rendering 3D scatter graphs. |
15 | * \since QtDataVisualization 1.0 |
16 | * |
17 | * This class enables developers to render scatter graphs in 3D and to view them by rotating the scene |
18 | * freely. Rotation is done by holding down the right mouse button and moving the mouse. Zooming |
19 | * is done by mouse wheel. Selection, if enabled, is done by left mouse button. The scene can be |
20 | * reset to default camera view by clicking mouse wheel. In touch devices rotation is done |
21 | * by tap-and-move, selection by tap-and-hold and zoom by pinch. |
22 | * |
23 | * If no axes are set explicitly to Q3DScatter, temporary default axes with no labels are created. |
24 | * These default axes can be modified via axis accessors, but as soon any axis is set explicitly |
25 | * for the orientation, the default axis for that orientation is destroyed. |
26 | * |
27 | * Q3DScatter supports more than one series visible at the same time. |
28 | * |
29 | * \section1 How to construct a minimal Q3DScatter graph |
30 | * |
31 | * First, construct Q3DScatter. Since we are running the graph as top level window |
32 | * in this example, we need to clear the \c Qt::FramelessWindowHint flag, which gets set by |
33 | * default: |
34 | * |
35 | * \snippet doc_src_q3dscatter_construction.cpp 0 |
36 | * |
37 | * Now Q3DScatter is ready to receive data to be rendered. Add one series of 3 QVector3D items: |
38 | * |
39 | * \snippet doc_src_q3dscatter_construction.cpp 1 |
40 | * |
41 | * Finally you will need to set it visible: |
42 | * |
43 | * \snippet doc_src_q3dscatter_construction.cpp 2 |
44 | * |
45 | * The complete code needed to create and display this graph is: |
46 | * |
47 | * \snippet doc_src_q3dscatter_construction.cpp 3 |
48 | * |
49 | * And this is what those few lines of code produce: |
50 | * |
51 | * \image q3dscatter-minimal.png |
52 | * |
53 | * The scene can be rotated, zoomed into, and an item can be selected to view its position, |
54 | * but no other interaction is included in this minimal code example. |
55 | * You can learn more by familiarizing yourself with the examples provided, like |
56 | * the \l{Scatter Graph}. |
57 | * |
58 | * \sa Q3DBars, Q3DSurface, {Qt Data Visualization C++ Classes} |
59 | */ |
60 | |
61 | /*! |
62 | * Constructs a new 3D scatter graph with optional \a parent window |
63 | * and surface \a format. |
64 | */ |
65 | Q3DScatter::Q3DScatter(const QSurfaceFormat *format, QWindow *parent) |
66 | : QAbstract3DGraph(new Q3DScatterPrivate(this), format, parent) |
67 | { |
68 | if (!dptr()->m_initialized) |
69 | return; |
70 | |
71 | dptr()->m_shared = new Scatter3DController(geometry()); |
72 | d_ptr->setVisualController(dptr()->m_shared); |
73 | dptr()->m_shared->initializeOpenGL(); |
74 | QObject::connect(sender: dptr()->m_shared, signal: &Scatter3DController::selectedSeriesChanged, |
75 | context: this, slot: &Q3DScatter::selectedSeriesChanged); |
76 | } |
77 | |
78 | /*! |
79 | * Destroys the 3D scatter graph. |
80 | */ |
81 | Q3DScatter::~Q3DScatter() |
82 | { |
83 | } |
84 | |
85 | /*! |
86 | * Adds the \a series to the graph. A graph can contain multiple series, but has only one set of |
87 | * axes. If the newly added series has specified a selected item, it will be highlighted and |
88 | * any existing selection will be cleared. Only one added series can have an active selection. |
89 | * |
90 | * \sa QAbstract3DGraph::hasSeries() |
91 | */ |
92 | void Q3DScatter::addSeries(QScatter3DSeries *series) |
93 | { |
94 | dptr()->m_shared->addSeries(series); |
95 | } |
96 | |
97 | /*! |
98 | * Removes the \a series from the graph. |
99 | * |
100 | * \sa QAbstract3DGraph::hasSeries() |
101 | */ |
102 | void Q3DScatter::removeSeries(QScatter3DSeries *series) |
103 | { |
104 | dptr()->m_shared->removeSeries(series); |
105 | } |
106 | |
107 | /*! |
108 | * Returns the list of series added to this graph. |
109 | * |
110 | * \sa QAbstract3DGraph::hasSeries() |
111 | */ |
112 | QList<QScatter3DSeries *> Q3DScatter::seriesList() const |
113 | { |
114 | return dptrc()->m_shared->scatterSeriesList(); |
115 | } |
116 | |
117 | Q3DScatterPrivate *Q3DScatter::dptr() |
118 | { |
119 | return static_cast<Q3DScatterPrivate *>(d_ptr.data()); |
120 | } |
121 | |
122 | const Q3DScatterPrivate *Q3DScatter::dptrc() const |
123 | { |
124 | return static_cast<const Q3DScatterPrivate *>(d_ptr.data()); |
125 | } |
126 | |
127 | /*! |
128 | * \property Q3DScatter::axisX |
129 | * |
130 | * \brief The active x-axis. |
131 | */ |
132 | |
133 | /*! |
134 | * Sets \a axis as the active x-axis. Implicitly calls addAxis() to transfer the |
135 | * ownership of the axis to this graph. |
136 | * |
137 | * If \a axis is null, a temporary default axis with no labels and an automatically adjusting |
138 | * range is created. |
139 | * This temporary axis is destroyed if another axis is set explicitly to the |
140 | * same orientation. |
141 | * |
142 | * \sa addAxis(), releaseAxis() |
143 | */ |
144 | void Q3DScatter::setAxisX(QValue3DAxis *axis) |
145 | { |
146 | dptr()->m_shared->setAxisX(axis); |
147 | } |
148 | |
149 | QValue3DAxis *Q3DScatter::axisX() const |
150 | { |
151 | return static_cast<QValue3DAxis *>(dptrc()->m_shared->axisX()); |
152 | } |
153 | |
154 | /*! |
155 | * \property Q3DScatter::axisY |
156 | * |
157 | * \brief The active y-axis. |
158 | */ |
159 | |
160 | /*! |
161 | * Sets \a axis as the active y-axis. Implicitly calls addAxis() to transfer the |
162 | * ownership of the axis to this graph. |
163 | * |
164 | * If \a axis is null, a temporary default axis with no labels and an automatically adjusting |
165 | * range is created. |
166 | * This temporary axis is destroyed if another axis is set explicitly to the |
167 | * same orientation. |
168 | * |
169 | * \sa addAxis(), releaseAxis() |
170 | */ |
171 | void Q3DScatter::setAxisY(QValue3DAxis *axis) |
172 | { |
173 | dptr()->m_shared->setAxisY(axis); |
174 | } |
175 | |
176 | QValue3DAxis *Q3DScatter::axisY() const |
177 | { |
178 | return static_cast<QValue3DAxis *>(dptrc()->m_shared->axisY()); |
179 | } |
180 | |
181 | /*! |
182 | * \property Q3DScatter::axisZ |
183 | * |
184 | * \brief The active z-axis. |
185 | */ |
186 | |
187 | /*! |
188 | * Sets \a axis as the active z-axis. Implicitly calls addAxis() to transfer the |
189 | * ownership of the axis to this graph. |
190 | * |
191 | * If \a axis is null, a temporary default axis with no labels and an automatically adjusting |
192 | * range is created. |
193 | * This temporary axis is destroyed if another axis is set explicitly to the |
194 | * same orientation. |
195 | * |
196 | * \sa addAxis(), releaseAxis() |
197 | */ |
198 | void Q3DScatter::setAxisZ(QValue3DAxis *axis) |
199 | { |
200 | dptr()->m_shared->setAxisZ(axis); |
201 | } |
202 | |
203 | /*! |
204 | * Returns the used z-axis. |
205 | */ |
206 | QValue3DAxis *Q3DScatter::axisZ() const |
207 | { |
208 | return static_cast<QValue3DAxis *>(dptrc()->m_shared->axisZ()); |
209 | } |
210 | |
211 | /*! |
212 | * \property Q3DScatter::selectedSeries |
213 | * |
214 | * \brief The selected series or null. |
215 | */ |
216 | QScatter3DSeries *Q3DScatter::selectedSeries() const |
217 | { |
218 | return dptrc()->m_shared->selectedSeries(); |
219 | } |
220 | |
221 | /*! |
222 | * Adds \a axis to the graph. The axes added via addAxis are not yet taken to use, |
223 | * addAxis is simply used to give the ownership of the \a axis to the graph. |
224 | * The \a axis must not be null or added to another graph. |
225 | * |
226 | * \sa releaseAxis(), setAxisX(), setAxisY(), setAxisZ() |
227 | */ |
228 | void Q3DScatter::addAxis(QValue3DAxis *axis) |
229 | { |
230 | dptr()->m_shared->addAxis(axis); |
231 | } |
232 | |
233 | /*! |
234 | * Releases the ownership of the \a axis back to the caller, if it is added to this graph. |
235 | * If the released \a axis is in use, a new default axis will be created and set active. |
236 | * |
237 | * If the default axis is released and added back later, it behaves as any other axis would. |
238 | * |
239 | * \sa addAxis(), setAxisX(), setAxisY(), setAxisZ() |
240 | */ |
241 | void Q3DScatter::releaseAxis(QValue3DAxis *axis) |
242 | { |
243 | dptr()->m_shared->releaseAxis(axis); |
244 | } |
245 | |
246 | /*! |
247 | * Returns the list of all added axes. |
248 | * |
249 | * \sa addAxis() |
250 | */ |
251 | QList<QValue3DAxis *> Q3DScatter::axes() const |
252 | { |
253 | QList<QAbstract3DAxis *> abstractAxes = dptrc()->m_shared->axes(); |
254 | QList<QValue3DAxis *> retList; |
255 | foreach (QAbstract3DAxis *axis, abstractAxes) |
256 | retList.append(t: static_cast<QValue3DAxis *>(axis)); |
257 | |
258 | return retList; |
259 | } |
260 | |
261 | Q3DScatterPrivate::Q3DScatterPrivate(Q3DScatter *q) |
262 | : QAbstract3DGraphPrivate(q), |
263 | m_shared(0) |
264 | { |
265 | } |
266 | |
267 | Q3DScatterPrivate::~Q3DScatterPrivate() |
268 | { |
269 | } |
270 | |
271 | void Q3DScatterPrivate::handleAxisXChanged(QAbstract3DAxis *axis) |
272 | { |
273 | emit qptr()->axisXChanged(axis: static_cast<QValue3DAxis *>(axis)); |
274 | } |
275 | |
276 | void Q3DScatterPrivate::handleAxisYChanged(QAbstract3DAxis *axis) |
277 | { |
278 | emit qptr()->axisYChanged(axis: static_cast<QValue3DAxis *>(axis)); |
279 | } |
280 | |
281 | void Q3DScatterPrivate::handleAxisZChanged(QAbstract3DAxis *axis) |
282 | { |
283 | emit qptr()->axisZChanged(axis: static_cast<QValue3DAxis *>(axis)); |
284 | } |
285 | |
286 | Q3DScatter *Q3DScatterPrivate::qptr() |
287 | { |
288 | return static_cast<Q3DScatter *>(q_ptr); |
289 | } |
290 | |
291 | QT_END_NAMESPACE |
292 | |
293 | |