| /**************************************************************************** |
| ** |
| ** Copyright (C) 2016 The Qt Company Ltd. |
| ** Contact: https://www.qt.io/licensing/ |
| ** |
| ** This file is part of the documentation of the Qt Toolkit. |
| ** |
| ** $QT_BEGIN_LICENSE:FDL$ |
| ** Commercial License Usage |
| ** Licensees holding valid commercial Qt licenses may use this file in |
| ** accordance with the commercial license agreement provided with the |
| ** Software or, alternatively, in accordance with the terms contained in |
| ** a written agreement between you and The Qt Company. For licensing terms |
| ** and conditions see https://www.qt.io/terms-conditions. For further |
| ** information use the contact form at https://www.qt.io/contact-us. |
| ** |
| ** GNU Free Documentation License Usage |
| ** Alternatively, this file may be used under the terms of the GNU Free |
| ** Documentation License version 1.3 as published by the Free Software |
| ** Foundation and appearing in the file included in the packaging of |
| ** this file. Please review the following information to ensure |
| ** the GNU Free Documentation License version 1.3 requirements |
| ** will be met: https://www.gnu.org/licenses/fdl-1.3.html. |
| ** $QT_END_LICENSE$ |
| ** |
| ****************************************************************************/ |
| |
| /*! |
| \example bars |
| \title Bars Example |
| \ingroup qtdatavisualization_examples |
| \brief Using Q3DBars in a widget application. |
| |
| The bars example shows how to make a 3D bar graph using Q3DBars and combining the use of |
| widgets for adjusting several adjustable qualities. The example shows how to: |
| |
| \list |
| \li Create an application with Q3DBars and some widgets |
| \li Use QBar3DSeries and QBarDataProxy to set data to the graph |
| \li Adjust some graph and series properties using widget controls |
| \li Select a row or a column by clicking an axis label |
| \endlist |
| |
| It also demonstrates how having negative bar values affects the graph. |
| |
| For instructions about how to interact with the graph, see \l{Qt Data Visualization Interacting with Data}{this page}. |
| |
| \image bars-example.png |
| |
| \include examples-run.qdocinc |
| |
| \section1 Creating the Application |
| |
| First, in main.cpp, we create a QApplication, instantiate Q3DBars and a window container |
| for it: |
| |
| \snippet bars/main.cpp 0 |
| |
| The call to QWidget::createWindowContainer is required, as all data visualization graph classes |
| (Q3DBars, Q3DScatter, Q3DSurface) inherit QWindow. Any class inheriting QWindow cannot be used |
| as a widget any other way. |
| |
| Then we'll create horizontal and vertical layouts. We'll add the graph and the vertical |
| layout into the horizontal one: |
| |
| \snippet bars/main.cpp 1 |
| |
| We're not using the vertical layout for anything yet, but we'll get back to it in |
| \l {Using widgets to control the graph} |
| |
| Next, let's create another class to handle the data addition and other interaction with the |
| graph. Let's call it \c GraphModifier (See \l {Setting up the graph} and |
| \l {Adding data to the graph} for details): |
| |
| \snippet bars/main.cpp 2 |
| |
| The application main is done and we can show the graph and start the event loop: |
| |
| \snippet bars/main.cpp 3 |
| |
| \section1 Setting up the Graph |
| |
| Let's set up the graph in the constructor of the \c GraphModifier class we instantiated in the |
| application main: |
| |
| \snippet bars/graphmodifier.cpp 0 |
| |
| Let's take a closer look at parts of the code. |
| |
| First we're creating the axes and the series into member variables to support changing them |
| easily later on, if we want to: |
| |
| \snippet bars/graphmodifier.cpp 1 |
| |
| Then we're setting some of the visual qualities for the graph: |
| |
| \snippet bars/graphmodifier.cpp 2 |
| |
| We're also setting up the axes and setting them to the graph as active axes: |
| |
| \snippet bars/graphmodifier.cpp 3 |
| |
| We give axis labels a small autorotation angle to make them orient somewhat toward the |
| camera. This is done to improve axis label readability at extreme camera angles. |
| |
| Next we initialize the visual properties of the series. |
| Note that the second series is initially not visible: |
| |
| \snippet bars/graphmodifier.cpp 8 |
| |
| The series need to be added to the graph to show them: |
| |
| \snippet bars/graphmodifier.cpp 4 |
| |
| Finally, we set the camera angle by calling the same method the camera angle change button |
| in the UI uses to cycle through various camera angles: |
| |
| \snippet bars/graphmodifier.cpp 6 |
| |
| There you can see that the camera is controlled via the scene object of the graph: |
| |
| \snippet bars/graphmodifier.cpp 10 |
| |
| For more information about using scene and cameras, see Q3DScene and Q3DCamera. |
| |
| That concludes setting up the graph. |
| |
| \section1 Adding Data to the Graph |
| |
| At the end of the constructor there's a call: |
| |
| \snippet bars/graphmodifier.cpp 9 |
| |
| This method is used to add data to the proxies of the two series: |
| |
| \snippet bars/graphmodifier.cpp 5 |
| |
| Now the series have data to show. |
| |
| \section1 Using Widgets to Control the Graph |
| |
| There isn't much interaction yet, so let's continue by adding some widgets back in the |
| application main. Let's just focus on two as an example: |
| |
| \snippet bars/main.cpp 4 |
| |
| We can use these slider widgets to rotate the graph instead of just using the mouse or |
| touch. |
| |
| Let's add them to the vertical layout we created earlier: |
| |
| \snippet bars/main.cpp 5 |
| |
| Then we'll connect them to methods in \c GraphModifier: |
| |
| \snippet bars/main.cpp 6 |
| |
| Here are the methods in \c GraphModifier the signals were connected to. The camera |
| is controlled via the scene object. This time we specify the actual camera position |
| along the orbit around the center point, instead of specifying a preset camera angle: |
| |
| \snippet bars/graphmodifier.cpp 7 |
| |
| Now these two sliders can be used to rotate the graph. |
| |
| And so we have an application in which we can control: |
| |
| \list |
| \li Graph rotation |
| \li Label style |
| \li Camera preset |
| \li Background visibility |
| \li Grid visibility |
| \li Bar shading smoothness |
| \li Visibility of the second bar series |
| \li Value axis direction |
| \li Axis title visibility and rotation |
| \li Data range to be shown |
| \li Bar style |
| \li Selection mode |
| \li Theme |
| \li Shadow quality |
| \li Font |
| \li Font size |
| \li Axis label rotation |
| \endlist |
| |
| \section1 Selecting a Row/column by Clicking an Axis Label |
| |
| Selection by axis label is default functionality for bar graphs. As an example, you can select |
| rows by clicking an axis label in the following way: |
| |
| \list |
| \li Change selection mode to \c SelectionRow |
| \li Click a year label |
| \li The row with the clicked year is selected |
| \endlist |
| |
| You can use the same method with \c SelectionSlice and \c SelectionItem flags, as long as |
| you have either \c SelectionRow or \c SelectionColumn set as well. |
| |
| \section1 Zooming to Selection |
| |
| As an example of adjusting camera target we have implemented an animation of zooming to |
| selection via a button press. Animation initializations are done in the constructor: |
| |
| \snippet bars/graphmodifier.cpp 12 |
| |
| The function \c{GraphModifier::zoomToSelectedBar()} contains the rest of the functionality: |
| |
| \snippet bars/graphmodifier.cpp 11 |
| |
| The QPropertyAnimation \c m_animationCameraTarget targets Q3DCamera::target property, |
| which takes a value normalized to the range (-1, 1). We figure out where the selected bar |
| is relative to axes, and use that as the end value for \c{m_animationCameraTarget}: |
| |
| \snippet bars/graphmodifier.cpp 13 |
| \dots |
| \snippet bars/graphmodifier.cpp 14 |
| |
| Likewise, we want to angle the camera so that it always points approximately to the center of |
| the graph at the end of the animation: |
| |
| \snippet bars/graphmodifier.cpp 15 |
| |
| \section1 Example Contents |
| |
| */ |