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 | |
33 | QT_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 | */ |
89 | Q3DScatter::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 | */ |
105 | Q3DScatter::~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 | */ |
114 | void Q3DScatter::addSeries(QScatter3DSeries *series) |
115 | { |
116 | dptr()->m_shared->addSeries(series); |
117 | } |
118 | |
119 | /*! |
120 | * Removes the \a series from the graph. |
121 | */ |
122 | void 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 | */ |
130 | QList<QScatter3DSeries *> Q3DScatter::seriesList() const |
131 | { |
132 | return dptrc()->m_shared->scatterSeriesList(); |
133 | } |
134 | |
135 | Q3DScatterPrivate *Q3DScatter::dptr() |
136 | { |
137 | return static_cast<Q3DScatterPrivate *>(d_ptr.data()); |
138 | } |
139 | |
140 | const 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 | */ |
162 | void Q3DScatter::setAxisX(QValue3DAxis *axis) |
163 | { |
164 | dptr()->m_shared->setAxisX(axis); |
165 | } |
166 | |
167 | QValue3DAxis *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 | */ |
189 | void Q3DScatter::setAxisY(QValue3DAxis *axis) |
190 | { |
191 | dptr()->m_shared->setAxisY(axis); |
192 | } |
193 | |
194 | QValue3DAxis *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 | */ |
216 | void Q3DScatter::setAxisZ(QValue3DAxis *axis) |
217 | { |
218 | dptr()->m_shared->setAxisZ(axis); |
219 | } |
220 | |
221 | /*! |
222 | * Returns the used z-axis. |
223 | */ |
224 | QValue3DAxis *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 | */ |
234 | QScatter3DSeries *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 | */ |
246 | void 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 | */ |
259 | void 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 | */ |
269 | QList<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 | |
279 | Q3DScatterPrivate::Q3DScatterPrivate(Q3DScatter *q) |
280 | : QAbstract3DGraphPrivate(q), |
281 | m_shared(0) |
282 | { |
283 | } |
284 | |
285 | Q3DScatterPrivate::~Q3DScatterPrivate() |
286 | { |
287 | } |
288 | |
289 | void Q3DScatterPrivate::handleAxisXChanged(QAbstract3DAxis *axis) |
290 | { |
291 | emit qptr()->axisXChanged(axis: static_cast<QValue3DAxis *>(axis)); |
292 | } |
293 | |
294 | void Q3DScatterPrivate::handleAxisYChanged(QAbstract3DAxis *axis) |
295 | { |
296 | emit qptr()->axisYChanged(axis: static_cast<QValue3DAxis *>(axis)); |
297 | } |
298 | |
299 | void Q3DScatterPrivate::handleAxisZChanged(QAbstract3DAxis *axis) |
300 | { |
301 | emit qptr()->axisZChanged(axis: static_cast<QValue3DAxis *>(axis)); |
302 | } |
303 | |
304 | Q3DScatter *Q3DScatterPrivate::qptr() |
305 | { |
306 | return static_cast<Q3DScatter *>(q_ptr); |
307 | } |
308 | |
309 | QT_END_NAMESPACE_DATAVISUALIZATION |
310 | |
311 | |