diff options
Diffstat (limited to 'examples/bars/doc/src/bars.qdoc')
| -rw-r--r-- | examples/bars/doc/src/bars.qdoc | 171 |
1 files changed, 74 insertions, 97 deletions
diff --git a/examples/bars/doc/src/bars.qdoc b/examples/bars/doc/src/bars.qdoc index a8de709b..379aa871 100644 --- a/examples/bars/doc/src/bars.qdoc +++ b/examples/bars/doc/src/bars.qdoc @@ -20,22 +20,25 @@ \example bars \title Bars Example \ingroup qtdatavisualization_examples - \brief Using an item model as data source for Q3DBars. + \brief Using Q3DBars in a widget application. - The bars 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: + 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 How to create an application with Q3DBars and widgets - \li How to use QItemModelBarDataMapping and QItemModelBarDataProxy to set data to the graph - \li How to use a table widget to modify the data in the graph + \li Create an application with Q3DBars and some widgets + \li Use QBarDataProxy to set data to the graph + \li Adjust some graph properties using widget controls \endlist - \image bars-example-2.png + It also demonstrates how having negative bar values affects the graph. + + \image bars-example.png \section1 Creating the application - First, in main.cpp, we create a QApplication, instantiate Q3DBars and a window container for it: + First, in main.cpp, we create a QApplication, instantiate Q3DBars and a window container + for it: \snippet ../examples/bars/main.cpp 0 @@ -43,140 +46,114 @@ (Q3DBars, Q3DScatter, 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: + Then we'll create horizontal and vertical layouts. We'll add the graph and the vertical + layout into the horizontal one: \snippet ../examples/bars/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 QItemModelBarDataMapping and QItemModelBarDataProxy and give them to the - graph: - - \snippet ../examples/bars/main.cpp 2 - - Here we tell the mapping object to directly map model's rows and columns into 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 and the mapping object to the proxy. Finally we set the proxy as the active - data proxy for the graph. + 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 GraphDataGenerator (See \l {Setting up the graph} and - \l {Adding data to the graph} for details) and connect some signals between Q3DBars, - GraphDataGenerator and QTableWidget (See \l {Interacting with the data} for a closer look): + graph. Let's call it GraphModifier (See \l {Setting up the graph} and + \l {Adding data to the graph} for details): - \snippet ../examples/bars/main.cpp 3 + \snippet ../examples/bars/main.cpp 2 The application main is done and we can show the graph and start the event loop: - \snippet ../examples/bars/main.cpp 4 + \snippet ../examples/bars/main.cpp 3 \section1 Setting up the graph - Let's set up the visual attributes for the graph in the constructor of GraphDataGenerator: + Let's set up the graph in the constructor of the GraphModifier class we instantiated in the + application main: - \snippet ../examples/bars/main.cpp 5 - \snippet ../examples/bars/main.cpp 6 - \snippet ../examples/bars/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. + \snippet ../examples/bars/graphmodifier.cpp 0 - Then, we set the bar type to flat pyramids, overriding the default bar type. - We want to be able to select rows of data for a closer inspection, so we set the selection mode - to slice row. This means that whenever we select a bar in the graph, the whole row will be - displayed separately. + Let's take a closer look at parts of the code. - Next line sets the font to \c Impact. If your system doesn't have it, it will be replaced by - system default. + First we're creating the axes and the proxy into member variables to support changing them + easily later on, if we want to: - And finally, we set theme to \c Digia and camera position to \c {Preset Front}. Now the initial - graph settings are done. + \snippet ../examples/bars/graphmodifier.cpp 1 - \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. + Then we're setting some of the visual qualities for the graph: - \section1 Adding data to the graph + \snippet ../examples/bars/graphmodifier.cpp 2 - We created the data generator in the application main and gave it the graph and the table - widget as parameters: + We're also setting up the axes and adding them to the graph. Notice that we're not setting them + active yet: - \code GraphDataGenerator generator(graph, tableWidget); \endcode + \snippet ../examples/bars/graphmodifier.cpp 3 - 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: + And add the proxy. Note that we're not setting it active yet, but just adding it: - \code generator.start(); \endcode + \snippet ../examples/bars/graphmodifier.cpp 4 - Let's have a look at the contents of the \c start() method: + That concludes setting up the graph. - \snippet ../examples/bars/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 whole data timer implementation is not vital for the - application, so we won't take a closer look at it. It's just there to make the table look better. - - In \c setupModel() we first introduce the row and column labels, and the actual data: + \section1 Adding data to the graph - \snippet ../examples/bars/main.cpp 9 + At the end of the constructor there's a call: - Then we set up the axes: + \code resetTemperatureData(); \endcode - \snippet ../examples/bars/main.cpp 10 + The method is used to add data to the proxy: - The other lines there are pretty self-explanatory except for the one with the segment count. - We're setting it to five as we want the value axis (the Y-axis) to show more values than just - the lowest and the highest. + \snippet ../examples/bars/graphmodifier.cpp 5 - Next we will set up the table widget: + Now the data is in the proxy, but not in the graph. We have not set the proxy active yet. - \snippet ../examples/bars/main.cpp 11 + In application main, we called \c {modifier->start()} after constructing all the necessary + objects. This is what is done in it: - After that all that's left is adding the data to the table widget: + \snippet ../examples/bars/graphmodifier.cpp 6 - \snippet ../examples/bars/main.cpp 12 + Finally we set the proxy and the axes active. Now our graph has the data and is ready to be + used. - Now we have a bar graph and a table widget, both displaying the same data. + \section1 Using widgets to control the graph - 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: + 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: - \snippet ../examples/bars/main.cpp 2 - - We created QItemModelBarDataMapping and QItemModelBarDataProxy instances, and gave the proxy - the model of the table widget and the model mapping we just created. Then we set the proxy as - the active proxy for the graph. The proxy maps the rows and the columns in the model of the table - widget into rows and columns for itself using the model mapping, and the graph gets the data - to be displayed from its active proxy. + \snippet ../examples/bars/main.cpp 4 - \section1 Interacting with the data + We can use these to rotate the graph using slider widgets instead of just using the mouse or + touch. - We made a couple of signal connections in the application main earlier: + Let's add them to the vertical layout we created earlier: - \snippet ../examples/bars/main.cpp 3 + \snippet ../examples/bars/main.cpp 5 - Now we'll find out what these were for. + Then we'll connect them to methods in GraphModifier: - The first one connects a signal from Q3DBars to the GraphDataGenerator. Signal - Q3DBars::selectedBarPosChanged() is emitted when a bar is selected from the graph. We connect - that to a method in the data generator that selects the same data item in the table widget: + \snippet ../examples/bars/main.cpp 6 - \snippet ../examples/bars/main.cpp 13 + Here are the methods in GraphModifier the signals were connected to: - 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 graph: + \snippet ../examples/bars/graphmodifier.cpp 7 - \snippet ../examples/bars/main.cpp 14 + Now these two sliders can be used to rotate the graph. - 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 active proxy with mapping between the data - in the table widget and itself. + And so we have an application in which we can control: - \image bars-example.png + \list + \li Graph rotation + \li Label style + \li Camera preset + \li Background visibility + \li Grid visibility + \li Bar shading smoothness + \li Bar style + \li Selection mode + \li Theme + \li Shadow quality + \li Font + \li Font size + \endlist \section1 Example contents + */ |