// Copyright (C) 2024 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only

/*!
    \page qtgraphs_migration_guide_2d.html
    \title Qt Graphs Migration from Qt Charts

    The API and functionality between Qt Charts and Qt Graphs is slightly
    different. This article explains the differences between the API of both
    Qt Charts to Qt Graphs:

    \section1 QML Import Statement

    The import statement in Qt Charts:
    \code
    import QtCharts
    \endcode
    has to be changed to:
    \code
    import QtGraphs
    \endcode
    for Qt Graphs.

    \section1 CMake Module Inclusion

    The inclusion in Qt Charts:
    \code
    find_package(Qt6 REQUIRED COMPONENTS Charts)
    target_link_libraries(mytarget PRIVATE Qt6::Charts)
    \endcode
    has to be changed to:
    \code
    find_package(Qt6 REQUIRED COMPONENTS Graphs)
    target_link_libraries(mytarget PRIVATE Qt6::Graphs)
    \endcode
    for Qt Graphs.

    \section1 Qmake Module Inclusion

    The inclusion in Qt Charts:
    \code
    QT += charts
    \endcode
    has to be changed to:
    \code
    QT += graphs
    \endcode
    for Qt Graphs.

    \section1 Features missing in Qt Graphs

    These features are missing in Qt Graphs in 6.8 release:

    \list
        \li Qt Graphs Widgets
        \li Candlestick charts
        \li Box-and-whiskers chart
        \li Titles and legends
        \li Log value axis
        \li Polar chart view
    \endlist

    \section2 Theme APIs

    The theming between 2D and 3D graphs is unified, for the theme settings, see
    \l{GraphsTheme}.

    The generic color scheme of the whole graph is now controlled by a
    \l{GraphsTheme::colorScheme}{color scheme} property, and series colors by a
    \l{GraphsTheme::theme}{theme} property. If color scheme is not explicitly
    set, it will follow the desktop theming (Light/Dark).

    \section2 Enums

    In Qt Graphs 2D, all the enums are implemented as scoped enums, for example,
    for the \c{PieSlice.LabelOutside} in Qt Charts, the corresponding enum in
    Qt Graphs 2D is \c{PieSlice.LabelPosition.Outside}.

    \section1 Migrating chart series in QML

    This section gives the examples of how to migrate you code with Qt Charts to
    the Qt Graphs 2D.

    \section2 Migrating Area series

    These code samples implement similar charts:

    With Qt Charts:

    \qml
    ChartView {
        anchors.fill: parent
        ValueAxis {
            id: valueAxisX
            max: 8
        }

        ValueAxis {
            id: valueAxisY
            max: 4
        }

        AreaSeries {
            axisX: valueAxisX
            axisY: valueAxisY
            upperSeries: LineSeries {
                XYPoint { x: 0; y: 2 }
                XYPoint { x: 1; y: 3.5 }
                XYPoint { x: 2; y: 3.8 }
            }
            lowerSeries: LineSeries {
                XYPoint { x: 0.4; y: 1.5 }
                XYPoint { x: 1; y: 2.5 }
                XYPoint { x: 2.4; y: 3 }
            }
        }
    }
    \endqml

    With Qt Graphs:

    \qml
    GraphsView {
        anchors.fill: parent
        axisX: ValueAxis {
            id: xAxis
            max: 8
            tickInterval: 2.0
        }

        axisY: ValueAxis {
            id: yAxis
            max: 4
            tickInterval: 1.0
        }

        AreaSeries {
            upperSeries: LineSeries {
                XYPoint { x: 0; y: 2 }
                XYPoint { x: 1; y: 3.5 }
                XYPoint { x: 2; y: 3.8 }
            }

            lowerSeries: LineSeries {
                XYPoint { x: 0.4; y: 1.5 }
                XYPoint { x: 1; y: 2.5 }
                XYPoint { x: 2.4; y: 3 }
            }
        }
    }
    \endqml


    \section2 Migrating Bar series

    With Qt Charts:

    \qml
    import QtQuick
    import QtCharts

    ChartView {
        BarSeries {
            id: mySeries
            axisX: BarCategoryAxis { categories: ["2007", "2008", "2009", "2010", "2011", "2012" ] }
            BarSet { label: "Bob"; values: [2, 2, 3, 4, 5, 6] }
            BarSet { label: "Susan"; values: [5, 1, 2, 4, 1, 7] }
            BarSet { label: "James"; values: [3, 5, 8, 13, 5, 8] }
        }
    }
    \endqml

    With Qt Graphs:

    \qml
    GraphsView {
        axisX: BarCategoryAxis { categories: ["2007", "2008", "2009", "2010", "2011", "2012" ] }

        BarSeries {
            id: mySeries
            BarSet { label: "Bob"; values: [2, 2, 3, 4, 5, 6] }
            BarSet { label: "Susan"; values: [5, 1, 2, 4, 1, 7] }
            BarSet { label: "James"; values: [3, 5, 8, 13, 5, 8] }
        }
    }
    \endqml

    \section2 Migrating Donut series

    With Qt Charts:

    \qml
    import QtQuick
    import QtCharts

    ChartView {
        PieSeries {
            id: pieOuter
            size: 0.96
            holeSize: 0.7
            PieSlice { id: slice; label: "Alpha"; value: 19511; color: "#99CA53" }
            PieSlice { label: "Epsilon"; value: 11105; color: "#209FDF" }
            PieSlice { label: "Psi"; value: 9352; color: "#F6A625" }
        }

        PieSeries {
            id: pieInner
            size: 0.7
            holeSize: 0.25

            PieSlice { label: "Materials"; value: 10334; color: "#B9DB8A" }
            PieSlice { label: "Employee"; value: 3066; color: "#DCEDC4" }
            PieSlice { label: "Logistics"; value: 6111; color: "#F3F9EB" }

            PieSlice { label: "Materials"; value: 7371; color: "#63BCE9" }
            PieSlice { label: "Employee"; value: 2443; color: "#A6D9F2" }
            PieSlice { label: "Logistics"; value: 1291; color: "#E9F5FC" }

            PieSlice { label: "Materials"; value: 4022; color: "#F9C36C" }
            PieSlice { label: "Employee"; value: 3998; color: "#FCE1B6" }
            PieSlice { label: "Logistics"; value: 1332; color: "#FEF5E7" }
        }

        Component.onCompleted: {
            // Set the common slice properties dynamically for convenience
            for (var i = 0; i < pieOuter.count; i++) {
                pieOuter.at(i).labelPosition = PieSlice.LabelOutside;
                pieOuter.at(i).labelVisible = true;
                pieOuter.at(i).borderWidth = 3;
            }
            for (var i = 0; i < pieInner.count; i++) {
                pieInner.at(i).labelPosition = PieSlice.LabelInsideNormal;
                pieInner.at(i).labelVisible = true;
                pieInner.at(i).borderWidth = 2;
            }
        }
    }
    \endqml

    With Qt Graphs:

    \qml
    GraphsView {
        PieSeries {
            id: pieOuter
            pieSize: 0.96
            holeSize: 0.7
            PieSlice { id: slice; label: "Alpha"; value: 19511; color: "#99CA53" }
            PieSlice { label: "Epsilon"; value: 11105; color: "#209FDF" }
            PieSlice { label: "Psi"; value: 9352; color: "#F6A625" }
        }

        PieSeries {
            id: pieInner
            pieSize: 0.7
            holeSize: 0.25

            PieSlice { label: "Materials"; value: 10334; color: "#B9DB8A" }
            PieSlice { label: "Employee"; value: 3066; color: "#DCEDC4" }
            PieSlice { label: "Logistics"; value: 6111; color: "#F3F9EB" }

            PieSlice { label: "Materials"; value: 7371; color: "#63BCE9" }
            PieSlice { label: "Employee"; value: 2443; color: "#A6D9F2" }
            PieSlice { label: "Logistics"; value: 1291; color: "#E9F5FC" }

            PieSlice { label: "Materials"; value: 4022; color: "#F9C36C" }
            PieSlice { label: "Employee"; value: 3998; color: "#FCE1B6" }
            PieSlice { label: "Logistics"; value: 1332; color: "#FEF5E7" }
        }

        Component.onCompleted: {
            // Set the common slice properties dynamically for convenience
            for (var i = 0; i < pieOuter.count; i++) {
                pieOuter.at(i).labelPosition = PieSlice.LabelPosition.Outside;
                pieOuter.at(i).labelVisible = true;
                pieOuter.at(i).borderWidth = 3;
            }
            for (var i = 0; i < pieInner.count; i++) {
                pieInner.at(i).labelPosition = PieSlice.LabelPosition.InsideNormal;
                pieInner.at(i).labelVisible = true;
                pieInner.at(i).borderWidth = 2;
            }
        }
    }
    \endqml



    \section2 Migrating Line series

    With Qt Charts:

    \qml
    ChartView {
        LineSeries {
            XYPoint { x: 0; y: 0 }
            XYPoint { x: 1.1; y: 2.1 }
            XYPoint { x: 1.9; y: 3.3 }
            XYPoint { x: 2.1; y: 2.1 }
            XYPoint { x: 2.9; y: 4.9 }
            XYPoint { x: 3.4; y: 3.0 }
            XYPoint { x: 4.1; y: 3.3 }
        }
    }
    \endqml

    With Qt Graphs:

    \qml
    GraphsView {
        // Graphs don't calculate a visible range for axes.
        // You should define the visible range explicitly.
        axisX: ValueAxis {
            id: xAxis
            max: 4.1
        }
        axisY: ValueAxis {
            id: yAxis
            max: 4.9
        }

        LineSeries {
            XYPoint { x: 0; y: 0 }
            XYPoint { x: 1.1; y: 2.1 }
            XYPoint { x: 1.9; y: 3.3 }
            XYPoint { x: 2.1; y: 2.1 }
            XYPoint { x: 2.9; y: 4.9 }
            XYPoint { x: 3.4; y: 3.0 }
            XYPoint { x: 4.1; y: 3.3 }
        }
    }
    \endqml

    \section2 Migrating Pie series

    With Qt Charts:

    \qml
    ChartView {
        property variant othersSlice: 0

        PieSeries {
            id: pieSeries
            PieSlice { label: "Volkswagen"; value: 13.5 }
            PieSlice { label: "Toyota"; value: 10.9 }
            PieSlice { label: "Ford"; value: 8.6 }
            PieSlice { label: "Skoda"; value: 8.2 }
            PieSlice { label: "Volvo"; value: 6.8 }
        }

        Component.onCompleted: {
            othersSlice = pieSeries.append("Others", 52.0);
            pieSeries.find("Volkswagen").exploded = true;
        }
    }
    \endqml

    With Qt Graphs:

    \qml
    GraphsView {
        property variant othersSlice: 0

        PieSeries {
            id: pieSeries
            PieSlice { label: "Volkswagen"; value: 13.5 }
            PieSlice { label: "Toyota"; value: 10.9 }
            PieSlice { label: "Ford"; value: 8.6 }
            PieSlice { label: "Skoda"; value: 8.2 }
            PieSlice { label: "Volvo"; value: 6.8 }
        }

        Component.onCompleted: {
            othersSlice = pieSeries.append("Others", 52.0);
            pieSeries.find("Volkswagen").exploded = true;
        }
    }
    \endqml


    \section2 Migrating Scatter series

    With Qt Charts:

    \qml
    ChartView {
        ScatterSeries {
            XYPoint { x: 1.5; y: 1.5 }
            XYPoint { x: 1.5; y: 1.6 }
            XYPoint { x: 1.57; y: 1.55 }
            XYPoint { x: 1.8; y: 1.8 }
            XYPoint { x: 1.9; y: 1.6 }
            XYPoint { x: 2.1; y: 1.3 }
            XYPoint { x: 2.5; y: 2.1 }
        }
    }
    \endqml

    With Qt Graphs:

    \qml
    GraphsView {
        // Graphs don't calculate a visible range for axes.
        // You should define the visible range explicitly.
        ValueAxis {
            id: xyAxis
            min: 1.3
            max: 2.5
        }
        axisX: xyAxis
        axisY: xyAxis

        ScatterSeries {
            XYPoint { x: 1.5; y: 1.5 }
            XYPoint { x: 1.5; y: 1.6 }
            XYPoint { x: 1.57; y: 1.55 }
            XYPoint { x: 1.8; y: 1.8 }
            XYPoint { x: 1.9; y: 1.6 }
            XYPoint { x: 2.1; y: 1.3 }
            XYPoint { x: 2.5; y: 2.1 }
        }
    }
    \endqml


    \section2 Migrating Spline series

    With Qt Charts:

    \qml
    ChartView {
        SplineSeries {
            name: "Spline"
            XYPoint { x: 0; y: 0.0 }
            XYPoint { x: 1.1; y: 3.2 }
            XYPoint { x: 1.9; y: 2.4 }
            XYPoint { x: 2.1; y: 2.1 }
            XYPoint { x: 2.9; y: 2.6 }
            XYPoint { x: 3.4; y: 2.3 }
            XYPoint { x: 4.1; y: 3.1 }
        }
    }
    \endqml

    With Qt Graphs:

    \qml
    GraphsView {
        ValueAxis {
            id: xyAxis
            max: 5
        }
        axisX: xyAxis
        axisY: xyAxis
        SplineSeries {
            XYPoint { x: 0; y: 0.0 }
            XYPoint { x: 1.1; y: 3.2 }
            XYPoint { x: 1.9; y: 2.4 }
            XYPoint { x: 2.1; y: 2.1 }
            XYPoint { x: 2.9; y: 2.6 }
            XYPoint { x: 3.4; y: 2.3 }
            XYPoint { x: 4.1; y: 3.1 }
        }
    }
    \endqml

*/
