From 175a5ab34240c723ad2c2a2d60ad38a01ed6d218 Mon Sep 17 00:00:00 2001 From: Juha Vuolle Date: Fri, 18 Jun 2021 14:39:03 +0300 Subject: QtSensors Qt6 documentation base update The QtSensors module shall be released in 6.2 for the first time in Qt 6 series. This commit updates the basic things of the documentation accordingly. Documentation for sensor support, platform support, and examples shall be updated with followup commits. [ChangeLog][sensorfw] sensorfw removed from docs for now Pick-to: 6.2 Task-number: QTBUG-92512 Change-Id: I7c5e447766109bf9da8ab3cc56fe22ec42dbd875 Reviewed-by: Leena Miettinen Reviewed-by: Lorn Potter --- src/sensors/doc/src/compatmap.qdoc | 23 +----- src/sensors/doc/src/porting.qdoc | 126 ----------------------------- src/sensors/doc/src/qt6-changes.qdoc | 24 +++--- src/sensors/doc/src/qtsensors-modules.qdoc | 82 +++++++++++++++++++ src/sensors/doc/src/qtsensors.qdoc | 49 +++++++---- src/sensors/doc/src/qtsensors5.qdoc | 80 ------------------ 6 files changed, 132 insertions(+), 252 deletions(-) delete mode 100644 src/sensors/doc/src/porting.qdoc create mode 100644 src/sensors/doc/src/qtsensors-modules.qdoc delete mode 100644 src/sensors/doc/src/qtsensors5.qdoc (limited to 'src/sensors/doc/src') diff --git a/src/sensors/doc/src/compatmap.qdoc b/src/sensors/doc/src/compatmap.qdoc index 6db9f708..4f3bb8d4 100644 --- a/src/sensors/doc/src/compatmap.qdoc +++ b/src/sensors/doc/src/compatmap.qdoc @@ -56,9 +56,8 @@ Android Linux iOS - Universal Windows Platform + Windows Generic - Sensorfw TI Sensor Tag @@ -69,7 +68,6 @@ - Altimeter @@ -79,7 +77,6 @@ - Ambient Light Sensor @@ -89,7 +86,6 @@ - Ambient Temperature Sensor @@ -98,7 +94,6 @@ - @@ -108,7 +103,6 @@ - @@ -119,7 +113,6 @@ - Gyroscope @@ -129,7 +122,6 @@ - Holster Sensor @@ -139,7 +131,6 @@ - Humidity Sensor @@ -148,7 +139,6 @@ - @@ -158,7 +148,6 @@ - @@ -168,7 +157,6 @@ - @@ -179,7 +167,6 @@ - Magnetometer @@ -189,7 +176,6 @@ - Orientation Sensor @@ -198,7 +184,6 @@ - @@ -208,7 +193,6 @@ - @@ -218,7 +202,6 @@ - @@ -228,7 +211,6 @@ - @@ -239,7 +221,6 @@ - Tilt Sensor @@ -249,7 +230,6 @@ - Sensor Gestures @@ -258,7 +238,6 @@ - diff --git a/src/sensors/doc/src/porting.qdoc b/src/sensors/doc/src/porting.qdoc deleted file mode 100644 index 6f5d7ea4..00000000 --- a/src/sensors/doc/src/porting.qdoc +++ /dev/null @@ -1,126 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2017 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** 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. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \page qtsensors-porting.html - \title Porting Applications from QtMobility Sensors to Qt Sensors - \brief Explain how to port from QtMobility Sensors to Qt Sensors - \since Qt 5.1 - - \tableofcontents - - \section1 Overview - - The initial release of Qt Sensors (5.0) is generally expected to be source - compatible with QtMobility Sensors 1.2. This document attempts to explain - where things need to be changed in order to port applications to Qt Sensors. - - \section1 QML - - In \c QtMobility, the C++ classes like \c QAccelerometer were directly used as QML types. - In Qt Sensors, there are now separate classes for the QML types, which have no public - C++ API. - - The new QML types in Qt Sensors fix some issues the former QtMobility QML types had, - for example: - \list - \li The reading types now have proper change notifications. - \li \c availableDataRates and \c outputRanges of the \c Sensor type are now proper list types. - \li The \c identifier and \c type properties of \c Sensor can now be used. - \li The \c lux property of \c LightSensorReading has been renamed to \c illuminance. - \li The \c QmlSensors singleton now allows to query for sensor types. - \endlist - - For more information, see the \l {Qt Sensors QML Types}{QML API} documentation. - - \section1 C++ - - The C++ API mainly remained the same as in QtMobility. - - \section2 Includes - - QtMobility Sensors installed headers into a \c Qt Sensors directory. This is - also the directory that Qt Sensors uses. It is therefore expected that includes - that worked with QtMobility Sensors should continue to work. - - For example: - \code - #include - #include - #include - #include - \endcode - - \section2 Macros and Namespace - - QtMobility Sensors was built in a \c QtMobility namespace. This was enabled by - the use of various macros. Qt Sensors does not normally build into a namespace - and the macros from QtMobility no longer exist. - - \list - \li QTM_BEGIN_NAMESPACE - \li QTM_END_NAMESPACE - \li QTM_USE_NAMESPACE - \li QTM_PREPEND_NAMESPACE(x) - \endlist - - Note that Qt can be configured to build into a namespace. If Qt is built in this - way then Qt Sensors is also built into the nominated namespace. However, as this - is optional, the macros for this are typically defined to do nothing. - - \list - \li QT_BEGIN_NAMESPACE - \li QT_END_NAMESPACE - \li QT_USE_NAMESPACE - \li QT_PREPEND_NAMESPACE(x) - \endlist - - \section2 qtimestamp - - qtimestamp was previously defined as an opaque type equivalent to a quint64. It existed - as a class due to an implementation detail. - - In Qt Sensors, the API uses quint64 instead of qtimestamp. qtimestamp still exists as a - typedef so that applications that refer to qtimestamp can be compiled. - - \section1 Project Files - - QtMobility Sensors applications used this in their project files to enable the Sensors API. - - \code - CONFIG += mobility - MOBILITY += sensors - \endcode - - Applications should remove these lines and instead use the following statement to enable - the Qt Sensors API: - - \code - QT += sensors - \endcode -*/ - diff --git a/src/sensors/doc/src/qt6-changes.qdoc b/src/sensors/doc/src/qt6-changes.qdoc index ffde4d19..9cce19d4 100644 --- a/src/sensors/doc/src/qt6-changes.qdoc +++ b/src/sensors/doc/src/qt6-changes.qdoc @@ -43,23 +43,29 @@ \section1 Platform notes - On Windows the Qt6 does not support the UWP (Universal Windows Platform) - any longer. As such the QtSensors now builds on the Win32 + \section2 Windows + + On Windows, sensors are supported in Qt installations that were built with MSVC. + + \section2 sensorfw + + The \l {https://git.sailfishos.org/mer-core/sensorfw}{sensorfw} does not yet have + a Qt 6 port and is therefore not yet supported by sensors in Qt 6. \section1 API changes \section2 Deleted typedef for qtimestamp - The typedef for the historical, QtMobility-era, 'qtimestamp' has been - removed. Use the actual type 'quint64' directly. + The typedef for the historical, QtMobility-era, \c qtimestamp has been + removed. Use the actual type \c quint64 directly. - \section2 Renamed 'sensor' type string to 'sensorType' + \section2 Renamed \c sensor type string to \c sensorType - The subclasses of QSensor implement a \e {char const*} string which defines - the string that identifies the base sensor. This static \e type field + The subclasses of QSensor implement a \c {char const*} string which defines + the string that identifies the base sensor. This static \c type field shadowed the baseclass \l QSensor::type() method, leading to unnecessary - compilation errors and consequent workarounds. The \e type string has been - now renamed as \e sensorType. + compilation errors and consequent workarounds. The \c type string has been + now renamed as \c sensorType. \section2 Renamed LidReading::backLidChanged property to \c backLidClosed diff --git a/src/sensors/doc/src/qtsensors-modules.qdoc b/src/sensors/doc/src/qtsensors-modules.qdoc new file mode 100644 index 00000000..6b4c9713 --- /dev/null +++ b/src/sensors/doc/src/qtsensors-modules.qdoc @@ -0,0 +1,82 @@ +/**************************************************************************** +** +** Copyright (C) 2017 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and The Qt Company. For licensing terms +** and conditions see https://www.qt.io/terms-conditions. For further +** information use the contact form at https://www.qt.io/contact-us. +** +** GNU Free Documentation License Usage +** 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. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: https://www.gnu.org/licenses/fdl-1.3.html. +** $QT_END_LICENSE$ +** +****************************************************************************/ + + +/*! + \module QtSensors + \title Qt Sensors C++ Classes + \qtcmakepackage Sensors + \ingroup modules + \qtvariable sensors + + \brief Provides classes for reading sensor data. + + Mobile devices contain sensor hardware that allow detecting changes in various physical + properties of the device itself or its immediate environment. Examples of device properties + include the angle at which the device is held, whereas environmental properties include for + example the current level of ambient light. +*/ + +/*! + \qmlmodule QtSensors + \title Qt Sensors QML Types + \ingroup qmlmodules + + \brief Provides QML types for reading sensor data. + + \section1 QML Sensors Module API + + QmlSensors is a module API that provides information about currently + available sensors types, identifiers, and the default sensors. + + \qml + import QtSensors + // ... + Component.onCompleted: { + var types = QmlSensors.sensorTypes(); + console.log(types.join(", ")); + } + \endqml + + The documentation for the module API can be found in QmlSensors. + + \section1 QML Sensor Types + + These types represent specific types of sensors. + + Note that most properties come from the abstract \l{Sensor}{Sensor} element. + + \annotatedlist qml-sensors_type + + \section1 QML Reading Types + + The data from a sensor comes via a reading class. + + \annotatedlist qml-sensors_reading + + \section1 All QML Types +*/ diff --git a/src/sensors/doc/src/qtsensors.qdoc b/src/sensors/doc/src/qtsensors.qdoc index b6261233..04329cf9 100644 --- a/src/sensors/doc/src/qtsensors.qdoc +++ b/src/sensors/doc/src/qtsensors.qdoc @@ -34,13 +34,36 @@ The Qt Sensors API provides access to sensor hardware via QML and C++ interfaces. The Qt Sensors API also provides a motion gesture recognition API for devices. - Currently the API is supported on \l{Qt for Android}{Android} and - \l{Qt for iOS}{iOS}. + Currently the API is supported on \l{Qt for Android}{Android}, + \l{Qt for iOS}{iOS}, and \l {Qt for Windows}{Windows (MSVC)}. \section1 Information for Application Writers Applications can access Qt Sensors using QML or C++. + To include the definitions of the module's classes, use the following directive: + + \code + #include + \endcode + + To import the QML types into your application, use the following import statement + in your .qml file: + + \qml + import QtSensors + \endqml + + To link against the module: + + Using cmake: + \include qtsensors-module-use.qdocinc cmakebuild + + Using qmake: + \include qtsensors-module-use.qdocinc qmakebuild + + Further references: + \table \row \li \l {Qt Sensors QML Types}{QML Types} @@ -70,16 +93,9 @@ \li The Qt Sensors - Grue Sensor Example demonstrates creation of a sensor backend \endtable - \section1 Compatibility with QtMobility Sensors API - - Qt Sensors 5.0 (the initial release) is generally expected to be source compatible - with QtMobility Sensors 1.2. - - \table - \row - \li \l {Porting Applications from QtMobility Sensors to Qt Sensors}{Porting Guide} - \li Information about the steps needed to port applications to the Qt Sensors API. - \endtable + \section1 Module Evolution + \l{Changes to Qt Sensors} lists important changes in the module API + and functionality that were done for the Qt 6 series of Qt. \omit \section1 Information for Qt SensorGestures API @@ -115,8 +131,11 @@ \row \li \l {Generic Backend}{Generic Backend} \li Information about the generic sensor backend. - \row - \li \l {Sensorfw Backend}{Sensorfw Backend} - \li Information about the Sensorfw sensor backend. \endtable + + The Qt Sensors module is available under commercial licenses from + \l{The Qt Company}. In addition, it is available under free software licenses: + The \l{GNU Lesser General Public License, version 3}, or + the \l{GNU General Public License, version 2}. + See \l{Qt Licensing} for further details. */ diff --git a/src/sensors/doc/src/qtsensors5.qdoc b/src/sensors/doc/src/qtsensors5.qdoc deleted file mode 100644 index 403f3282..00000000 --- a/src/sensors/doc/src/qtsensors5.qdoc +++ /dev/null @@ -1,80 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2017 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** 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. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ - - -/*! - \module QtSensors - \title Qt Sensors C++ Classes - \ingroup modules - \qtvariable sensors - - \brief Provides classes for reading sensor data. - - Mobile devices contain sensor hardware that allow detecting changes in various physical - properties of the device itself or its immediate environment. Examples of device properties - include the angle at which the device is held, whereas environmental properties include for - example the current level of ambient light. -*/ - -/*! - \qmlmodule QtSensors 5.\QtMinorVersion - \title Qt Sensors QML Types - \ingroup qmlmodules - - \brief Provides types for reading sensor data. - - \section1 QML Module API - - If the module is imported into a namespace, some additional methods become available. - - \qml \QtMinorVersion - import QtSensors 5.\1 - // ... - Component.onCompleted: { - var types = QmlSensors.sensorTypes(); - console.log(types.join(", ")); - } - \endqml - - The documentation for the module API can be found in QmlSensors. - - \section1 QML Sensor Types - - These types represent specific types of sensors. - - Note that most properties come from the abstract \l{Sensor}{Sensor} element. - - \annotatedlist qml-sensors_type - - \section1 QML Reading Types - - The data from a sensor comes via a reading class. - - \annotatedlist qml-sensors_reading - - \section1 All QML Types -*/ -- cgit v1.2.3