diff options
Diffstat (limited to 'examples/sensors/sensor_explorer/doc/src/sensor_explorer.qdoc')
| -rw-r--r-- | examples/sensors/sensor_explorer/doc/src/sensor_explorer.qdoc | 127 |
1 files changed, 83 insertions, 44 deletions
diff --git a/examples/sensors/sensor_explorer/doc/src/sensor_explorer.qdoc b/examples/sensors/sensor_explorer/doc/src/sensor_explorer.qdoc index 367711b1..aef88c39 100644 --- a/examples/sensors/sensor_explorer/doc/src/sensor_explorer.qdoc +++ b/examples/sensors/sensor_explorer/doc/src/sensor_explorer.qdoc @@ -31,74 +31,113 @@ \ingroup qtsensors-examples \brief Demonstrates how to read the meta-data of available sensors. - \image qtsensors-examples-explorer.png + \image qtsensors-examples-sensor-explorer.png - This example is divided into two parts: + 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. - \list - \li A \l{Sensor Explorer QML Import}{C++ plugin} that provides QML - alternatives for \c QSensorExplorer, \c QPropertyInfo and - \c QSensorItem C++ classes. - \li A \l{Sensor Explorer QML Application}{QML Application} that uses - the QML types to read the sensor meta-data and present it. - \endlist + \section1 Exposing and Importing the Models - This example is built as an executable with C++ code that runs the QML, - but it can also be launched directly using the \c qmlscene tool. You - should build the top-level \e sensor_explorer project before trying to - run this example or it will not be able to find its dependencies. + The QML models written in C++ are exposed in the project build files + as a \c SensorModels QML module. + \e CMake: \code - qmlscene -I . sensor_explorer.qml + set_target_properties(sensor_explorer PROPERTIES + QT_QML_MODULE_VERSION 1.0 + QT_QML_MODULE_URI SensorModels + ) + qt_qml_type_registration(sensor_explorer) \endcode - Above, the -I . parameter adds the current directory as a module import - path to locate the Explorer QML module. + \e qmake: + \code + CONFIG += qmltypes + QML_IMPORT_NAME = SensorModels + QML_IMPORT_MAJOR_VERSION = 1 + \endcode - \section1 Sensor Explorer QML Import + The indvidual 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 - The Sensor Explorer QML import defines the \e Explorer QML module, - exporting \c QSensorExplorer, \c QPropertyInfo and \c QSensorItem C++ - classes as QML types. The source code is available in the - \c sensor_explorer/import subdirectory. + To access the models in the QML application, the module is imported + by the application QML: + \snippet sensor_explorer/sensor_explorer.qml 0 - \section1 Sensor Explorer QML Application + \section1 Populating the Model of Available Sensors - To write a QML application that will use the QML types exposed by the - Explorer module, following steps are needed: + 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: - Import the Explorer 1.0 declarative plugin: + \snippet sensor_explorer/sensormodels.cpp 0 - \snippet sensor_explorer/sensor_explorer.qml 0 + The model's \c data() function returns a pointer to the requested sensor + object. - Create a SensorExplorer QML item: + \snippet sensor_explorer/sensormodels.cpp 1 - \snippet sensor_explorer/sensor_explorer.qml 1 + Since the sensor (QSensor) is a QObject, the QML is then able to directly + access all metaproperties and -functions directly. - You can retrieve a list of all available sensors using - \c SensorExplorer.availableSensors: + \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. - \snippet sensor_explorer/sensor_explorer.qml 2 + \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. - The example uses the returned list as a model to populate a view of - available sensors. + 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. - To retrieve the properties of a sensor, use \c SensorItem.properties: + \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 - The property list is used as a model for another view that displays the - property names and values. + 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. - It is possible to edit the values of certain sensor properties. Selecting - a writable property value will open an editor. \c SensorExplorer QML - type allows you to pass a new value for a sensor property value as - follows: + \section1 Activating the Sensors - \snippet sensor_explorer/sensor_explorer.qml 4 + 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 - Starting and stopping a sensor can be done by setting the - \c SensorItem.start property: + On clicking the button, the sensor's active property is toggled on/off. - \snippet sensor_explorer/sensor_explorer.qml 5 */ |