Doc: Add an overview of using Qt Charts module

Based on the "Qt Data Visualization and Charts" webinar
(https://www.youtube.com/watch?v=NqbQe6q-0BI) and the current
docs.

Change-Id: I766d1e6123ca4edb9cbd356e433c98c47a7bea88
Reviewed-by: Miikka Heikkinen <miikka.heikkinen@qt.io>

2 files changed, 376 insertions, 0 deletions

diff --git a/src/charts/doc/src/index.qdoc b/src/charts/doc/src/index.qdoc
index 1b736be4..18d5cb0b 100644
--- a/src/charts/doc/src/index.qdoc
+++ b/src/charts/doc/src/index.qdoc
@@ -57,6 +57,11 @@
 
     \snippet doc_src_qtcharts.pro 0
 
+    \section1 Articles and Guides
+    \list
+        \li \l{Qt Charts Overview}
+    \endlist
+
     \section1 Examples
     \list
         \li \l{Qt Charts Examples}
diff --git a/src/charts/doc/src/qtcharts-overview.qdoc b/src/charts/doc/src/qtcharts-overview.qdoc
new file mode 100644
index 00000000..dd042133
--- /dev/null
+++ b/src/charts/doc/src/qtcharts-overview.qdoc
@@ -0,0 +1,371 @@
+/****************************************************************************
+**
+** Copyright (C) 2017 The Qt Company Ltd.
+** Contact: https://www.qt.io/licensing/
+**
+** This file is part of the Qt Charts 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$
+**
+****************************************************************************/
+
+/*!
+    \page qtcharts-overview.html overview
+    \title Qt Charts Overview
+    \brief Visualizing data as 2D charts.
+
+    Qt Charts enables creating stylish, interactive, data centric user
+    interfaces. Qt Charts uses the \l {Graphics View Framework} for ease of
+    integration. The chart components can be used as QWidget or QGraphicsWidget
+    objects or QML types.
+
+    \image examples_chartthemes_light.png
+
+    The QChart class manages the graphical representation of different types of
+    series and other chart related objects, such as legend and axes. QChart is a
+    QGraphicsWidget that can be shown in a QGraphicsScene.
+    A simpler solution is to display a chart in a layout by using the
+    convenience class QChartView instead of QChart. In QML, charts are displayed
+    using the ChartView type.
+
+    Some chart components can also be presented as polar charts by using the
+    the QPolarChart class that is a specialization of the QChart class or the
+    PolarChartView QML type that is a specialization of the ChartView type.
+
+    The look and feel of charts can be customized by using themes, modifying
+    colors and properties, hiding chart components, or animating charts.
+
+    Model mappers enable using a data model derived from the QAbstractItemModel
+    class as a data source for a chart. Model mappers can be either horizontal
+    or vertical.
+
+    \section1 Chart Types
+
+    The Qt Charts module provides the following chart types:
+
+    \list
+        \li \l{Line and spline charts}
+        \li \l{Area and scatter charts}
+        \li \l{Bar charts}
+        \li \l{Pie charts}
+        \li \l{Box-and-whiskers charts}
+        \li \l{Candlestick charts}
+        \li \l{Polar charts}
+    \endlist
+
+    Each chart type is represented by an QAbstractSeries derived class or
+    AbstractSeries derived type in QML. Charts are created by using an instance
+    of a series class and adding it to a QChart or ChartView instance.
+
+    For example:
+    \code
+    QLineSeries* series = new QLineSeries();
+    series->add(0, 6);
+    series->add(2, 4);
+    ...
+    chartView->chart()->addSeries(series);
+    chartView->chart()->createDefaultAxes();
+    \endcode
+
+    Or, in QML:
+
+    \snippet qmlpiechart/qml/qmlpiechart/main.qml 1
+    \snippet qmlpiechart/qml/qmlpiechart/main.qml 2
+    \snippet qmlpiechart/qml/qmlpiechart/main.qml 3
+
+    You can combine different types of series in one chart.
+
+    \section2 Line and Spline Charts
+
+    Line and spline charts present data as a series of data points connected by
+    lines. In a line chart, the data points are connected by straight lines,
+    whereas in a spline chart they are connected by a spline. The spline is
+    drawn by using QPainterPath.
+
+    \inlineimage examples_linechart.png
+    \inlineimage examples_splinechart.png
+
+
+    A line chart is implemented by using the QLineSeries class or the LineSeries
+    QML type.
+
+    A spline chart is implemented by using the QSplineSeries class
+    that inherits QLineSeries or the SplineSeries type that inherits LineSeries.
+
+    For more information, see \l{LineChart Example}, \l{SplineChart Example},
+    and \l{Dynamic Spline Example}.
+    For an example of combining a line chart with a bar chart and using a common
+    axis for both, see \l{Line and BarChart Example}.
+
+    \section2 Area and Scatter Charts
+
+    Area charts present data as an area bound by two lines, whereas scatter
+    charts present data as a collection of points.
+
+    \inlineimage examples_areachart.png
+    \inlineimage examples_scatterchart.png
+
+
+    An area chart is implemented by using the QAreaSeries class or the
+    AreaSeries QML type. By default, the x-axis is used as one boundary and
+    QLineSeries or LineSeries as the other. However, you can use QLineSeries
+    or LineSeries as both boundaries.
+
+    A scatter chart is implemented by using the QScatterSeries class or the
+    ScatterSeries QML type.
+
+    For more information, see \l{AreaChart Example}, \l{ScatterChart Example},
+    and \l{Scatter Interactions Example}.
+
+    \section2 Bar Charts
+
+    A bar chart presents data as horizontal or vertical bars that are grouped
+    by category. The QBarSet class and the BarSet QML type represent one set of
+    bars in a bar chart. The QAbstractBarSeries class is an abstract parent
+    class for all bar series classes, and the AbstractBarSeries type is the
+    parent type of bar series types. The series type determines how the data is
+    presented.
+
+    The QBarSeries class and the BarSeries QML type present data as vertical
+    bars grouped by category. Similarly, the QHorizontalBarSeries class and the
+    HorizontalBarSeries QML type present data as horizontal bars.
+
+    \inlineimage examples_barchart.png
+    \inlineimage examples_horizontalbarchart.png
+
+
+    The QStackedBarSeries class and the StackedBarSeries type present a series
+    of data as vertically stacked bars, with one bar per category. The
+    corresponding horizontal class and type are QHorizontalStackedBarSeries and
+    HorizontalStackedBarSeries, respectively.
+
+    \inlineimage examples_stackedbarchart.png
+    \inlineimage examples_horizontalstackedbarchart.png
+
+
+    The QPercentBarSeries class and PercentBarSeries QML type present a series
+    of categorized data as a percentage of each category. The corresponding
+    horizontal class and type are QHorizontalPercentBarSeries and
+    HorizontalPercentBarSeries, respectively.
+
+    \inlineimage examples_percentbarchart.png
+    \inlineimage examples_horizontalpercentbarchart.png
+
+
+    For more information, see \l{BarChart Example},
+    \l{HorizontalBarChart Example}, \l{StackedBarChart Example},
+    \l{HorizontalStackedBarChart Example}, \l{PercentBarChart Example}, and
+    \l{HorizontalPercentBarChart Example}.
+
+    \section2 Pie Charts
+
+    Pie charts present data as a pie that consists of pie slices. The pie is
+    implemented using the QPieSeries class or the PieSeries QML type and the pie
+    slices are added using the QPieSlice class or the PieSlice QML type.
+
+    The pie can be turned into a donut by specifying a hole size between 0.0
+    and 1.0.
+
+    \inlineimage examples_piechart.png
+    \inlineimage examples_donutchart.png
+
+
+    For more information, see \l{PieChart Example},
+    \l{Pie Chart Customization Example}, \l{DonutChart Example},
+    \l{Donut Chart Breakdown Example}, and \l{Nested Donuts Example}.
+
+    \section2 Box-and-Whiskers Charts
+
+    The box-and-whiskers charts present data as quartiles extended with whiskers
+    that show the variability of the values. The items in box plot series are
+    grouped by category, similarly to bar sets in bar series. For each
+    box-and-whiskers item, the lower extreme, lower quartile, median, upper
+    quartile, and upper extreme value are specified.
+
+    A box-and-whiskers chart is implemented by using the QBoxPlotSeries and
+    QBoxSet classes or the BoxPlotSeries and BoxSet QML types.
+
+    \image examples_boxplotchart.png
+
+    For more information, see \l{Box and Whiskers Example}.
+
+    \section2 Candlestick Charts
+
+    Candlestick charts presents a series of data shown as candlesticks.
+
+    \image examples_candlestickchart.png
+
+    A candlestick chart is implemented by using the QCandlestickSeries and
+    QCandlestickSet classes or the CandlestickSeries and CandlestickSet QML
+    types.
+
+    \section2 Polar Charts
+
+    Polar charts present data in a circular graph, where the placement of data
+    is based on the angle and distance from the center of the graph, the
+    \e pole.
+
+    \image examples_polarchart.png
+
+    The QPolarChart class is a specialization of the QChart class. It supports
+    line, spline, area, and scatter series, as well as all the axis types
+    supported by them. The axis can be used either as a radial or an angular
+    axis. In QML, the corresponding type is PolarChartView.
+
+    For more information, see \l{Polar Chart Example} and \l{Qml Polar Chart}.
+
+    \section1 Axes
+
+    Qt Charts supports the following axis types:
+
+    \list
+        \li Value axis
+        \li Category axis
+        \li Bar category axis
+        \li Date-time axis
+        \li Logarithmic value axis
+    \endlist
+
+    An axis can be set up to show a line with tick marks, grid lines, and
+    shades. The values on the axis are drawn at the positions of tick marks.
+    All axis types are specializations of the QAbstractAxis class or the
+    AbstractAxis QML type.
+
+    A value axis adds real values to a chart's axis. It is implemented using the
+    QValueAxis class or the ValueAxis QML type.
+
+    A category axis is implemented using the QCategoryAxis class or the
+    CategoryAxis QML type. It has named ranges and adjustable range widths.
+
+    The bar category axis is similar to a category axis, but the range width is
+    the same for all ranges. A bar category axis is implemented using the
+    QBarCategoryAxis class or the BarCategoryAxis QML type.
+
+    A date-time axis adds dates and times to a chart's axis. It is implemented
+    using the QDateTimeAxis class or the DateTimeAxis QML type.
+
+    A logarithmic axis adds a logarithmic scale to a chart's axis. A logarithmic
+    scale is a nonlinear scale that is based on orders of magnitude, so that
+    each tick mark on the axis is the previous tick mark multiplied by a value.
+    A logarithmic axis is implemented using the QLogValueAxis class or the
+    LogValueAxis QML type.
+
+    Multiple axes can be defined for one chart. The axes can be placed down, up,
+    left, or right of the chart. Further, the axes can be of different types.
+    However, mixing axis types that would result in different domains is not
+    supported, such as specifying QValueAxis and QLogValueAxis on the same
+    orientation.
+
+    For more information, see \l{DateTimeAxis Example},
+    \l{Logarithmic Axis Example}, \l{Multiple Axes Example}, and \l{Qml Axes}.
+
+    \section1 Legend
+
+    A legend is a graphical object that displays the legend of a chart. Legend
+    objects cannot be created or deleted, but they can be referenced via the
+    QChart class or the ChartView QML type. The legend state is updated by
+    QChart or ChartView when series change.
+
+    A legend can be positioned below or above the chart, as well as to the left
+    or right of it. By default, the legend is attached to the chart view, but it
+    can be detached to a separate graphics item that can be moved around freely.
+
+    It is possible to hide either individual markers from the legend or the
+    whole legend.
+
+    Legend markers can be modified by using the QLegendMarker base class and the
+    subclasses for each series type: QAreaLegendMarker, QBarLegendMarker,
+    QBoxPlotLegendMarker, QCandlestickLegendMarker, and QXYLegendMarker.
+
+    In QML, legend markers can be modified by creating custom legends, as
+    illustrated by the \l{Qml Custom Legend} example.
+
+    \section1 Interacting with Charts
+
+    End users can interact with charts by dynamically adding values to them,
+    drilling down into data, zooming into and out of charts, scrolling charts,
+    and clicking items in charts or hovering the mouse over them.
+
+    \section2 Drawing Data Dynamically
+
+    It is possible to add data to charts dynamically and to make the chart view
+    scroll automatically to display the new data.
+
+    For more information, see \l{Dynamic Spline Example}.
+
+    \section2 Drilling Down into Data
+
+    Drilldown effects can be implemented to bar or pie charts, for example.
+    When users select an item in the chart, a more detailed view of the
+    item is displayed. This is implemented by deleting the first series and
+    adding another one.
+
+    For more information, see \l{StackedBarChart Drilldown Example} and
+    \l{PieChart Drilldown Example}.
+
+    \section2 Zooming and Scrolling
+
+    Users can use the keyboard for zooming and scrolling. They can scroll charts
+    by using the arrow keys and zoom into or out of charts by using the plus and
+    minus keys. In addition, QRubberBand can be used for selecting the area to
+    zoom into.
+
+    On touch devices, gestures can be used for panning and zooming.
+
+    For more information, see \l{Zoom Line Example}.
+
+    \section2 Clicking and Hovering
+
+    You can connect slots to signals emitted when end users click items in
+    charts or hover the mouse over them. This enables you to add elements, such
+    as callouts, to the charts.
+
+    For more information, see \l{Callout Example}.
+
+    \section1 Themes
+
+    A theme is a built-in collection of UI style related settings applied to all
+    the visual elements of a chart, such as colors, pens, brushes, and fonts of
+    series, as well as axes, title, and legend.
+
+    \image examples_chartthemes_blue_cerulean.png
+
+    Qt Charts comes with the following predefined themes:
+
+    \list
+        \li Light theme, which is the default theme
+        \li Cerulean blue theme
+        \li Dark theme
+        \li Sand brown theme
+        \li Natural color system (NCS) blue theme
+        \li High contrast theme
+        \li Icy blue theme
+        \li Qt theme
+    \endlist
+
+    The themes can be customized by changing the colors, pens, brushes, and
+    fonts. New themes can be added by modifying the Qt Charts source code.
+
+    \note Changing the theme will overwrite all customization previously applied
+    to the series.
+
+    For more information, see the \l {Chart themes example}.
+*/