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

source code of qtdatavis3d/src/datavisualization/engine/q3dscatter.cpp