summaryrefslogtreecommitdiffstats
path: root/examples/datavisualization/qmlscatter/doc/src/qmlscatter.qdoc
blob: 236238e1ee65067d73ccaa08553ca4ff7a72c50d (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
/****************************************************************************
**
** 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 qmlscatter
    \title Qt Quick 2 Scatter Example
    \ingroup qtdatavisualization_examples
    \brief Using Scatter3D in a QML application.

    The Qt Quick 2 scatter example shows how to make a simple scatter graph visualization using
    Scatter3D and Qt Quick 2.

    For instructions about how to interact with the graph, see \l{Qt Data Visualization Interacting with Data}{this page}.

    \image qmlscatter-example.png

    \section1 Creating the application

    The application main is created by creating a new Qt Quick Application project in QtCreator.
    The dialog shown here is from QtCreator 3.0.0, and it may look a bit different in other
    versions:

    \image qmlscatter-newproject.png

    We'll modify the generated \c main.cpp a bit, as we want to add our \c main.qml file as a
    resource. We do it by replacing

    \code viewer.setMainQmlFile(QStringLiteral("qml/qmlscatter/main.qml")); \endcode

    with

    \snippet qmlscatter/main.cpp 0

    This will make application deployment easier.

    We'll enable anti-aliasing for our application in environments that support it:

    \snippet qmlscatter/main.cpp 2

    We'll also change the application to be shown maximized by replacing

    \code viewer.showExpanded(); \endcode

    with

    \snippet qmlscatter/main.cpp 1

    We won't look into that any closer, as we'll change nothing in the generated
    \c qtquick2applicationviewer files.

    Next we'll create new qml files for data (\c Data.qml) and a QtQuick.Controls button
    we want to modify a bit (\c NewButton.qml), and add them to the resource file, in addition to
    main.qml:

    \code
    <RCC>
        <qresource prefix="/">
            <file>qml/qmlscatter/Data.qml</file>
            <file>qml/qmlscatter/main.qml</file>
            <file>qml/qmlscatter/NewButton.qml</file>
        </qresource>
    </RCC>
    \endcode

    Now the base for our application is done, and we can start setting up the graph.

    \section1 Setting up the graph

    Let's start modifying the generated \c {main.qml}. We can remove all previous content from it,
    as it has nothing we need.

    First we'll import all the QML modules we need:

    \snippet qmlscatter/qml/qmlscatter/main.qml 0

    The last \c import just imports all the qml files in the same directory as our \c {main.qml},
    because that's where \c NewButton.qml and \c Data.qml are.

    Then we create our main \c Item and call it \c mainView:

    \snippet qmlscatter/qml/qmlscatter/main.qml 1

    \note The Qt Creator application wizard will set a \c Rectangle item as the main item, which
    is opaque white by default. This doesn't work for us, because the graphs are rendered behind the other
    QML elements. We change the main item type to \c Item, which is invisible. This way the graph is
    not covered by the main item.

    Then we'll add another \c Item inside it, and call it \c dataView. This will be the item to hold
    the Scatter3D graph. We'll anchor it to the parent bottom:

    \snippet qmlscatter/qml/qmlscatter/main.qml 9

    Next we're ready to add the Scatter3D graph itself. We'll add it inside the \c dataView and
    name it \c {scatterGraph}. Let's make it fill the \c {dataView}:

    \snippet qmlscatter/qml/qmlscatter/main.qml 2

    Now the graph is ready for use, but has no data. It also has the default axes and visual
    properties.

    Let's modify some visual properties first by adding the following inside \c {scatterGraph}:

    \snippet qmlscatter/qml/qmlscatter/main.qml 3

    We added a customized theme and changed the shadow quality.
    We're happy with the other visual properties, so we won't change them.

    The custom theme is based on a predefined theme, but we change the font in it:

    \snippet qmlscatter/qml/qmlscatter/main.qml 13

    Then it's time to start feeding the graph some data.

    \section1 Adding data to the graph

    Let's create a \c Data item inside the \c mainView and name it \c seriesData:

    \snippet qmlscatter/qml/qmlscatter/main.qml 4

    The \c seriesData item contains the data models for all three series we use in this example.

    This is the component that holds our data in \c {Data.qml}. It has an \c Item as the main
    component.

    In the main component we'll add the data itself in a \c ListModel and name it
    \c {dataModel}:

    \snippet qmlscatter/qml/qmlscatter/Data.qml 0
    \dots

    We'll add two more of these for the other two series, and name them \c dataModelTwo and
    \c {dataModelThree}.

    Then we need to expose the data models to be usable from \c {main.qml}. We do this by defining
    them as aliases in the main data component:

    \snippet qmlscatter/qml/qmlscatter/Data.qml 1

    Now we can use the data from \c Data.qml with \c scatterGraph in \c {main.qml}. First we'll add
    a Scatter3DSeries and call it \c {scatterSeries}:

    \snippet qmlscatter/qml/qmlscatter/main.qml 5

    Then we'll set up selection label format for the series:

    \snippet qmlscatter/qml/qmlscatter/main.qml 10

    And finally the data for series one in a ItemModelScatterDataProxy. We set the data itself as
    \c itemModel for the proxy:

    \snippet qmlscatter/qml/qmlscatter/main.qml 11

    We'll add the other two series in the same way, but modify some series-specific details a bit:

    \snippet qmlscatter/qml/qmlscatter/main.qml 12
    \dots

    Then we'll modify the properties of the default axes in \c scatterGraph a bit:

    \snippet qmlscatter/qml/qmlscatter/main.qml 6

    After that we'll just add a few buttons to the \c mainView to control the graph. We'll only
    show one as an example:

    \snippet qmlscatter/qml/qmlscatter/main.qml 7

    Then we'll modify \c dataView to make room for the buttons at the top:

    \snippet qmlscatter/qml/qmlscatter/main.qml 8
    \dots

    And we're done!

    \section1 Example contents
*/