Using ChartDirector with QML/Qt Quick

ChartDirector comes with a lot of QML/Qt Quick examples in the "ChartDirector/qmldemo" directory. They are packages into the following Qt projects. The Qt ".pro" project files can be opened with the Qt Creator.

helloworld: This is a basic Qt project that just displays a simple bar chart.
qmldemo: This project includes all ChartDirector chart types. It demonstrates various advanced features such as tooltips with rich formatting, clickable chart objects, programmable track cursors, zooming and scrolling, realtime charts, contour cross section, 3D chart rotations, PDF reports and huge dataset support.

All ChartDirector QML/Qt Quick sample programs uses the QmlChartViewer control to display charts and handle user interactions.

To use QmlChartViewer in your own project:

Include "qmlchartviewer.h" and "qmlchartviewer.cpp" in your project.
Register the QmlChartViewer and QmlViewPortControl as QML types, so you can use them in QML. This can be by including the "qmlchartviewer.h" and the following lines in the start up code of the application (usually the "main" function).

#include "qmlchartviewer.h" ...... // Register QmlChartViewer and QmlViewPortControl under "advsofteng.com 1.0" qmlRegisterType<QmlChartViewer>("advsofteng.com", 1, 0, "QmlChartViewer"); qmlRegisterType<QmlViewPortControl>("advsofteng.com", 1, 0, "QmlViewPortControl");
You can then use the QmlChartViewer in QML, like:

// Import the QmlChartViewer and QmlViewPortControl import advsofteng.com 1.0 // The QML Chart Viewer QmlChartViewer { id: myViewer }

To display a chart using QmlChartViewer, the QmlChartViewer can be passed to the C++ chart drawing function. In the function, only one line of code is needed:

// myQmlViewer is a QmlChartViewer pointer; myChart is a BaseChart pointer
myQmlViewer->setChart(myChart);

Hot spots are special regions in on the chart that are usually used to represent chart objects, such as data representation objects (sectors for pie chart, bars for bar charts, etc). One can display tool tips when the mouse is over the hot spots, and/or to make the hot spots clickable with mouse cursor feedback.

In ChartDirector, hot spots for the charts are defined using standard HTML image maps (text strings containing HTML tags). The BaseChart.getHTMLImageMap method can be used to generate image maps automatically for a chart. To set the image map to the QmlChartViewer control, one may use:

myQmlViewer->setImageMap(myImageMap);

After setting the image map, the QmlChartViewer control will display the tool tips defined in the image map when the mouse is over the hot spots. For clickable hot spots, it will also change the mouse cursor into a "hand" shape.

When the mouse clicks on the QmlChartViewer control, a QmlChartViewer.clicked signal will be emitted. The signal handler can use QmlChartViewer.getHotSpot to determine which hot spot has been clicked. An example is like:

QmlChartViewer {
    onClicked: {
        var h = getHotSpot();
        // If the hotspot has a path attribute, it is clickable
        if (h["path"])
            // In the sample code, we simply display all the hot spot parameters
            hotSpotDialog.showHotSpot(h)
    }
}

In ChartDirector, track cursors can be created by drawing them on a "dynamic layer" when the mouse moves on the chart. For example, drawing a horizontal line and a vertical line will create a crosshair cursor that tracks the mouse. Other things, such as legend entries, data labels and axis labels, can also be drawn, allowing them to update as the mouse moves over the chart.

QmlChartViewer will emit QmlChartViewer.mouseMovePlotArea signals when the mouse moves over the extended plot area. The track cursor drawing code can be implemented in the handler of this signal.

A viewport can be imagined as a window to an underlying surface. For example, a data series with 10 years of data can be imagined as a long surface. If only 1 year of data is displayed, we may consider this as the viewport showing 10% of the underlying surface.

Scrolling can be handled as moving the viewport, while zooming in and out can be handled as changing the viewport size.

QmlChartViewer supports using mouse click and drag to control the viewport (see QmlChartViewer.mouseUsage). When the viewport is changed by mouse actions, QmlChartViewer will emit a QmlChartViewer.viewPortChanged signal. The signal handler can then redraw the chart to reflect the updated viewport.

QmlChartViewer also includes methods for changing the viewport programmatically. This allows external controls (such as scroll bars, mouse wheel, sliders, date picker, etc) to manipulate the viewport.

The QmlViewPortControl is a Qt Quick control allows a user to visualize and control the QmlChartViewer viewport.

In typical usage, the QmlViewPortControl will display an "overall chart" that shows the full data range. Once the QmlViewPortControl is associated with the QmlChartViewer, it will draw a rectangle on the overall chart to represent the QChartViewer viewport, and dim out the region outside the rectangle. If the viewport changed, such as if the user zooms in the chart, the rectangle will automatically update.

The user can drag the rectangle to move the QmlChartViewer viewport (equivalent to scrolling). The user can also resize the viewport by dragging the border of the rectangle (equivalent to zooming), or drag a new rectangular region on the overall chart to be used as the new viewport, or click on a point on the chart to center the viewport at that point. In all these cases, as the viewport has changed, the QmlChartViewer.viewPortChanged signal will be emitted.

The code to use the QmlViewPortControl with a QmlChartViewer is like:

// Import the QmlChartViewer and QmlViewPortControl
import advsofteng.com 1.0

QmlChartViewer {
    id: myVewer
}

QmlViewPortControl {
    id: myViewPortControl

    // Bind the QmlViewPortControl to the QmlChartViewer
    viewer: myVewer
}

ChartDirector can output the charts in PDF, SVG, PNG, JPG, GIF and BMP format to a file using BaseChart.makeChart, or to memory using BaseChart.makeChart2. For example, to save the chart in a QmlChartViewer to a file, the code is:

// myViewer a QmlChartViewer object which contains the chart to save. The format
// is determined by the file extension in pathname.
myViewer->getChart()->makeChart(pathname);