summaryrefslogtreecommitdiffstats
path: root/examples/datavisualization/itemmodel/doc/src/itemmodel.qdoc
diff options
context:
space:
mode:
Diffstat (limited to 'examples/datavisualization/itemmodel/doc/src/itemmodel.qdoc')
-rw-r--r--examples/datavisualization/itemmodel/doc/src/itemmodel.qdoc181
1 files changed, 181 insertions, 0 deletions
diff --git a/examples/datavisualization/itemmodel/doc/src/itemmodel.qdoc b/examples/datavisualization/itemmodel/doc/src/itemmodel.qdoc
new file mode 100644
index 00000000..16cd1974
--- /dev/null
+++ b/examples/datavisualization/itemmodel/doc/src/itemmodel.qdoc
@@ -0,0 +1,181 @@
+/****************************************************************************
+**
+** Copyright (C) 2014 Digia Plc
+** All rights reserved.
+** For any questions to Digia, please use contact form at http://qt.digia.com
+**
+** This file is part of the QtDataVisualization module.
+**
+** Licensees holding valid Qt Enterprise licenses may use this file in
+** accordance with the Qt Enterprise License Agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and Digia.
+**
+** If you have questions regarding the use of this file, please use
+** contact form at http://qt.digia.com
+**
+****************************************************************************/
+
+/*!
+ \example itemmodel
+ \title Item Model Example
+ \ingroup qtdatavisualization_examples
+ \brief Using an item model as data source for Q3DBars.
+
+ The item model example shows how to make a simple 3D bar graph using Q3DBars and how to modify
+ the data being drawn at run-time. The example shows how to:
+
+ \list
+ \li Create an application with Q3DBars and widgets
+ \li Use QItemModelBarDataProxy to set data to the graph
+ \li Use a table widget to modify the data in the graph
+ \endlist
+
+ For instructions about how to interact with the graph, see \l{Qt Data Visualization Interacting with Data}{this page}.
+
+ \image itemmodel-example-2.png
+
+ \section1 Creating the application
+
+ First, in main.cpp, we create a QApplication, instantiate Q3DBars and a window container for it:
+
+ \snippet ../examples/itemmodel/main.cpp 0
+
+ The call to QWidget::createWindowContainer is required, as all data visualization types
+ (Q3DBars, Q3DScatter, and Q3DSurface) inherit QWindow. Any class inheriting QWindow cannot be used
+ as a widget any other way.
+
+ Then we'll create a layout and add the graph and the table widget into it:
+
+ \snippet ../examples/itemmodel/main.cpp 1
+
+ The table widget is going to be used to display the numerical data being inserted into the
+ graph, and to modify it (See \l {Adding data to the graph} and \l {Interacting with the data}).
+
+ We need to instantiate QItemModelBarDataProxy and a QBar3DSeries for it, and give the series
+ to the graph:
+
+ \snippet ../examples/itemmodel/main.cpp 2
+
+ Here we tell the proxy to directly map the model's rows and columns into the proxy's rows and
+ columns instead of defining row and column roles to map for them. Then we give the model from
+ the table widget to the proxy. We also create a series instance and set the proxy to it.
+ We customize the series visuals a bit by changing the object mesh to pyramids, and finally
+ add the series to the graph.
+
+ Next, let's create another class to handle the data addition and other interaction with the
+ graph. Let's call it \c GraphDataGenerator (See \l {Setting up the graph} and
+ \l {Adding data to the graph} for details) and connect some signals between QBar3DSeries,
+ \c GraphDataGenerator, and QTableWidget (See \l {Interacting with the data} for a closer look):
+
+ \snippet ../examples/itemmodel/main.cpp 3
+
+ The application main is done and we can show the graph and start the event loop:
+
+ \snippet ../examples/itemmodel/main.cpp 4
+
+ \section1 Setting up the graph
+
+ Let's set up the visual attributes for the graph in the constructor of \c GraphDataGenerator:
+
+ \snippet ../examples/itemmodel/main.cpp 5
+ \snippet ../examples/itemmodel/main.cpp 6
+ \snippet ../examples/itemmodel/main.cpp 7
+
+ First we set bar thickness ratio to 1.0, which means bars will be as wide as they are deep. 1.0
+ is also the default value, so the line is basically unnecessary. It's left there so you could
+ easily try how changing it affects the graph. The second line sets bar spacings to 0.2, which
+ means there will be a gap of 20% of the bar's thickness between the bars in both directions.
+
+ We want to be able to select rows of data for a closer inspection, so we set the selection mode
+ to slice item and row. This means that whenever we select a bar in the graph, the whole row will be
+ displayed separately and the selected bar will be highlighted.
+
+ We don't want to use the default colors, so we set one of the predefined themes as the active theme.
+
+ Next line sets the font to \c Impact. If your system doesn't have it, it will be replaced by
+ the system default.
+
+ And finally, we set the camera position to one of the predefined camera positions.
+ Now the initial graph settings are done.
+
+ \note You do not need to set any of these in case you're happy with the defaults. You can
+ easily try them by commenting out the contents of the constructor.
+
+ \section1 Adding data to the graph
+
+ We created the data generator in the application main and gave it the graph and the table
+ widget as parameters:
+
+ \code GraphDataGenerator generator(graph, tableWidget); \endcode
+
+ We added a separate start method to the generator, so that it wouldn't start doing anything
+ until everything else is set up. We then called the method when starting the application:
+
+ \code generator.start(); \endcode
+
+ Let's have a look at the contents of the \c start() method:
+
+ \snippet ../examples/itemmodel/main.cpp 8
+
+ The main thing \c start() does is set up the data model. It also activates a timer for getting
+ the accurate dimensions of the table widget after it's been filled with data. The reason we
+ do this is that the widget doesn't know its final visual domensions until all the data has been
+ inserted to it and it has been shown. The data timer usage is not vital for the
+ application, so we won't take a closer look at it. It's just there to make QTableWidget look better.
+
+ In \c setupModel() we first introduce the row and column labels, and the actual data:
+
+ \snippet ../examples/itemmodel/main.cpp 9
+
+ Then we set up the axes:
+
+ \snippet ../examples/itemmodel/main.cpp 10
+
+ Next we will set up the table widget:
+
+ \snippet ../examples/itemmodel/main.cpp 11
+
+ After that all that's left is adding the data to the table widget:
+
+ \snippet ../examples/itemmodel/main.cpp 12
+
+ Now we have a bar graph and a table widget, both displaying the same data.
+
+ You're probably wondering how the data can be displayed in the graph, as the only thing we did
+ was add it to the table widget? That's because of what we did earlier, in the application main:
+
+ \snippet ../examples/itemmodel/main.cpp 2
+
+ We created QItemModelBarDataProxy instance, and gave the proxy the model of the table widget
+ we just created. The proxy maps the rows and the columns in the model of the table widget into
+ rows and columns for itself directly, as we set the QItemModelBarDataProxy::useModelCategories
+ property to true, and the graph gets the data to be displayed via the series that owns the proxy.
+
+ \section1 Interacting with the data
+
+ We made a couple of signal connections in the application main earlier:
+
+ \snippet ../examples/itemmodel/main.cpp 3
+
+ Now we'll find out what these were for.
+
+ The first one connects a signal from Q3DBars to the \c GraphDataGenerator. Signal
+ QBar3DSeries::selectedBarChanged() is emitted when a bar is selected from the series. We connect
+ that to a method in the data generator that selects the same data item in the table widget:
+
+ \snippet ../examples/itemmodel/main.cpp 13
+
+ The second connection does the opposite; it connects a signal from the table widget to a
+ method in the data generator. The method then selects the corresponding bar in the series:
+
+ \snippet ../examples/itemmodel/main.cpp 14
+
+ You can even select an item in the widget and change the value of it, and the new value is
+ updated to the graph. This is handled again by the proxy with mapping between the data
+ in the table widget and itself.
+
+ \image itemmodel-example.png
+
+ \section1 Example contents
+*/