summaryrefslogtreecommitdiffstats
path: root/examples/datavisualization/qmllegend/doc/src/qmllegend.qdoc
blob: 03d03450ae69001f228359ce4f477a168b897c52 (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
/****************************************************************************
**
** Copyright (C) 2015 The Qt Company Ltd
** All rights reserved.
** For any questions to The Qt Company, please use contact form at http://qt.io
**
** This file is part of the Qt Data Visualization module.
**
** Licensees holding valid commercial license for Qt may use this file in
** accordance with the Qt License Agreement provided with the Software
** or, alternatively, in accordance with the terms contained in a written
** agreement between you and The Qt Company.
**
** If you have questions regarding the use of this file, please use
** contact form at http://qt.io
**
****************************************************************************/

/*!
    \example qmllegend
    \title Qt Quick 2 Legend Example
    \ingroup qtdatavisualization_examples
    \brief Showing graph legend in a QML application.

    The Qt Quick 2 legend example shows how to make an interactive legend for a graph.

    \image qmllegend-example.png

    The interesting thing about this example is displaying the legend. We'll concentrate on
    that and skip explaining the basic functionality - for
    more detailed QML example documentation, see \l{Qt Quick 2 Scatter Example}.

    \section1 Legend

    The legend is simply a column of custom \c LegendItem items inside a transparent rectangle.
    Each item is supplied with a series and the graph theme:

    \snippet qmllegend/qml/qmllegend/main.qml 0

    The legend items consist of a marker rectangle, which indicates the color of the series,
    and a text field, which shows the name of the series. The colors we get from the series and
    the theme supplied at legend item initialization:

    \snippet qmllegend/qml/qmllegend/LegendItem.qml 0
    \dots 4
    \snippet qmllegend/qml/qmllegend/LegendItem.qml 1

    We want the legend to be interactive, so we add additional logic to enable selection of a
    series by clicking on a legend item, as well as highlighting the legend item corresponding
    to the selected series.

    The highlight depends on the selection state of the series, so we define two states, which
    follow the Bar3DSeries::selectedBar property and adjust the \c legendItem color appropriately:

    \snippet qmllegend/qml/qmllegend/LegendItem.qml 3

    To make the legend item interactive, we define a MouseArea to detect clicks on it and adjust
    the series selection accordingly:

    \snippet qmllegend/qml/qmllegend/LegendItem.qml 2

    The \c previousSelection used above is another custom property of \c LegendItem, which we update
    whenever selection changes on the series. This way we remember the last selected bar of
    each series:

    \snippet qmllegend/qml/qmllegend/LegendItem.qml 4
*/