/****************************************************************************
**
** Copyright (C) 2017 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** 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 Free Documentation License Usage
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of
** this file. Please review the following information to ensure
** the GNU Free Documentation License version 1.3 requirements
** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
** $QT_END_LICENSE$
**
****************************************************************************/

/*!
    \example sensor_explorer
    \title Qt Sensors - Explorer QML Example
    \ingroup qtsensors-examples
    \brief Demonstrates how to read the meta-data of available sensors.

    \image qtsensors-examples-sensor-explorer.png

    The example is implemented as a typical model-view application. The
    models are written with C++ and exposed to QML, and the views are
    implemented as QML types in the QML application.

    \section1 Exposing and Importing the Models

    The QML models written in C++ are exposed in the project build files
    as a \c SensorModels QML module.

    \e CMake:
    \code
    qt_add_qml_module(sensor_explorer
        URI SensorModels
        VERSION 1.0
    )
    \endcode

    \e qmake:
    \code
    CONFIG += qmltypes
    QML_IMPORT_NAME = SensorModels
    QML_IMPORT_MAJOR_VERSION = 1
    \endcode

    The individual model elements are exposed as part of the model
    code by using the \c QML_ELEMENT macro as illustrated here:
    \snippet sensor_explorer/sensormodels.h 0

    To access the models in the QML application, the module is imported
    by the application QML:
    \snippet sensor_explorer/sensor_explorer.qml 0

    \section1 Populating the Model of Available Sensors

    The \c AvailableSensorsModel is a list model that provides information on
    available sensors on the device. The model is populated once at the
    element's construction time:

    \snippet sensor_explorer/sensormodels.cpp 0

    The model's \c data() function returns a pointer to the requested sensor
    object.

    \snippet sensor_explorer/sensormodels.cpp 1

    Since the sensor (QSensor) is a QObject, the QML is then able to directly
    access all metaproperties and -functions directly.

    \note It would be possible to refresh the sensor list later at will, but for
    the simplicity of the example such functionality is not exposed to QML.

    \section1 Populating the Model of Sensor Properties

    The \c SensorPropertyModel is a table model that provides individual
    sensor's property-value pairs as columns. The column \c 0 provides the
    property's name and the column \c 1 provides the property's value. The
    population of the properties is done by reading the metadata of the sensors.
    The model reads both the sensor's metadata as well as the sensor's reading's
    metadata. The code below illustrates the reading of the \c reading metadata:

    \snippet sensor_explorer/sensormodels.cpp 2

    This metadata access allows providing the model data for all sensors
    without prior compile-time understanding of their properties.

    Once the metadata is set, the code then subscribes to the
    QSensor::readingChanged() signal to detect sensor reading changes.
    Upon such changes (for example a rotation value changes), the model data
    is updated accordingly.

    \section1 Viewing the Models

    The QML application is based on two views. The first view shows the available
    sensors as a selectable list. The second view shows the selected sensor's
    properties and their values. The delegates for viewing the individual items
    are simplistic \e {rectangle and text} items.

    Binding the two views functionally together is done by binding the property
    model's \c sensor property to the current selection of the available sensors
    model:

    \snippet sensor_explorer/sensor_explorer.qml 1

    When the selected sensor changes, the \c sensor of the property model changes
    accordingly.

    The following snippet illustrates how the property view is implemented. For
    more details about QML models and views, please see
    \l{Models and Views in Qt Quick}.

    \snippet sensor_explorer/sensor_explorer.qml 3

    For clarity it should be mentioned that the \c display attribute used by
    the text element refers to the Qt::DisplayRole role of the model, which is
    provided by default by Qt models.

    \section1 Activating the Sensors

    The example has a button for activating and deactivating the currently
    selected sensor. The button is enabled only if a sensor is currently
    selected, as illustrated below.

    \snippet sensor_explorer/sensor_explorer.qml 2

    On clicking the button, the sensor's active property is toggled on/off.

*/