1// Copyright (C) 2016 The Qt Company Ltd.
2// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GPL-3.0-only
3
4#include "q3dbars_p.h"
5
6QT_BEGIN_NAMESPACE
7
8/*!
9 * \class Q3DBars
10 * \inmodule QtDataVisualization
11 * \brief The Q3DBars class provides methods for rendering 3D bar graphs.
12 * \since QtDataVisualization 1.0
13 *
14 * This class enables developers to render bar graphs in 3D and to view them by rotating the scene
15 * freely. Rotation is done by holding down the right mouse button and moving the mouse. Zooming
16 * is done by mouse wheel. Selection, if enabled, is done by left mouse button. The scene can be
17 * reset to default camera view by clicking mouse wheel. In touch devices rotation is done
18 * by tap-and-move, selection by tap-and-hold and zoom by pinch.
19 *
20 * If no axes are set explicitly to Q3DBars, temporary default axes with no labels are created.
21 * These default axes can be modified via axis accessors, but as soon any axis is set explicitly
22 * for the orientation, the default axis for that orientation is destroyed.
23 *
24 * Q3DBars supports more than one series visible at the same time. It is not necessary for all series
25 * to have the same amount of rows and columns.
26 * Row and column labels are taken from the first added series, unless explicitly defined to
27 * row and column axes.
28 *
29 * \section1 How to construct a minimal Q3DBars graph
30 *
31 * First, construct an instance of Q3DBars. 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_q3dbars_construction.cpp 4
36 *
37 * After constructing Q3DBars, you can set the data window by changing the range on the row and
38 * column axes. It is not mandatory, as data window will default to showing all of the data in
39 * the series. If the amount of data is large, it is usually preferable to show just a
40 * portion of it. For the example, let's set the data window to show first five rows and columns:
41 *
42 * \snippet doc_src_q3dbars_construction.cpp 0
43 *
44 * Now Q3DBars is ready to receive data to be rendered. Create a series with one row of 5 values:
45 *
46 * \snippet doc_src_q3dbars_construction.cpp 1
47 *
48 * \note We set the data window to 5 x 5, but we are adding only one row of data. This is ok,
49 * the rest of the rows will just be blank.
50 *
51 * Finally you will need to set it visible:
52 *
53 * \snippet doc_src_q3dbars_construction.cpp 2
54 *
55 * The complete code needed to create and display this graph is:
56 *
57 * \snippet doc_src_q3dbars_construction.cpp 3
58 *
59 * And this is what those few lines of code produce:
60 *
61 * \image q3dbars-minimal.png
62 *
63 * The scene can be rotated, zoomed into, and a bar can be selected to view its value,
64 * but no other interaction is included in this minimal code example. You can learn more by
65 * familiarizing yourself with the examples provided, like the \l{Bar Graph}.
66 *
67 * \sa Q3DScatter, Q3DSurface, {Qt Data Visualization C++ Classes}
68 */
69
70/*!
71 * Constructs a new 3D bar graph with optional \a parent window
72 * and surface \a format.
73 */
74Q3DBars::Q3DBars(const QSurfaceFormat *format, QWindow *parent)
75 : QAbstract3DGraph(new Q3DBarsPrivate(this), format, parent)
76{
77 if (!dptr()->m_initialized)
78 return;
79
80 dptr()->m_shared = new Bars3DController(geometry());
81 d_ptr->setVisualController(dptr()->m_shared);
82 dptr()->m_shared->initializeOpenGL();
83 QObject::connect(sender: dptr()->m_shared, signal: &Bars3DController::primarySeriesChanged,
84 context: this, slot: &Q3DBars::primarySeriesChanged);
85 QObject::connect(sender: dptr()->m_shared, signal: &Bars3DController::selectedSeriesChanged,
86 context: this, slot: &Q3DBars::selectedSeriesChanged);
87}
88
89/*!
90 * Destroys the 3D bar graph.
91 */
92Q3DBars::~Q3DBars()
93{
94}
95
96/*!
97 * \property Q3DBars::primarySeries
98 *
99 * \brief The primary series of the graph.
100 */
101
102/*!
103 * Sets \a series as the primary series of the graph. The primary series
104 * determines the row and column axis labels when the labels are not explicitly
105 * set to the axes.
106 *
107 * If the specified series is not yet added to the graph, setting it as the
108 * primary series will also implicitly add it to the graph.
109 *
110 * If the primary series itself is removed from the graph, this property
111 * resets to default.
112 *
113 * If \a series is null, this property resets to default.
114 * Defaults to the first added series or zero if no series are added to the graph.
115 */
116void Q3DBars::setPrimarySeries(QBar3DSeries *series)
117{
118 dptr()->m_shared->setPrimarySeries(series);
119}
120
121QBar3DSeries *Q3DBars::primarySeries() const
122{
123 return dptrc()->m_shared->primarySeries();
124}
125
126/*!
127 * Adds the \a series to the graph. A graph can contain multiple series, but only one set of axes,
128 * so the rows and columns of all series must match for the visualized data to be meaningful.
129 * If the graph has multiple visible series, only the primary series will
130 * generate the row or column labels on the axes in cases where the labels are not explicitly set
131 * to the axes. If the newly added series has specified a selected bar, it will be highlighted and
132 * any existing selection will be cleared. Only one added series can have an active selection.
133 *
134 * \sa seriesList(), primarySeries, QAbstract3DGraph::hasSeries()
135 */
136void Q3DBars::addSeries(QBar3DSeries *series)
137{
138 dptr()->m_shared->addSeries(series);
139}
140
141/*!
142 * Removes the \a series from the graph.
143 *
144 * \sa QAbstract3DGraph::hasSeries()
145 */
146void Q3DBars::removeSeries(QBar3DSeries *series)
147{
148 dptr()->m_shared->removeSeries(series);
149}
150
151/*!
152 * Inserts the \a series into the position \a index in the series list.
153 * If the \a series has already been added to the list, it is moved to the
154 * new \a index.
155 * \note When moving a series to a new \a index that is after its old index,
156 * the new position in list is calculated as if the series was still in its old
157 * index, so the final index is actually the \a index decremented by one.
158 *
159 * \sa addSeries(), seriesList(), QAbstract3DGraph::hasSeries()
160 */
161void Q3DBars::insertSeries(int index, QBar3DSeries *series)
162{
163 dptr()->m_shared->insertSeries(index, series);
164}
165
166/*!
167 * Returns the list of series added to this graph.
168 *
169 * \sa QAbstract3DGraph::hasSeries()
170 */
171QList<QBar3DSeries *> Q3DBars::seriesList() const
172{
173 return dptrc()->m_shared->barSeriesList();
174}
175
176/*!
177 * \property Q3DBars::multiSeriesUniform
178 *
179 * \brief Whether bars are to be scaled with proportions set to a single series
180 * bar even if there are multiple series displayed.
181 *
182 * If set to \c {true}, \l{barSpacing}{bar spacing} will be correctly applied
183 * only to the X-axis. Preset to \c false by default.
184 */
185void Q3DBars::setMultiSeriesUniform(bool uniform)
186{
187 if (uniform != isMultiSeriesUniform()) {
188 dptr()->m_shared->setMultiSeriesScaling(uniform);
189 emit multiSeriesUniformChanged(uniform);
190 }
191}
192
193bool Q3DBars::isMultiSeriesUniform() const
194{
195 return dptrc()->m_shared->multiSeriesScaling();
196}
197
198/*!
199 * \property Q3DBars::barThickness
200 *
201 * \brief The bar thickness ratio between the X and Z dimensions.
202 *
203 * The value \c 1.0 means that the bars are as wide as they are deep, whereas
204 *\c 0.5 makes them twice as deep as they are wide. Preset to \c 1.0 by default.
205 */
206void Q3DBars::setBarThickness(float thicknessRatio)
207{
208 if (thicknessRatio != barThickness()) {
209 dptr()->m_shared->setBarSpecs(thicknessRatio: GLfloat(thicknessRatio), spacing: barSpacing(),
210 relative: isBarSpacingRelative());
211 emit barThicknessChanged(thicknessRatio);
212 }
213}
214
215float Q3DBars::barThickness() const
216{
217 return dptrc()->m_shared->barThickness();
218}
219
220/*!
221 * \property Q3DBars::barSpacing
222 *
223 * \brief Bar spacing in the X and Z dimensions.
224 *
225 * Preset to \c {(1.0, 1.0)} by default. Spacing is affected by the
226 * barSpacingRelative property.
227 *
228 * \sa barSpacingRelative, multiSeriesUniform, barSeriesMargin
229 */
230void Q3DBars::setBarSpacing(const QSizeF &spacing)
231{
232 if (spacing != barSpacing()) {
233 dptr()->m_shared->setBarSpecs(thicknessRatio: GLfloat(barThickness()), spacing, relative: isBarSpacingRelative());
234 emit barSpacingChanged(spacing);
235 }
236}
237
238QSizeF Q3DBars::barSpacing() const
239{
240 return dptrc()->m_shared->barSpacing();
241}
242
243/*!
244 * \property Q3DBars::barSpacingRelative
245 *
246 * \brief Whether spacing is absolute or relative to bar thickness.
247 *
248 * If it is \c true, the value of \c 0.0 means that the bars are placed
249 * side-to-side, \c 1.0 means that a space as wide as the thickness of one bar
250 * is left between the bars, and so on. Preset to \c true.
251 */
252void Q3DBars::setBarSpacingRelative(bool relative)
253{
254 if (relative != isBarSpacingRelative()) {
255 dptr()->m_shared->setBarSpecs(thicknessRatio: GLfloat(barThickness()), spacing: barSpacing(), relative);
256 emit barSpacingRelativeChanged(relative);
257 }
258}
259
260bool Q3DBars::isBarSpacingRelative() const
261{
262 return dptrc()->m_shared->isBarSpecRelative();
263}
264
265/*!
266 * \property Q3DBars::barSeriesMargin
267 * \since 6.3
268 *
269 * \brief Margin between series columns in X and Z dimensions.
270 * Sensible values are on the range [0,1).
271 *
272 * Preset to \c {(0.0, 0.0)} by default. This property enables
273 * showing bars from different series side by side, but with space between columns.
274 *
275 * \sa barSpacing
276 */
277void Q3DBars::setBarSeriesMargin(const QSizeF &margin)
278{
279 if (margin != barSeriesMargin()) {
280 dptr()->m_shared->setBarSeriesMargin(margin);
281 emit barSeriesMarginChanged(margin);
282 }
283}
284
285QSizeF Q3DBars::barSeriesMargin() const
286{
287 return dptrc()->m_shared->barSeriesMargin();
288}
289
290/*!
291 * \property Q3DBars::rowAxis
292 *
293 * \brief The axis attached to the active row.
294 */
295
296/*!
297 * Sets the axis of the active row to \a axis. Implicitly calls addAxis() to
298 * transfer the ownership of the axis to this graph.
299 *
300 * If \a axis is null, a temporary default axis with no labels is created.
301 * This temporary axis is destroyed if another axis is set explicitly to the
302 * same orientation.
303 *
304 * \sa addAxis(), releaseAxis()
305 */
306void Q3DBars::setRowAxis(QCategory3DAxis *axis)
307{
308 dptr()->m_shared->setAxisZ(axis);
309}
310
311QCategory3DAxis *Q3DBars::rowAxis() const
312{
313 return static_cast<QCategory3DAxis *>(dptrc()->m_shared->axisZ());
314}
315
316/*!
317 * \property Q3DBars::columnAxis
318 *
319 * \brief The axis attached to the active column.
320 */
321
322/*!
323 * Sets the axis of the active column to \a axis. Implicitly calls addAxis() to
324 * transfer the ownership of the axis to this graph.
325 *
326 * If \a axis is null, a temporary default axis with no labels is created.
327 * This temporary axis is destroyed if another axis is set explicitly to the
328 * same orientation.
329 *
330 * \sa addAxis(), releaseAxis()
331 */
332void Q3DBars::setColumnAxis(QCategory3DAxis *axis)
333{
334 dptr()->m_shared->setAxisX(axis);
335}
336
337QCategory3DAxis *Q3DBars::columnAxis() const
338{
339 return static_cast<QCategory3DAxis *>(dptrc()->m_shared->axisX());
340}
341
342/*!
343 * \property Q3DBars::valueAxis
344 *
345 * Sets the active value axis (the Y-axis) to \a axis. Implicitly calls
346 * addAxis() to transfer the ownership of \a axis to this graph.
347 *
348 * If \a axis is null, a temporary default axis with no labels and
349 * an automatically adjusting range is created.
350 * This temporary axis is destroyed if another axis is set explicitly to the
351 * same orientation.
352 *
353 * \sa addAxis(), releaseAxis()
354 */
355void Q3DBars::setValueAxis(QValue3DAxis *axis)
356{
357 dptr()->m_shared->setAxisY(axis);
358}
359
360QValue3DAxis *Q3DBars::valueAxis() const
361{
362 return static_cast<QValue3DAxis *>(dptrc()->m_shared->axisY());
363}
364
365/*!
366 * \property Q3DBars::selectedSeries
367 *
368 * \brief The selected series or a null value.
369 *
370 * If selectionMode has the \c SelectionMultiSeries flag set, this
371 * property holds the series that owns the selected bar.
372 */
373QBar3DSeries *Q3DBars::selectedSeries() const
374{
375 return dptrc()->m_shared->selectedSeries();
376}
377
378/*!
379 * \property Q3DBars::floorLevel
380 *
381 * \brief The floor level for the bar graph in Y-axis data coordinates.
382 *
383 * The actual floor level will be restricted by the Y-axis minimum and maximum
384 * values.
385 * Defaults to zero.
386 */
387void Q3DBars::setFloorLevel(float level)
388{
389 if (level != floorLevel()) {
390 dptr()->m_shared->setFloorLevel(level);
391 emit floorLevelChanged(level);
392 }
393}
394
395float Q3DBars::floorLevel() const
396{
397 return dptrc()->m_shared->floorLevel();
398}
399
400/*!
401 * Adds \a axis to the graph. The axes added via addAxis are not yet taken to use,
402 * addAxis is simply used to give the ownership of the \a axis to the graph.
403 * The \a axis must not be null or added to another graph.
404 *
405 * \sa releaseAxis(), setValueAxis(), setRowAxis(), setColumnAxis()
406 */
407void Q3DBars::addAxis(QAbstract3DAxis *axis)
408{
409 dptr()->m_shared->addAxis(axis);
410}
411
412/*!
413 * Releases the ownership of the \a axis back to the caller, if it is added to this graph.
414 * If the released \a axis is in use, a new default axis will be created and set active.
415 *
416 * If the default axis is released and added back later, it behaves as any other axis would.
417 *
418 * \sa addAxis(), setValueAxis(), setRowAxis(), setColumnAxis()
419 */
420void Q3DBars::releaseAxis(QAbstract3DAxis *axis)
421{
422 dptr()->m_shared->releaseAxis(axis);
423}
424
425/*!
426 * Returns the list of all added axes.
427 *
428 * \sa addAxis()
429 */
430QList<QAbstract3DAxis *> Q3DBars::axes() const
431{
432 return dptrc()->m_shared->axes();
433}
434
435Q3DBarsPrivate *Q3DBars::dptr()
436{
437 return static_cast<Q3DBarsPrivate *>(d_ptr.data());
438}
439
440const Q3DBarsPrivate *Q3DBars::dptrc() const
441{
442 return static_cast<const Q3DBarsPrivate *>(d_ptr.data());
443}
444
445Q3DBarsPrivate::Q3DBarsPrivate(Q3DBars *q)
446 : QAbstract3DGraphPrivate(q),
447 m_shared(0)
448{
449}
450
451Q3DBarsPrivate::~Q3DBarsPrivate()
452{
453}
454
455void Q3DBarsPrivate::handleAxisXChanged(QAbstract3DAxis *axis)
456{
457 emit qptr()->columnAxisChanged(axis: static_cast<QCategory3DAxis *>(axis));
458}
459
460void Q3DBarsPrivate::handleAxisYChanged(QAbstract3DAxis *axis)
461{
462 emit qptr()->valueAxisChanged(axis: static_cast<QValue3DAxis *>(axis));
463}
464
465void Q3DBarsPrivate::handleAxisZChanged(QAbstract3DAxis *axis)
466{
467 emit qptr()->rowAxisChanged(axis: static_cast<QCategory3DAxis *>(axis));
468}
469
470Q3DBars *Q3DBarsPrivate::qptr()
471{
472 return static_cast<Q3DBars *>(q_ptr);
473}
474
475QT_END_NAMESPACE
476

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