path: root/src/charts/doc/src/qtcharts-overview.qdoc

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

/*!
    \page qtcharts-overview.html
    \title Qt Charts Overview
    \brief Visualizing data as 2D charts.
    \ingroup explanation

    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 qmlchartsgallery/qml/PieChart.qml 1
    \snippet qmlchartsgallery/qml/PieChart.qml 2

    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{Creating Line Charts} and \l{Creating Spline Charts}.
    For an example of combining a line chart with a bar chart and using a common
    axis for both, see \l{Combining Line and BarChart}.

    \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{Creating Area Charts} and
    \l{Creating Scatter Charts}.


    \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{Creating Bar Charts},
    \l{Creating Horizontal Stacked Bar Charts}, \l{Creating Horizontal Bar Charts},
    and \l{Creating Horizontal Percent Bar Charts}.

    \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{Charts with Widgets Gallery},
    \l{Creating a Donut Breakdown Chart}, and \l{Creating Nested Donut Charts}.

    \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{Creating Box-and-Whiskers Charts}.

    \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{Creating Polar Charts} and \l{Using Polar Charts with QML}.

    \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{Line Charts with Date and Time Axes},
    \l{Using Logarithmic Value Axes}, \l{Using Multiple Axes}, and \l{Using Axes with QML}.

    \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{Customizing Legends} 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{Creating Spline Charts}.

    \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{Implementing Drilldown}.

    \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{Drawing a Callout on Top of a Chart}.

    \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 {Creating Charts With Themes}.
*/