/****************************************************************************
**
** Copyright (C) 2016 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of the Qt Data Visualization module of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:GPL$
** 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 General Public License Usage
** Alternatively, this file may be used under the terms of the GNU
** General Public License version 3 or (at your option) any later version
** approved by the KDE Free Qt Foundation. The licenses are as published by
** the Free Software Foundation and appearing in the file LICENSE.GPL3
** included in the packaging of this file. Please review the following
** information to ensure the GNU General Public License requirements will
** be met: https://www.gnu.org/licenses/gpl-3.0.html.
**
** $QT_END_LICENSE$
**
****************************************************************************/

/*!
    \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}.

    \include examples-run.qdocinc

    \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
*/