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
9QT_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 */
65Q3DScatter::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 */
81Q3DScatter::~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 */
92void 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 */
102void 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 */
112QList<QScatter3DSeries *> Q3DScatter::seriesList() const
113{
114 return dptrc()->m_shared->scatterSeriesList();
115}
116
117Q3DScatterPrivate *Q3DScatter::dptr()
118{
119 return static_cast<Q3DScatterPrivate *>(d_ptr.data());
120}
121
122const 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 */
144void Q3DScatter::setAxisX(QValue3DAxis *axis)
145{
146 dptr()->m_shared->setAxisX(axis);
147}
148
149QValue3DAxis *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 */
171void Q3DScatter::setAxisY(QValue3DAxis *axis)
172{
173 dptr()->m_shared->setAxisY(axis);
174}
175
176QValue3DAxis *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 */
198void Q3DScatter::setAxisZ(QValue3DAxis *axis)
199{
200 dptr()->m_shared->setAxisZ(axis);
201}
202
203/*!
204 * Returns the used z-axis.
205 */
206QValue3DAxis *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 */
216QScatter3DSeries *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 */
228void 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 */
241void 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 */
251QList<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
261Q3DScatterPrivate::Q3DScatterPrivate(Q3DScatter *q)
262 : QAbstract3DGraphPrivate(q),
263 m_shared(0)
264{
265}
266
267Q3DScatterPrivate::~Q3DScatterPrivate()
268{
269}
270
271void Q3DScatterPrivate::handleAxisXChanged(QAbstract3DAxis *axis)
272{
273 emit qptr()->axisXChanged(axis: static_cast<QValue3DAxis *>(axis));
274}
275
276void Q3DScatterPrivate::handleAxisYChanged(QAbstract3DAxis *axis)
277{
278 emit qptr()->axisYChanged(axis: static_cast<QValue3DAxis *>(axis));
279}
280
281void Q3DScatterPrivate::handleAxisZChanged(QAbstract3DAxis *axis)
282{
283 emit qptr()->axisZChanged(axis: static_cast<QValue3DAxis *>(axis));
284}
285
286Q3DScatter *Q3DScatterPrivate::qptr()
287{
288 return static_cast<Q3DScatter *>(q_ptr);
289}
290
291QT_END_NAMESPACE
292
293

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