diff options
Diffstat (limited to 'src/positioning/doc/src')
| -rw-r--r-- | src/positioning/doc/src/cpp-position.qdoc | 191 | ||||
| -rw-r--r-- | src/positioning/doc/src/cpp-qml-positioning.qdoc | 55 | ||||
| -rw-r--r-- | src/positioning/doc/src/examples/declarative-flickr.qdoc | 85 | ||||
| -rw-r--r-- | src/positioning/doc/src/examples/logfilepositionsource.qdoc | 87 | ||||
| -rw-r--r-- | src/positioning/doc/src/examples/qtpositioning-examples.qdoc | 38 | ||||
| -rw-r--r-- | src/positioning/doc/src/examples/weatherinfo.qdoc | 109 | ||||
| -rw-r--r-- | src/positioning/doc/src/qml-position.qdoc | 107 | ||||
| -rw-r--r-- | src/positioning/doc/src/qtpositioning-plugins.qdoc | 82 | ||||
| -rw-r--r-- | src/positioning/doc/src/qtpositioning-qml.qdoc | 65 | ||||
| -rw-r--r-- | src/positioning/doc/src/qtpositioning.qdoc | 124 |
10 files changed, 943 insertions, 0 deletions
diff --git a/src/positioning/doc/src/cpp-position.qdoc b/src/positioning/doc/src/cpp-position.qdoc new file mode 100644 index 00000000..75c2e30e --- /dev/null +++ b/src/positioning/doc/src/cpp-position.qdoc @@ -0,0 +1,191 @@ +/**************************************************************************** +** +** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/legal +** +** 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 Digia. For licensing terms and +** conditions see http://qt.digia.com/licensing. For further information +** use the contact form at http://qt.digia.com/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: http://www.gnu.org/copyleft/fdl.html. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! +\page location-positioning-cpp.html + +\title Positioning (C++) + +\brief The Location Positioning API enables location positioning by means of +GPS or an NMEA data source. + +\section1 Positioning + +The Positioning component of the Qt Location API is about the geographical position, size +and address of some place. Positioning contains a QGeoCoordinate class, containing latitude, longitude and altitude in meters. QGeoLocation contains a QGeoCoordinate plus address +and size information (a bounding box) so that positions can be more than mathematical points. +Movement into or out of the defined bounding box areas can be monitored. The API +also allows the developer to control the source of the positional information +as well. + +Location data involves a precisely specified position on the Earth's +surface \unicode {0x2014} as provided by a latitude-longitude coordinate +\unicode {0x2014} along with associated data, such as: + + \list + \li The date and time at which the position was reported + \li The velocity of the device that reported the position + \li The altitude of the reported position (height above sea level) + \li The bearing of the device in degrees, relative to true north + \endlist + +This data can be extracted through a variety of methods. One of the most +well known methods of positioning is GPS (Global Positioning System), a +publicly available system that uses radiowave signals received from +Earth-orbiting satellites to calculate the precise position and time of +the receiver. Another popular method is 'Cell Identifier Positioning', which uses +the cell identifier of the cell site that is currently serving the receiving +device to calculate its approximate location. These and other positioning +methods can all be used with the Location API; the only requirement for a +location data source within the API is that it provides a +latitude-longitude coordinate with a date/time value, with the option of +providing the other attributes listed above. + + +Location data sources are created by subclassing QGeoPositionInfoSource and +providing QGeoPositionInfo objects through the +QGeoPositionInfoSource::positionUpdated() signal. Clients that require +location data can connect to the +\l{QGeoPositionInfoSource::positionUpdated()}{positionUpdated()} signal and +call \l{QGeoPositionInfoSource::startUpdates()}{startUpdates()} or +\l{QGeoPositionInfoSource::requestUpdate()}{requestUpdate()} to trigger the +distribution of location data. The location data distribution can be stopped by +calling the \l {QGeoPositionInfoSource::stopUpdates()}{stopUpdates()} function. + +A default position source may be available on some platforms. Call +QGeoPositionInfoSource::createDefaultSource() to create an instance of the default +position source; the method returns 0 if no default source is available for +the platform. + +If a problem occurs with access to the information source then an +\l {QGeoPositionInfoSource::error()}{error()} signal is emitted. + +The QGeoAreaMonitor class enables client applications to be notified when +the receiving device has moved in or out of a particular area, as specified +by a coordinate and radius. If the platform provides built-in support for +area monitoring, QGeoAreaMonitor::createDefaultMonitor() returns an instance of +the default area monitor. + +Satellite information can also be distributed through the +QGeoSatelliteInfoSource class. Call QGeoSatelliteInfoSource::createDefaultSource() to +create an instance of the default satellite data source for the platform, +if one is available. Alternatively, clients can subclass it to provide a +custom satellite data source. + + + +\section2 Requesting Location Data from Data Sources + +To receive data from a source, connect to its +\l{QGeoPositionInfoSource::positionUpdated()}{positionUpdated()} signal, +then call either \l{QGeoPositionInfoSource::startUpdates()}{startUpdates()} +or \l{QGeoPositionInfoSource::requestUpdate()}{requestUpdate()} to begin. + +Here is an example of a client that receives data from the default location +data source, as returned by QGeoPositionInfoSource::createDefaultSource(): + +\code +class MyClass : public QObject +{ + Q_OBJECT +public: + MyClass(QObject *parent = 0) + : QObject(parent) + { + QGeoPositionInfoSource *source = QGeoPositionInfoSource::createDefaultSource(this); + if (source) { + connect(source, SIGNAL(positionUpdated(QGeoPositionInfo)), + this, SLOT(positionUpdated(QGeoPositionInfo))); + source->startUpdates(); + } + } + +private slots: + void positionUpdated(const QGeoPositionInfo &info) + { + qDebug() << "Position updated:" << info; + } +}; + +\endcode + +\section2 Controlling Aspects of Data Sources + +The QGeoPositionInfoSource::setUpdateInterval() method can be used to +control the rate at which position updates are received. For example, if +the client application only requires updates once every 30 seconds, it can +call \c setUpdateInterval(30000). (If no update interval is set, or +\l {QGeoPositionInfoSource::}{setUpdateInterval()} is called with a value of 0, the source uses a default +interval or some other internal logic to determine when updates should be +provided.) + +QGeoPositionInfoSource::setPreferredPositioningMethods() enables client +applications to request that a certain type of positioning method be used. +For example, if the application prefers to use only satellite positioning, +which offers fairly precise outdoor positioning but can be a heavy user of +power resources, it can call this method with the +QGeoPositionInfoSource::SatellitePositioningMethods value. However, this +method should only be used in specialized client applications; in most +cases, the default positioning methods should not be changed, as a source +may internally use a variety of positioning methods that can be useful to +the application. + +\section2 NMEA Data + +\l {http://en.wikipedia.org/wiki/NMEA_0183}{NMEA} is a common text-based +protocol for specifying navigational data. For convenience, the +QNmeaPositionInfoSource is provided to enable client applications to read +and distribute NMEA data in either real-time mode (for example, when +streaming from a GPS device) or simulation mode (for example, when reading +from a NMEA log file). In simulation mode, the source will emit updates +according to the time stamp of each NMEA sentence to produce a "replay" +of the recorded data. + +Generally, the capabilities provided by the default position source as +returned by QGeoPositionInfoSource::createDefaultSource(), along with the +QNmeaPositionInfoSource class, are sufficient for retrieving location +data. However, in some cases developers may wish to write their own custom +location data source. + +The \l {Log File Position Source (C++)} example demonstrates how to subclass QGeoPositionInfoSource +to create a custom positioning source. + + +\section1 Examples + +\section3 \b{Flickr Example} + +The \l{Flickr QML}{Flickr Example} uses the Location to download thumbnail +images from Flickr relevant to the current location. + + + +\section1 Positioning Classes + +\annotatedlist QtPositioning-positioning + +*/ diff --git a/src/positioning/doc/src/cpp-qml-positioning.qdoc b/src/positioning/doc/src/cpp-qml-positioning.qdoc new file mode 100644 index 00000000..4ccd8510 --- /dev/null +++ b/src/positioning/doc/src/cpp-qml-positioning.qdoc @@ -0,0 +1,55 @@ +/**************************************************************************** +** +** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/legal +** +** 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 Digia. For licensing terms and +** conditions see http://qt.digia.com/licensing. For further information +** use the contact form at http://qt.digia.com/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: http://www.gnu.org/copyleft/fdl.html. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! +\page positioning-cpp-qml.html +\title Interfaces between C++ and QML Code in Qt Positioning + +\brief Some of the providing QtPositioning QML types providing interfaces to access and modify properties in C++. + +\section2 Address - QGeoAddress +\target geoaddress +The \l {QtPositioning5::Address::address} {Address.address} property is used to provide an interface between C++ and QML code. First a pointer to a +Address object must be obtained from C++, then use the \l {QObject::property()}{property()} and +\l {QObject::setProperty()}{setProperty()} functions to get and set the \c address property. +The following gets the QGeoAddress representing this object from C++: +\snippet cpp/cppqml.cpp Address get +The following sets the properties of this object based on a QGeoAddress object from C++: +\snippet cpp/cppqml.cpp Address set + + +\section2 Location - QGeoLocation +\target location +The \l {Location::location} {Location.location} property is used to provide an interface between C++ and QML code. First a pointer to a +Location object must be obtained from C++, then use the \l {QObject::property()}{property()} and +\l {QObject::setProperty()}{setProperty()} functions to get and set the \c location property. +The following gets the QGeoLocation representing this object from C++: +\snippet cpp/cppqml.cpp Location get +The following sets the properties of this object based on a QGeoLocation object from C++: +\snippet cpp/cppqml.cpp Location set + +*/ diff --git a/src/positioning/doc/src/examples/declarative-flickr.qdoc b/src/positioning/doc/src/examples/declarative-flickr.qdoc new file mode 100644 index 00000000..c68797b0 --- /dev/null +++ b/src/positioning/doc/src/examples/declarative-flickr.qdoc @@ -0,0 +1,85 @@ +/**************************************************************************** +** +** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/legal +** +** 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 Digia. For licensing terms and +** conditions see http://qt.digia.com/licensing. For further information +** use the contact form at http://qt.digia.com/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: http://www.gnu.org/copyleft/fdl.html. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example declarative/flickr + \title Flickr (QML) + \ingroup qtpositioning-examples + + \brief The Flickr example shows how to use the user's current position to + fetch local content from a web service. + + This is a small example, illustrating one of the very core parts of the + Qt Positioning API: the ability to retrieve and use the user's current + geographic position. + + Key QML types shown in this example: + \list + \li \l{QtPositioning5::PositionSource}{PositionSource} + \li \l{XmlListModel}{XmlListModel} + \endlist + + \image qml-flickr-1.jpg + + \section2 Retrieving the Current Position + + Retrieving the user's current position is achieved using the PositionSource + type. In this example, we instantiate the PositionSource as part of the + GeoTab component (the floating "window" describing current position and + status). + + \snippet flickr/flickrmobile/GeoTab.qml possrc + + When the "Locate and update" button is pressed, we first interrogate the + PositionSource to check if it has an available backend for positioning + data. If it does not, we fall back to using a pre-recorded NMEA log + for demonstration. We then instruct the PositionSource to update. + + \snippet flickr/flickrmobile/GeoTab.qml locatebutton-top + \snippet flickr/flickrmobile/GeoTab.qml locatebutton-clicked + + To share the new position data with the rest of the application, we use + properties that we have created on the GeoTab component: + + \snippet flickr/flickrmobile/GeoTab.qml props + + \section2 Using the Current Position + + The longitude and latitude values retrieved here are eventually set on + in properties on the RestModel component. The RestModel is an XmlListModel, + which retrieves XML data from a URL and creates a data model by performing + XPath queries on it. + + In this case, it retrieves data from the Flickr REST API online, based on + our current position + + \snippet flickr/flickrcommon/RestModel.qml restmodel + + This model data is then shown in a variety of Qt Quick views to produce + the example application. + +*/ diff --git a/src/positioning/doc/src/examples/logfilepositionsource.qdoc b/src/positioning/doc/src/examples/logfilepositionsource.qdoc new file mode 100644 index 00000000..f69c1dd1 --- /dev/null +++ b/src/positioning/doc/src/examples/logfilepositionsource.qdoc @@ -0,0 +1,87 @@ +/**************************************************************************** +** +** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/legal +** +** 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 Digia. For licensing terms and +** conditions see http://qt.digia.com/licensing. For further information +** use the contact form at http://qt.digia.com/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: http://www.gnu.org/copyleft/fdl.html. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! +\example logfilepositionsource +\title Log File Position Source (C++) +\ingroup qtpositioning-examples + +\brief The Logfile Position Source shows how to create and work with a custom NMEA position source, + for platforms without GPS. + +The data is read from a file which has positional data in NMEA format. The resulting time and +position information is then displayed to the screen as simple text in date/time and +latitude/longitude format. + +This example class reads position data from a text file, \e log.txt. The file specifies position +data using a simple text format: it contains one position update per line, where each line contains +a date/time, a latitude and a longitude, separated by spaces. The date/time is in ISO 8601 format +and the latitude and longitude are in degrees decimal format. Here is an excerpt from \e log.txt: + +\code +2009-08-24T22:25:01 -27.576082 153.092415 +2009-08-24T22:25:02 -27.576223 153.092530 +2009-08-24T22:25:03 -27.576364 153.092648 +\endcode + +The class reads this data and distributes it via the +\l{QGeoPositionInfoSource::positionUpdated()}{positionUpdated()} signal. + +Here is the definition of the \c LogFilePositionSource class: + +\quotefromfile logfilepositionsource/logfilepositionsource.h +\skipto class LogFilePositionSource +\printuntil }; + +The main methods overrided by the subclass are: + +\list + \li \l{QGeoPositionInfoSource::startUpdates()}{startUpdates()}: called by client applications + to start regular position updates. + \li \l{QGeoPositionInfoSource::stopUpdates()}{stopUpdates()}: called by client applications to + stop regular position updates. + \li \l{QGeoPositionInfoSource::requestUpdate()}{requestUpdate()}: called by client applications + to request a single update, with a specified timeout. +\endlist + +When a position update is available, the subclass emits the +\l{QGeoPositionInfoSource::positionUpdated()}{positionUpdated()} signal. + +Here are the key methods in the class implementation: + +\quotefromfile logfilepositionsource/logfilepositionsource.cpp +\skipto LogFilePositionSource::LogFilePositionSource +\printuntil /^\}/ +\skipto LogFilePositionSource::startUpdates +\printuntil /^\}/ +\skipto LogFilePositionSource::stopUpdates +\printuntil /^\}/ +\skipto LogFilePositionSource::requestUpdate +\printuntil /^\}/ +\printuntil LogFilePositionSource::readNextPosition +\printuntil /^\}/ +*/ diff --git a/src/positioning/doc/src/examples/qtpositioning-examples.qdoc b/src/positioning/doc/src/examples/qtpositioning-examples.qdoc new file mode 100644 index 00000000..ac1d79ec --- /dev/null +++ b/src/positioning/doc/src/examples/qtpositioning-examples.qdoc @@ -0,0 +1,38 @@ +/**************************************************************************** +** +** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/legal +** +** 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 Digia. For licensing terms and +** conditions see http://qt.digia.com/licensing. For further information +** use the contact form at http://qt.digia.com/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: http://www.gnu.org/copyleft/fdl.html. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \group qtpositioning-examples + \title Qt Positioning Examples + \brief Examples for the Qt Positioning module + \ingroup all-examples + \ingroup qtpositioning + + These are the Qt Positioning examples. + +*/ + diff --git a/src/positioning/doc/src/examples/weatherinfo.qdoc b/src/positioning/doc/src/examples/weatherinfo.qdoc new file mode 100644 index 00000000..0c98cc04 --- /dev/null +++ b/src/positioning/doc/src/examples/weatherinfo.qdoc @@ -0,0 +1,109 @@ +/**************************************************************************** +** +** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/legal +** +** 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 Digia. For licensing terms and +** conditions see http://qt.digia.com/licensing. For further information +** use the contact form at http://qt.digia.com/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: http://www.gnu.org/copyleft/fdl.html. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example weatherinfo + \title Weather Info (C++/QML) + + \brief The Weather Info example shows how to use the user's current position + to retrieve local content from a web service in a C++ plugin for QML. + + \ingroup qtpositioning-examples + + Key Qt Positioning classes used in this example: + + \list + \li \l{QGeoPositionInfo} + \li \l{QGeoPositionInfoSource} + \endlist + + \image ../images/example-weatherinfo.png + + The key part of this example is the application's data model, contained + in the WeatherData and AppModel classes. WeatherData represents the weather + information taken from the HTTP service. It is a simple data class, but we + give it Q_PROPERTies to expose it nicely to QML, later. + + \snippet weatherinfo/appmodel.h 0 + \snippet weatherinfo/appmodel.h 1 + + AppModel models the state of the entire application. At startup, the + application first begins by waiting for network connectivity. We do + this using the QNetworkConfigurationManager and QNetworkSession family + of C++ APIs. + + \snippet weatherinfo/appmodel.cpp 0 + \snippet weatherinfo/appmodel.cpp 1 + + Once the network session is open, we proceed to get the platform's + default position source using QGeoPositionInfo::createDefaultSource() + + \snippet weatherinfo/appmodel.cpp 2 + + If no default source is available, we take a static position and fetch + weather for that. If, however, we do have a position source, we connect + its positionUpdated() signal to a slot on the AppModel and call + startUpdates(), which begins regular updates of device position. + + When a position update is received, we use the longitude and latitude + of the returned coordinate to retrieve the current "city" name for use + in the weather lookup. + + \snippet weatherinfo/appmodel.cpp 3 + + To inform the UI about this process, the cityChanged() signal is emitted + when a new city is used, and the weatherChanged() signal whenever a + weather update occurs. + + \snippet weatherinfo/appmodel.h 2 + \snippet weatherinfo/appmodel.h 3 + \snippet weatherinfo/appmodel.h 4 + + We use a QQmlListProperty for the weather forecast information, + which contains the next 4 days of forecast weather. This makes it + easy to access from QML. + + To expose these to the QML UI layer, we use the qmlRegisterType() + function. We call this once for each type we wish to register, before + loading the actual QML file. + + \snippet weatherinfo/main.cpp 0 + \snippet weatherinfo/main.cpp 1 + + Finally, in the actual QML, we instantiate the AppModel. + + \snippet weatherinfo/weatherinfo.qml 0 + \snippet weatherinfo/weatherinfo.qml 1 + \snippet weatherinfo/weatherinfo.qml 2 + + Once instantiated like this, we can use its properties elsewhere in the + QML document: + + \snippet weatherinfo/weatherinfo.qml 3 + \snippet weatherinfo/weatherinfo.qml 4 + +*/ diff --git a/src/positioning/doc/src/qml-position.qdoc b/src/positioning/doc/src/qml-position.qdoc new file mode 100644 index 00000000..850bdd35 --- /dev/null +++ b/src/positioning/doc/src/qml-position.qdoc @@ -0,0 +1,107 @@ +/**************************************************************************** +** +** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/legal +** +** 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 Digia. For licensing terms and +** conditions see http://qt.digia.com/licensing. For further information +** use the contact form at http://qt.digia.com/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: http://www.gnu.org/copyleft/fdl.html. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! +\page location-positioning-qml.html + +\title Positioning (QML) + +\brief The Location Positioning API enables location positioning by means of +GPS or an NMEA data source. + +\section1 Location Positioning + +Location data involves a precisely specified position on the Earth's +surface \unicode {0x2014} as provided by a latitude-longitude coordinate +\unicode {0x2014} along with associated data, such as: + + \list + \li The date and time at which the position was reported + \li The velocity of the device that reported the position + \li The altitude of the reported position (height above sea level) + \li The bearing of the device in degrees, relative to true north + \endlist + +For more information see +\l {http://en.wikipedia.org/wiki/Geographic_coordinate}{Geographic Coordinate}. + +This data can be extracted through a variety of methods. One of the most +well known methods of positioning is GPS (Global Positioning System), a +publicly available system that uses radiowave signals received from +Earth-orbiting satellites to calculate the precise position and time of +the receiver. Another popular method is 'Cell Identifier Positioning', which uses +the cell identifier of the cell site that is currently serving the receiving +device to calculate its approximate location. These and other positioning +methods can all be used with the Location API; the only requirement for a +location data source within the API is that it provides a +latitude-longitude coordinate with a date/time value, with the option of +providing the other attributes listed above. + +\section2 Coordinate + +The \l {coordinate} is a basic unit of geographical information. The +\l {coordinate} type has attributes to hold the \c {latitude}, +\c longitude and \c altitude. + +\section2 Position + +The three dimensional position of an object such as a mobile device can be specified by giving +the latitude, longitude and altitude. That is the values held in the +l\ {coordinate} type. Additionally for computation of future +positions we would like to know if the object is moving, what \l {Position::speed}{speed} it is +doing and what is the \l {Position::timestamp}{timestamp} of the last position data. Position +therefore includes values for the \l {Position::coordinate}{coordinate}, +\l {Position::speed}{speed} and a \l {Position::timestamp}{timestamp}. \l Position also takes +responsibility for validation of sensible values for these properties. These are exposed as +the \l {Position::latitudeValid}{latitudeValid}, \l {Position::longitudeValid}{longitudeValid}, +\l {Position::altitudeValid}{altitudeValid}, \l {Position::speedValid}{speedValid}, +\l {Position::horizontalAccuracyValid}{horizontalAccuracyValid}, and +\l {Position::verticalAccuracyValid}{verticalAccuracyValid} properties. + + +\section2 PositionSource + +We have a Position type, a \l {coordinate} type but where does the data come from? +Also it is a good idea to be able to indicate alternative sources. +Perhaps instead of directly picking up GPS satellites it might be desirable to do +some testing using a datafile. + +The \l PositionSource type provides the developer with control, +within the limits allowed by the platform, of the source of the +geographical data. Apart from tradtional sources such as GPS and cell data the positional data can be +sourced from a logfile which is in NMEA format. + +\l {http://en.wikipedia.org/wiki/NMEA}{NMEA} is a common text-based protocol for specifying navigational data. For convenience, the \l {PositionSource::nmeaSource}{nmeaSource} property is provided to enable QML applications to read NMEA data from a log file, the source will emit updates according to the time stamp of each NMEA sentence to produce a "replay" of the recorded data. + + + +\section2 \b{Flickr Example} + +The \l{Flickr (QML)}{Flickr Example} uses the Location to download thumbnail +images from Flickr relevant to the current location. + +*/ diff --git a/src/positioning/doc/src/qtpositioning-plugins.qdoc b/src/positioning/doc/src/qtpositioning-plugins.qdoc new file mode 100644 index 00000000..1ed1be1a --- /dev/null +++ b/src/positioning/doc/src/qtpositioning-plugins.qdoc @@ -0,0 +1,82 @@ +/**************************************************************************** +** +** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/legal +** +** 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 Digia. For licensing terms and +** conditions see http://qt.digia.com/licensing. For further information +** use the contact form at http://qt.digia.com/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: http://www.gnu.org/copyleft/fdl.html. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! +\page qtpositioning-plugins.html +\title Qt Positioning service plugins +\brief Implementing Qt Positioning plugins + +Qt Positioning provides the majority of its functionality through plugins. This +document outlines how to develop a new position plugin. + +\section1 Plugin description + +Each plugin is described by a json file. The json describes the plugins capabilities and +version. Below is an example of a json file used by the postionpoll plugin: + +\quotefile ../../../plugins/position/positionpoll/plugin.json + +The entries have the following meaning: + +\table + \header + \li Key + \li Description + \row + \li Keys + \li The unique name/key of the plugin. Each position plugin must have a unique name. + \row + \li Provider + \li The provider name of the services. Multiple plugins may have the same name. + In such cases the Version string will be used to further distinguish the plugins. + \row + \li Position + \li Set to \c true if the plugin implements a \l QGeoPositionInfoSource. + \row + \li Satellite + \li Set to \c true if the plugin implements a \l QGeoSatelliteInfoSource. + \row + \li Monitor + \li Set to \c true if the plugin implements a \l QGeoAreaMonitor. + \row + \li Priority + \li The plugin priority. If multiple plugins have the same provider name, the plugin + with the higest priority will be used. +\endtable + +\section1 Implementing Plugins + +A plugin implementer needs to subclass \l QGeoPositionInfoSourceFactory and override one or more of +its functions. If a plugin does not support a specific feature the function should return 0 or +utilize the default implementation. + +\list + \li \l QGeoPositionInfoSourceFactory::areaMonitor() + \li \l QGeoPositionInfoSourceFactory::positionInfoSource() + \li \l QGeoPositionInfoSourceFactory::satelliteInfoSource() +\endlist +*/ diff --git a/src/positioning/doc/src/qtpositioning-qml.qdoc b/src/positioning/doc/src/qtpositioning-qml.qdoc new file mode 100644 index 00000000..ba35cb89 --- /dev/null +++ b/src/positioning/doc/src/qtpositioning-qml.qdoc @@ -0,0 +1,65 @@ +/**************************************************************************** +** +** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/legal +** +** 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 Digia. For licensing terms and +** conditions see http://qt.digia.com/licensing. For further information +** use the contact form at http://qt.digia.com/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: http://www.gnu.org/copyleft/fdl.html. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \qmlmodule QtPositioning 5.0 + \title Qt Positioning QML Types + \ingroup qmlmodules + \brief Provides QML types for position information + +\section1 Overview + +The identifying string for this module is \e QtPositioning. To use include the following import +statement in the QML file. + +\snippet doc_src_qtpositioning.qml import + +\section2 Positioning QML Concepts + +Position information can come from a variety of sources including satellites, +wifi, text files and so on. The position is described by the latitude, +the longitude, and the altitude in meters. For more information see +\l {http://en.wikipedia.org/wiki/Geographic_coordinate}{Geographic Coordinate}. + +The QML position is stored in a \l {coordinate} which contains the +latitude, longitude and altitude of the device. The \l {QtPositioning5::Location}{Location} contains +this \l {coordinate} and adds an address, it also has a bounding box which +defines the recommended viewing region when displaying the location. + +Now that the device has a position, with regular updates the API can determine +the speed and heading of the device. It can also define a box or a circle that can +produce a notification when the device either leaves or enters that region. + +More detailed information retrieving the current position can be found under +{Positioning (QML)}{Location Positioning via QML} + +\section1 Basic Types + +\annotatedlist qml-QtPositioning5-basictypes + +\section1 Alphabetical Listing of all QML Types +*/ diff --git a/src/positioning/doc/src/qtpositioning.qdoc b/src/positioning/doc/src/qtpositioning.qdoc new file mode 100644 index 00000000..95b3fecc --- /dev/null +++ b/src/positioning/doc/src/qtpositioning.qdoc @@ -0,0 +1,124 @@ +/**************************************************************************** +** +** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/legal +** +** 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 Digia. For licensing terms and +** conditions see http://qt.digia.com/licensing. For further information +** use the contact form at http://qt.digia.com/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: http://www.gnu.org/copyleft/fdl.html. +** $QT_END_LICENSE$ +** +****************************************************************************/ + + + + +/*! + \module QtPositioning + \title Qt Positioning C++ Classes + \ingroup modules + \qtvariable location + + \brief The Positioning module provides positioning information via QML and C++ interfaces. + + To load the Qt Positioning module, add the following statement to your .qml files + + \code + import QtPositioning 5.0 + \endcode + + For C++ projects include the header appropriate for the current use case, + for example applications using routes may use + + \code #include <QGeoCoordinate> \endcode + + The .pro file should have the \e positioning keyword added + + \code QT += positioning \endcode + + + See more in the \l{Qt Positioning}{Qt Positioning Overview}. + +*/ + + + +/*! +\page qtpositioning-index.html +\title Qt Positioning +\brief The Qt Positioning API provides positioning information via QML and C++ interfaces. +\ingroup technology-apis + +The Qt Positioning API provides positioning information via QML and C++ interfaces. + +\section1 Overview + +The Qt Positioning API gives developers the ability to determine a position by +using a variety of possible sources, including satellite, or wifi, or text file, +and so on. That information can then be used to for example determine a position +on a map. In addition satellite information can be retrieved and area based monitoring +can be performed. + +\section1 Getting Started + +To load the Qt Positioning module, add the following statement to your .qml files + +\code + import QtPositioning 5.0 +\endcode + +For C++ projects include the header appropriate for the current use case, +for example applications using routes may use + +\code #include <QGeoCoordinate> \endcode + +The .pro file should have the \e positioning keyword added + +\code QT += positioning \endcode + +\section1 Related information +\section2 Overview + +Positioning includes all the functionality necessary to find and work with geographic +coordinates. It can use a variety of external sources of information, including GPS. This +provides us with a coordinate and altitude for the device with additional features +such as speed and direction. This provides the fundamental location information used in the API. + +\section2 References +\table +\row + \li Positioning introduction: + \li \l{Positioning (QML)}{for QML} + \li \l{Positioning (C++)}{for C++} +\row + \li API references: + \li \l {Qt Positioning QML Types}{for QML} + \li \l {Qt Positioning C++ Classes}{for C++} +\row + \li Position plugins: + \li \l {Qt Positioning service plugins} +\endtable + +\section2 Examples + +\list + \li \l {Flickr (QML)} + \li \l {Log File Position Source (C++)} + \li \l {Weather Info (C++/QML)} +\endlist +*/ |