From 52c831db165f5068826dddef4d41427a98a42dfd Mon Sep 17 00:00:00 2001 From: Topi Reinio Date: Tue, 13 Aug 2013 14:40:13 +0200 Subject: Doc: Update Grue Sensor example Fix a number of issues with the example: - Add \omit to generated doc sections, we don't want qdoc to process these (not part of Qt docs) - Combine the 5 separate examples into a single \example and discuss each subproject in a subsection - Add example image to doc - Fix deployment/build target directories and import paths - Define a 'reading' property for the sensor to make it work on QtSensors 5.1 - Fix the Grue QML application to avoid flicker from frequent updates. Task-number: QTBUG-32881 Change-Id: I2785faead1baaf5b1ae9d05df3398e018e945418 Reviewed-by: Jerome Pasion Reviewed-by: Lorn Potter --- examples/sensors/grue/console_app/console_app.pro | 13 +++-- .../grue/doc/images/qtsensors-examples-grue.png | Bin 0 -> 12278 bytes examples/sensors/grue/doc/src/grue.qdoc | 63 +++++++++------------ examples/sensors/grue/grue.qml | 54 +++++++++++++----- examples/sensors/grue/import/import.pro | 19 +++++-- examples/sensors/grue/import/main.cpp | 7 +++ examples/sensors/grue/lib/gruesensor.cpp | 12 ++++ examples/sensors/grue/lib/gruesensor.h | 1 + examples/sensors/grue/lib/lib.pro | 11 ++-- examples/sensors/grue/plugin/plugin.pro | 12 ++-- examples/sensors/grue/qml.pro | 5 +- 11 files changed, 124 insertions(+), 73 deletions(-) create mode 100644 examples/sensors/grue/doc/images/qtsensors-examples-grue.png diff --git a/examples/sensors/grue/console_app/console_app.pro b/examples/sensors/grue/console_app/console_app.pro index 786d2b19..f2b627ec 100644 --- a/examples/sensors/grue/console_app/console_app.pro +++ b/examples/sensors/grue/console_app/console_app.pro @@ -1,8 +1,11 @@ -TEMPLATE=app -TARGET=detect_grue +TEMPLATE = app +TARGET = detect_grue CONFIG += console -QT=core sensors -SOURCES=main.cpp +QT = core sensors -target.path = $$[QT_INSTALL_EXAMPLES]/qtsensors/grue +DESTDIR = $$OUT_PWD/.. + +SOURCES = main.cpp + +target.path = $$[QT_INSTALL_EXAMPLES]/sensors/grue INSTALLS += target diff --git a/examples/sensors/grue/doc/images/qtsensors-examples-grue.png b/examples/sensors/grue/doc/images/qtsensors-examples-grue.png new file mode 100644 index 00000000..81b37254 Binary files /dev/null and b/examples/sensors/grue/doc/images/qtsensors-examples-grue.png differ diff --git a/examples/sensors/grue/doc/src/grue.qdoc b/examples/sensors/grue/doc/src/grue.qdoc index 9a0d4472..32cfb7f5 100644 --- a/examples/sensors/grue/doc/src/grue.qdoc +++ b/examples/sensors/grue/doc/src/grue.qdoc @@ -26,11 +26,13 @@ ****************************************************************************/ /*! - \page gruesensorexample.html + \example grue \title Qt Sensors - Grue Sensor Example \brief The Qt Sensors - Grue sensor example demonstrates all the steps from creating a new sensor to using it. \ingroup qtsensors-examples + \image qtsensors-examples-grue.png + The Qt Sensors - 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 @@ -54,12 +56,11 @@ \li \l{Grue Sensor QML Import} \li \l{Grue Sensor QML Application} \endlist -*/ -/*! - \example grue/lib - \title Grue Sensor Definition - \brief The Grue sensor is defined in a library so that applications can use it. + \section1 Grue Sensor Definition + + The Grue sensor is defined in a library so that applications can use it. + The source code is available in the \c{grue/lib} subdirectory. 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 @@ -74,13 +75,10 @@ src/sensors. As such, it contains some generated code that defines the convenience classes GrueFilter and GrueSensor. - \sa {Qt Sensors - Grue Sensor Example} -*/ + \section1 Grue Sensor Implementation -/*! - \example grue/plugin - \title Grue Sensor Implementation - \brief The Grue sensor implementation lives in a plugin that is loaded by the Qt Sensors library. + The Grue sensor implementation lives in a plugin that is loaded by the Qt Sensors + library. The source code is available in the \c{grue/plugin} subdirectory. 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 @@ -119,44 +117,37 @@ 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 {Qt Sensors - Grue Sensor Example} -*/ + \section1 Grue Sensor Console Application -/*! - \example grue/console_app - \title Grue Sensor Console Application - \brief The Grue sensor console application demonstrates use of the Grue sensor. + The Grue sensor console application demonstrates use of the Grue sensor. + The source code is available in the \c{grue/console_app} subdirectory. This is a simple commandline application. It demonstrates how to use the generic access feature of Qt Sensors to avoid a link-time dependency on the Grue Sensor library. - \sa {Qt Sensors - Grue Sensor Example} -*/ + \section1 Grue Sensor QML Import -/*! - \example grue/import - \title Grue Sensor QML Import - \brief The Grue sensor QML import exports the GrueSensor class as a QML type. + The Grue sensor QML import exports the GrueSensor class as a QML type. + The source code is available in the \c{grue/import} subdirectory. - This example creates the \e {Grue 1.0} import. + This creates the \e {Grue 1.0} import. - \sa {Qt Sensors - Grue Sensor Example} -*/ + \section1 Grue Sensor QML Application -/*! - \example grue - \title Grue Sensor QML Application - \brief The Grue sensor QML application demonstrates use of the GrueSensor QML type. + The Grue sensor QML application demonstrates the use of GrueSensor QML type. - This is a pure QML application that can be run from Qt Creator or directly using the - \c qmlscene binary. You should install the other projects before trying to run + The application consists of a single QML file and an image. It is built as an + exucutable 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 'grue' project before trying to run this example or it will not be able to find its dependencies. \code - qmlscene grue.qml + qmlscene -I . grue.qml \endcode - \sa {Qt Sensors - Grue Sensor Example} + Above, the \c{-I .} parameter adds the current directory as a module import + path to locate the Grue QML module. */ - diff --git a/examples/sensors/grue/grue.qml b/examples/sensors/grue/grue.qml index 65980165..acafdb69 100644 --- a/examples/sensors/grue/grue.qml +++ b/examples/sensors/grue/grue.qml @@ -43,33 +43,56 @@ import QtSensors 5.0 import Grue 1.0 Rectangle { + id: root width: 320 height: 480 color: "black" + property int percent: 0 + property string text: "" + property real grueOpacity: 0.0 + + function updateStatus(newPercent, newOpacity, newText) { + if (root.percent === newPercent) + return; + + // Delay updating the visual status to prevent flicker + timer.interval = (newPercent < root.percent) ? 500 : 0; + + root.percent = newPercent; + root.text = newText; + root.grueOpacity = newOpacity; + + timer.start() + } + + Timer { + id: timer + running: false + repeat: false + onTriggered: { + text.text = root.text + grueimg.opacity = root.grueOpacity + } + } + GrueSensor { id: sensor active: true onReadingChanged: { var percent = reading.chanceOfBeingEaten; - var thetext = ""; - var theopacity = 0; if (percent === 0) { - thetext = "It is light. You are safe from Grues."; + updateStatus(percent, 0.0, "It is light.
You are safe from Grues."); } else if (percent === 100) { - thetext = "You have been eaten by a Grue!"; + updateStatus(percent, 1.0, "You have been eaten by a Grue!"); sensor.active = false; - theopacity = 1; } else if (percent > 0) { - thetext = "It is dark. You are likely to be eaten by a Grue. " - + "Your chance of being eaten by a Grue: "+percent+" percent."; - theopacity = 0.05 + (percent * 0.001); + updateStatus(percent, 0.05 + (percent * 0.001), + "It is dark.
You are " + percent +" % " + + "likely to be eaten by a Grue."); } - text.font.pixelSize = 30; - text.text = "

