diff options
author | Lincoln Ramsay <lincoln.ramsay@nokia.com> | 2011-10-04 15:14:01 +1000 |
---|---|---|
committer | Lincoln Ramsay <lincoln.ramsay@nokia.com> | 2011-10-10 09:25:31 +1000 |
commit | 4e04cda0e600f4e3bb148956ba631647a5c1fa4c (patch) | |
tree | 5dd8a0f2e2a0b2cdc8075f05a66cb1f6689e51c4 /doc | |
parent | 93be0e5c0fd1694b0868187ed3daa006dfa4bd79 (diff) |
Grue Sensor example
Updated, documented as an example.
Now with a QML import and a QML app.
Fixes: MTMW-85
Change-Id: I06772cf4a07ea0d2ec7bfccda6e8f51b5d866c20
Reviewed-on: http://codereview.qt-project.org/6016
Reviewed-by: Lincoln Ramsay <lincoln.ramsay@nokia.com>
Diffstat (limited to 'doc')
-rw-r--r-- | doc/src/examples/grue.qdoc | 165 | ||||
-rw-r--r-- | doc/src/examples/sensors.qdoc | 110 |
2 files changed, 165 insertions, 110 deletions
diff --git a/doc/src/examples/grue.qdoc b/doc/src/examples/grue.qdoc new file mode 100644 index 00000000..d4dc66fe --- /dev/null +++ b/doc/src/examples/grue.qdoc @@ -0,0 +1,165 @@ +/**************************************************************************** +** +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** GNU Free Documentation License +** 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. +** +** Other Usage +** Alternatively, this file may be used in accordance with the terms +** and conditions contained in a signed written agreement between you +** and Nokia. +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page gruesensorexample.html + \title Grue Sensor Example + \brief The Grue sensor example demonstrates all the steps from creating a new sensor to using it. + \ingroup qtsensors-examples + + The Grue sensor example demonstrates all the steps from creating a new sensor to using it. + + The sensor definition is placed in a library where client apps can access it. The actual implementation + lives in a plugin. + + \list + \o \l{Grue Sensor Definition} + \o \l{Grue Sensor Implementation} + \endlist + + The sensor can now be used by a C++ application, even if the application does not have access to the + definition. + + \list + \o \l{Grue Sensor Console Application} + \endlist + + To make the sensor available to a QML application an import must be created. + + \list + \o \l{Grue Sensor QML Import} + \o \l{Grue Sensor QML Application} + \endlist +*/ + +/*! + \example sensors/grue/lib + \title Grue Sensor Definition + \brief The Grue sensor is defined in a library so that applications can use it. + + First up is the sensor type. This is the interface for sensors that report + on your likelihood of being eaten by a Grue. Such sensors are very important + to adventurers, particularly if they are going into dark places as this is + where Grues live. + + The interface is a simple one. It provides only 1 piece of information, your + chance of being eaten. For the details on how this is property should be + interpreted please see the documentation in gruesensor.cpp. + + This example was created using the make_sensor.pl script which can be found in + src/sensors. As such, it contains some generated code that defines the convenience + classes GrueFilter and GrueSensor. + + \sa {Grue Sensor Example} +*/ + +/*! + \example sensors/grue/plugin + \title Grue Sensor Implementation + \brief The Grue sensor implementation lives in a plugin that is loaded by the QtSensors library. + + The Grue sensor needs a backend before it can be used. The backend provided + is rather basic and it relies on some kind of light sensor to work but it + gets the job done. If new hardware that can detect the actual presence of Grues + becomes available a backend could be created that supports this hardware and + applications using the Grue sensor would be able to use it without any changes. + + There are a few mandatory parts to a backend. They are the start and stop methods + and the setReading call. The start and stop methods are used to start and stop + any underlying hardware. In the case of this backend they start and stop a + light sensor. In the start method, the backend should be sure to call the + sensorStopped() or sensorBusy() methods if it cannot start. + + \snippet ../examples/sensors/grue/plugin/gruesensorimpl.cpp start + + The setReading method is needed so that the sensors library knows where the + readings are coming from. This backend has a local copy of the reading so + it passes a pointer to the function. + + \snippet ../examples/sensors/grue/plugin/gruesensorimpl.cpp setReading + + However it is also possible to pass null to the setReading method in which + case the sensors library will create an instance and return a pointer. + + \code + // Create a reading instance for us to use + m_reading = setReading<GrueSensorReading>(0); + \endcode + + The Grue sensor backend also supplies some metadata. + + The backend checks 2 things, how dark it is and how long you have been in the dark. + It uses the readingChanged() signal to know when to check the light sensor's + value. Once it is dark, it uses a timer to increase your chance of being eaten. + + The Grue sensor backend is delivered as a plugin. The plugin has a factory object + that registers the types available and does the actual instantiation of the backend. + + \sa {Grue Sensor Example} +*/ + +/*! + \example sensors/grue/console_app + \title Grue Sensor Console Application + \brief The Grue sensor console application demonstrates use of the Grue sensor. + + This is a simple commandline application. It demonstrates how to use the generic + access feature of QtSensors to avoid a link-time dependency on the Grue Sensor + library. + + \sa {Grue Sensor Example} +*/ + +/*! + \example sensors/grue/import + \title Grue Sensor QML Import + \brief The Grue sensor QML import exports the GrueSensor class as a QML element. + + This example creates the \l {Grue 1.0} import. + + \sa {Grue Sensor Example} +*/ + +/*! + \example sensors/grue/qml_app + \title Grue Sensor QML Application + \brief The Grue sensor QML application demonstrates use of the GrueSensor QML element. + + blah blah blah + + \sa {Grue Sensor Example} +*/ + +/*! + \qmlmodule Grue 1 + \title Grue 1.0 + \brief QML import for the Grue Sensor Example + + blah blah blah + +*/ + diff --git a/doc/src/examples/sensors.qdoc b/doc/src/examples/sensors.qdoc index db02d7d6..6cb3ce78 100644 --- a/doc/src/examples/sensors.qdoc +++ b/doc/src/examples/sensors.qdoc @@ -37,115 +37,6 @@ */ /*! - \example sensors/grueplugin - \title Grue Plugin - \brief The Grue Plugin demonstrates creation of a new sensor backend. - \ingroup qtsensors-examples - - The Grue plugin example demonstrates the creation of a new sensor type, - a sensor backend and plugin for the sensors library. Related to this example - is the \l{sensors/grueapp}{Grue Application} example. - - \tableofcontents - - \section1 Grue Sensor Type - - The files for this are: - - \list - \o gruesensor.h - \o gruesensor_p.h - \o gruesensor.cpp - \endlist - - First up is the sensor type. This is the interface for sensors that report - on your likelihood of being eaten by a Grue. Such sensors are very important - to adventurers, particularly if they are going into dark places as this is - where Grues live. - - The interface is a simple one. It provides only 1 piece of information, your - chance of being eaten. For the details on how this is property should be - interpreted please see the documentation in gruesensor.cpp. - - This example was created using the make_sensor.pl script which can be found in - src/sensors. As such, it contains some generated code that defines the convenience - classes GrueFilter and GrueSensor. - - \section1 Grue Sensor Backend - - The files for this are: - - \list - \o gruesensorimpl.h - \o gruesensorimpl.cpp - \endlist - - The Grue sensor needs a backend before it can be used. The backend provided - is rather basic and it relies on some kind of light sensor to work but it - gets the job done. If new hardware that can detect the actual presence of Grues - becomes available a backend could be created that supports this hardware and - applications using the Grue sensor would be able to use it without any changes. - - There are a few mandatory parts to a backend. They are the start and stop methods - and the setReading call. The start and stop methods are used to start and stop - any underlying hardware. In the case of this backend they start and stop a - light sensor. In the start method, the backend should be sure to call the - sensorStopped() or sensorBusy() methods if it cannot start. - - \snippet ../examples/sensors/grueplugin/gruesensorimpl.cpp start - - The setReading method is needed so that the sensors library knows where the - readings are coming from. This backend has a local copy of the reading so - it passes a pointer to the function. - - \snippet ../examples/sensors/grueplugin/gruesensorimpl.cpp setReading - - However it is also possible to pass null to the setReading method in which - case the sensors library will create an instance and return a pointer. - - \code - // Create a reading instance for us to use - m_reading = setReading<GrueSensorReading>(0); - \endcode - - The Grue sensor backend also supplies some metadata. - - The backend checks 2 things, how dark it is and how long you have been in the dark. - It uses the readingChanged() signal to know when to check the light sensor's - value. Once it is dark, it uses a timer to increase your chance of being eaten. - - \section1 Grue Sensor Plugin - - The files for this are: - - \list - \o main.cpp - \endlist - - The Grue sensor backend is delivered as a plugin. The plugin has a factory object - that registers the types available and does the actual instantiation of the backend. - - \sa {sensors/grueapp}{Grue Application} -*/ - - -/*! - \example sensors/grueapp - \title Grue Application - \brief The Grue Application demonstrates use of a new sensor type. - \ingroup qtsensors-examples - - The Grue application example demonstrates the use of the Grue sensor which - was defined and implemented by the \l{sensors/grueplugin}{Grue Plugin} example. - The Grue application is a commandline application. It is significant to note that - there is no link-time dependency on the Grue plugin. The Grue application uses - the generic access feature of the Sensors API. - - \sa {sensors/grueplugin}{Grue Plugin} -*/ - - -/*! \example sensors/cubehouse \title Cube House \ingroup qtsensors-examples @@ -169,7 +60,6 @@ \snippet ../examples/sensors/cubehouse/view.cpp smoothed */ - /*! \example sensors/sensor_explorer \title Sensor Explorer |