diff options
Diffstat (limited to 'doc/src/examples/grue.qdoc')
| -rw-r--r-- | doc/src/examples/grue.qdoc | 165 |
1 files changed, 165 insertions, 0 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 + +*/ + |