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

source code of qtgraphs/src/graphs3d/widget/q3dscatterwidgetitem.cpp