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

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