/****************************************************************************
**
** 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 scatter
    \title Scatter Example
    \ingroup qtdatavisualization_examples
    \brief Using Q3DScatter in a widget application.

    The scatter example shows how to make a simple 3D scatter graph using Q3DScatter and
    combining the use of widgets for adjusting several adjustable qualities. The example shows
    how to:

    \list
        \li Create an application with Q3DScatter and some widgets
        \li Use QScatterDataProxy to set data to the graph
        \li Adjust some graph properties using widget controls
    \endlist

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

    \image scatter-example.png

    \include examples-run.qdocinc

    \section1 Creating the Application

    First, in main.cpp, we create a QApplication, instantiate Q3DScatter, and a window container
    for it:

    \snippet scatter/main.cpp 0

    The call to QWidget::createWindowContainer is required, as all data visualization graph classes
    (Q3DBars, Q3DScatter, and Q3DSurface) inherit QWindow. Any class inheriting QWindow cannot be used
    as a widget any other way.

    Then we'll create horizontal and vertical layouts. We'll add the graph and the vertical
    layout into the horizontal one:

    \snippet scatter/main.cpp 1

    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 \c ScatterDataModifier (See \l {Setting up the graph} and
    \l {Adding data to the graph} for details):

    \snippet scatter/main.cpp 2

    The application main is done. We can show the graph and start the event loop:

    \snippet scatter/main.cpp 3

    \section1 Setting up the Graph

    Let's set up some visual qualities for the graph in the constructor of the \c ScatterDataModifier
    class we instantiated in the application main:

    \snippet scatter/scatterdatamodifier.cpp 0

    None of these are required, but are used to override graph defaults. You can try how it looks
    with the preset defaults by commenting the block above out.

    Finally we create a QScatterDataProxy and the associated QScatter3DSeries. We set custom label format
    and mesh smoothing for the series and add it to the graph:

    \snippet scatter/scatterdatamodifier.cpp 2

    That concludes setting up the graph.

    \section1 Adding Data to the Graph

    The last thing we do in the \c ScatterDataModifier constructor is to add data to the graph:

    \snippet scatter/scatterdatamodifier.cpp 3

    The actual data addition is done in \c addData() method. First we configure the axes:

    \snippet scatter/scatterdatamodifier.cpp 4

    This could have been done in the constructor of \c {ScatterDataModifier}, but we added it here
    to keep the constructor simpler and the axes configuration near the data.

    Next we create a data array:

    \snippet scatter/scatterdatamodifier.cpp 5

    and populate it:

    \snippet scatter/scatterdatamodifier.cpp 6

    Finally we tell the proxy to start using the data we gave it:

    \snippet scatter/scatterdatamodifier.cpp 7

    Now our graph has the data and is ready to be used. There isn't much interaction yet, though,
    so let's continue by adding some widgets to play with.

    \section1 Using Widgets to Control the Graph

    First, back in the application main, we'll create some widgets:

    \snippet scatter/main.cpp 4

    And add them to the vertical layout we created earlier:

    \snippet scatter/main.cpp 5

    Now, let's connect them to methods in ScatterDataModifier:

    \snippet scatter/main.cpp 6

    Here are the methods in ScatterDataModifier the signals were connected to:

    \snippet scatter/scatterdatamodifier.cpp 8

    And so we have an application in which we can control:

    \list
        \li Label style
        \li Camera preset
        \li Background visibility
        \li Grid visibility
        \li Dot shading smoothness
        \li Dot style
        \li Theme
        \li Shadow quality
        \li Label font
    \endlist

    \section1 Example Contents
*/
