From 4e04cda0e600f4e3bb148956ba631647a5c1fa4c Mon Sep 17 00:00:00 2001 From: Lincoln Ramsay Date: Tue, 4 Oct 2011 15:14:01 +1000 Subject: 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 --- doc/src/examples/grue.qdoc | 165 ++++++++++++++++++++++++++++++++++++++++++ doc/src/examples/sensors.qdoc | 110 ---------------------------- 2 files changed, 165 insertions(+), 110 deletions(-) create mode 100644 doc/src/examples/grue.qdoc (limited to 'doc/src') 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(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 @@ -36,115 +36,6 @@ \generatelist related */ -/*! - \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(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 @@ -169,7 +60,6 @@ \snippet ../examples/sensors/cubehouse/view.cpp smoothed */ - /*! \example sensors/sensor_explorer \title Sensor Explorer -- cgit v1.2.3