" + thetext + "

"; - grueimg.opacity = theopacity; } } @@ -79,10 +102,10 @@ Rectangle { anchors.topMargin: 0 anchors.left: parent.left anchors.right: parent.right - text: "I can't tell if you're going to be eaten by a Grue or not. You're on your own!" wrapMode: Text.WordWrap - font.pixelSize: 50 - color: "white" + text: "I can't tell if you're going to be eaten by a Grue or not. You're on your own!" + font.pixelSize: 30 + color: "lightgray" } Image { @@ -90,6 +113,7 @@ Rectangle { anchors.bottom: parent.bottom anchors.horizontalCenter: parent.horizontalCenter source: "grue.png" - opacity: 0 + opacity: 0.0 + Behavior on opacity { PropertyAnimation { duration: 250 } } } } diff --git a/examples/sensors/grue/import/import.pro b/examples/sensors/grue/import/import.pro index 71e2249d..56623daa 100644 --- a/examples/sensors/grue/import/import.pro +++ b/examples/sensors/grue/import/import.pro @@ -2,12 +2,12 @@ TEMPLATE = lib CONFIG += plugin TARGET = $$qtLibraryTarget(declarative_grue) -TARGETPATH = Grue +DESTDIR = ../Grue QT = core gui qml sensors INCLUDEPATH += $$PWD/../lib -LIBS += -L$$OUT_PWD/../lib -lgruesensor +LIBS += -L$$OUT_PWD/.. -lgruesensor # Shared gruesensor library will be installed in parent directory. # Define rpath so that this plugin will know where to look for it. @@ -15,15 +15,26 @@ unix:!mac: QMAKE_LFLAGS += -Wl,-rpath,\\\$\$ORIGIN/.. SOURCES = main.cpp -DESTPATH=$$[QT_INSTALL_EXAMPLES]/qtsensors/grue/Grue +DESTPATH=$$[QT_INSTALL_EXAMPLES]/sensors/grue/Grue target.path=$$DESTPATH INSTALLS += target qmldir.files=$$PWD/qmldir -qmldir.path=$$DESTPATH +qmldir.path=$$DESTDIR INSTALLS += qmldir OTHER_FILES += \ plugin.json qmldir +copyfile = $$PWD/qmldir +copydest = $$DESTDIR + +# On Windows, use backslashes as directory separators +win32: { + copyfile ~= s,/,\\,g + copydest ~= s,/,\\,g +} + +# Copy the qmldir file to the same folder as the plugin binary +QMAKE_POST_LINK += $$QMAKE_COPY $$quote($$copyfile) $$quote($$copydest) $$escape_expand(\\n\\t) diff --git a/examples/sensors/grue/import/main.cpp b/examples/sensors/grue/import/main.cpp index 5f6c925c..4191d623 100644 --- a/examples/sensors/grue/import/main.cpp +++ b/examples/sensors/grue/import/main.cpp @@ -66,6 +66,7 @@ public: // Register the 1.0 interfaces major = 1; minor = 0; + // @uri Grue qmlRegisterType (package, major, minor, "GrueSensor"); qmlRegisterUncreatableType(package, major, minor, "GrueSensorReading", QLatin1String("Cannot create GrueSensorReading")); } @@ -109,6 +110,7 @@ QT_END_NAMESPACE #include "main.moc" /* + \omit \qmltype GrueSensor \instantiates GrueSensor \inherits Sensor @@ -119,9 +121,11 @@ QT_END_NAMESPACE This type wraps the GrueSensor class. Please see the documentation for GrueSensor for details. + \endomit */ /* + \omit \qmltype GrueSensorReading \instantiates GrueSensorReading \inherits SensorReading @@ -134,9 +138,12 @@ QT_END_NAMESPACE GrueSensorReading for details. This type cannot be directly created. + \endomit */ /* + \omit \qmlproperty qreal Grue1::GrueSensorReading::chanceOfBeingEaten Please see GrueSensorReading::chanceOfBeingEaten for information about this property. + \endomit */ diff --git a/examples/sensors/grue/lib/gruesensor.cpp b/examples/sensors/grue/lib/gruesensor.cpp index c1e98e7d..9787dc5b 100644 --- a/examples/sensors/grue/lib/gruesensor.cpp +++ b/examples/sensors/grue/lib/gruesensor.cpp @@ -44,6 +44,7 @@ IMPLEMENT_READING(GrueSensorReading) /* + \omit \class GrueSensorReading \brief The GrueSensorReading class holds readings from the Grue sensor. @@ -64,6 +65,7 @@ IMPLEMENT_READING(GrueSensorReading) it is, the more likely you are to be eaten by a Grue. The longer you stay in a dark area, the more likely you are to be eaten by a Grue. If you are in a lit room, the probability will be 0 as Grues fear light. + \endomit */ int GrueSensorReading::chanceOfBeingEaten() const @@ -81,25 +83,30 @@ void GrueSensorReading::setChanceOfBeingEaten(int chanceOfBeingEaten) // begin generated code /* + \omit \class GrueFilter \brief The GrueFilter class is a convenience wrapper around QSensorFilter. The only difference is that the filter() method features a pointer to GrueSensorReading instead of QSensorReading. + \endomit */ /* + \omit \fn GrueFilter::filter(GrueSensorReading *reading) Called when \a reading changes. Returns false to prevent the reading from propagating. \sa QSensorFilter::filter() + \endomit */ char const * const GrueSensor::type("GrueSensor"); /* + \omit \class GrueSensor \brief The GrueSensor class is a convenience wrapper around QSensor. @@ -111,12 +118,15 @@ char const * const GrueSensor::type("GrueSensor"); For details about how the sensor works, see \l GrueSensorReading. \sa GrueSensorReading + \endomit */ /* + \omit \fn GrueSensor::GrueSensor(QObject *parent) Construct the sensor as a child of \a parent. + \endomit */ /* @@ -126,11 +136,13 @@ char const * const GrueSensor::type("GrueSensor"); */ /* + \omit \fn GrueSensor::reading() const Returns the reading class for this sensor. \sa QSensor::reading() + \endomit */ // end generated code diff --git a/examples/sensors/grue/lib/gruesensor.h b/examples/sensors/grue/lib/gruesensor.h index c0596ea8..9b9469af 100644 --- a/examples/sensors/grue/lib/gruesensor.h +++ b/examples/sensors/grue/lib/gruesensor.h @@ -74,6 +74,7 @@ private: class Q_GRUE_EXPORT GrueSensor : public QSensor { Q_OBJECT + Q_PROPERTY(GrueSensorReading* reading READ reading) public: explicit GrueSensor(QObject *parent = 0) : QSensor(GrueSensor::type, parent) {} virtual ~GrueSensor() {} diff --git a/examples/sensors/grue/lib/lib.pro b/examples/sensors/grue/lib/lib.pro index 4d12062e..3442abe8 100644 --- a/examples/sensors/grue/lib/lib.pro +++ b/examples/sensors/grue/lib/lib.pro @@ -1,16 +1,15 @@ TEMPLATE = lib TARGET = gruesensor -# avoid going to release/debug subdirectory -win32:DESTDIR = $$OUT_PWD +DESTDIR = $$OUT_PWD/.. DEFINES *= QT_BUILD_GRUE_LIB QT = core sensors -HEADERS += gruesensor.h\ - gruesensor_p.h\ +HEADERS += gruesensor.h \ + gruesensor_p.h -SOURCES += gruesensor.cpp\ +SOURCES += gruesensor.cpp -target.path=$$[QT_INSTALL_EXAMPLES]/qtsensors/grue +target.path=$$[QT_INSTALL_EXAMPLES]/sensors/grue INSTALLS += target diff --git a/examples/sensors/grue/plugin/plugin.pro b/examples/sensors/grue/plugin/plugin.pro index 90453537..8aa87ae7 100644 --- a/examples/sensors/grue/plugin/plugin.pro +++ b/examples/sensors/grue/plugin/plugin.pro @@ -5,21 +5,23 @@ PLUGIN_TYPE = sensors QT = core sensors +DESTDIR = ../$$PLUGIN_TYPE + INCLUDEPATH += $$PWD/../lib -LIBS += -L$$OUT_PWD/../lib -lgruesensor +LIBS += -L$$OUT_PWD/.. -lgruesensor # Shared gruesensor library will be installed in parent directory. # Define rpath so that this plugin will know where to look for it. unix:!mac: QMAKE_LFLAGS += -Wl,-rpath,\\\$\$ORIGIN/.. -HEADERS += gruesensorimpl.h\ +HEADERS += gruesensorimpl.h -SOURCES += gruesensorimpl.cpp\ - main.cpp\ +SOURCES += gruesensorimpl.cpp \ + main.cpp # Install the plugin under Grue example directory -target.path=$$[QT_INSTALL_EXAMPLES]/qtsensors/grue/$$PLUGIN_TYPE +target.path=$$[QT_INSTALL_EXAMPLES]/sensors/grue/$$PLUGIN_TYPE INSTALLS += target OTHER_FILES += \ diff --git a/examples/sensors/grue/qml.pro b/examples/sensors/grue/qml.pro index d7444ca8..ff0963fc 100644 --- a/examples/sensors/grue/qml.pro +++ b/examples/sensors/grue/qml.pro @@ -1,6 +1,7 @@ TEMPLATE = app TARGET = grue QT += quick + SOURCES = main.cpp RESOURCES += \ @@ -11,6 +12,6 @@ app.files = \ $$files(*.qml) \ grue.png -target.path = $$[QT_INSTALL_EXAMPLES]/qtsensors/grue -app.path = $$[QT_INSTALL_EXAMPLES]/qtsensors/grue +target.path = $$[QT_INSTALL_EXAMPLES]/sensors/grue +app.path = $$[QT_INSTALL_EXAMPLES]/sensors/grue INSTALLS += target app -- cgit v1.2.3