From 3a9590241cf54eccb9d28957c3d58268e0d23b60 Mon Sep 17 00:00:00 2001 From: Michal Klocek Date: Wed, 24 Feb 2016 12:26:27 +0100 Subject: Update examples documentation location MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The current way of documenting examples is to include qdoc and images source into example directory. Fix examples in location and positioning. Replace planespotter.jpg with png. Change-Id: I4eeacbfa575e7ae3ef747703348f2f201899e548 Reviewed-by: Topi Reiniö --- .../geoflickr/doc/images/qml-flickr-1.jpg | Bin 0 -> 66794 bytes .../positioning/geoflickr/doc/src/geoflickr.qdoc | 87 ++++++++++++++++ .../doc/src/logfilepositionsource.qdoc | 87 ++++++++++++++++ .../doc/images/example-satelliteinfo.png | Bin 0 -> 27371 bytes .../satelliteinfo/doc/src/satelliteinfo.qdoc | 75 ++++++++++++++ .../weatherinfo/doc/images/example-weatherinfo.png | Bin 0 -> 82081 bytes .../weatherinfo/doc/src/weatherinfo.qdoc | 113 +++++++++++++++++++++ 7 files changed, 362 insertions(+) create mode 100644 examples/positioning/geoflickr/doc/images/qml-flickr-1.jpg create mode 100644 examples/positioning/geoflickr/doc/src/geoflickr.qdoc create mode 100644 examples/positioning/logfilepositionsource/doc/src/logfilepositionsource.qdoc create mode 100644 examples/positioning/satelliteinfo/doc/images/example-satelliteinfo.png create mode 100644 examples/positioning/satelliteinfo/doc/src/satelliteinfo.qdoc create mode 100644 examples/positioning/weatherinfo/doc/images/example-weatherinfo.png create mode 100644 examples/positioning/weatherinfo/doc/src/weatherinfo.qdoc (limited to 'examples/positioning') diff --git a/examples/positioning/geoflickr/doc/images/qml-flickr-1.jpg b/examples/positioning/geoflickr/doc/images/qml-flickr-1.jpg new file mode 100644 index 00000000..42514ff0 Binary files /dev/null and b/examples/positioning/geoflickr/doc/images/qml-flickr-1.jpg differ diff --git a/examples/positioning/geoflickr/doc/src/geoflickr.qdoc b/examples/positioning/geoflickr/doc/src/geoflickr.qdoc new file mode 100644 index 00000000..6d043d4d --- /dev/null +++ b/examples/positioning/geoflickr/doc/src/geoflickr.qdoc @@ -0,0 +1,87 @@ +/**************************************************************************** +** +** Copyright (C) 2015 The Qt Company Ltd. +** Contact: http://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 http://www.qt.io/terms-conditions. For further +** information use the contact form at http://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: http://www.gnu.org/copyleft/fdl.html. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example geoflickr + \title GeoFlickr (QML) + \ingroup qtpositioning-examples + + \brief The GeoFlickr 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 + \l{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{QtPositioning::PositionSource}{PositionSource} + \li \l{XmlListModel}{XmlListModel} + \endlist + + \image qml-flickr-1.jpg + + \include examples-run.qdocinc + + \section1 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 geoflickr/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 geoflickr/flickrmobile/GeoTab.qml locatebutton-top + \snippet geoflickr/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 geoflickr/flickrmobile/GeoTab.qml props + + \section1 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 geoflickr/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/examples/positioning/logfilepositionsource/doc/src/logfilepositionsource.qdoc b/examples/positioning/logfilepositionsource/doc/src/logfilepositionsource.qdoc new file mode 100644 index 00000000..6b008af6 --- /dev/null +++ b/examples/positioning/logfilepositionsource/doc/src/logfilepositionsource.qdoc @@ -0,0 +1,87 @@ +/**************************************************************************** +** +** Copyright (C) 2015 The Qt Company Ltd. +** Contact: http://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 http://www.qt.io/terms-conditions. For further +** information use the contact form at http://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: 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/examples/positioning/satelliteinfo/doc/images/example-satelliteinfo.png b/examples/positioning/satelliteinfo/doc/images/example-satelliteinfo.png new file mode 100644 index 00000000..aa9a217c Binary files /dev/null and b/examples/positioning/satelliteinfo/doc/images/example-satelliteinfo.png differ diff --git a/examples/positioning/satelliteinfo/doc/src/satelliteinfo.qdoc b/examples/positioning/satelliteinfo/doc/src/satelliteinfo.qdoc new file mode 100644 index 00000000..51e40867 --- /dev/null +++ b/examples/positioning/satelliteinfo/doc/src/satelliteinfo.qdoc @@ -0,0 +1,75 @@ +/**************************************************************************** +** +** Copyright (C) 2015 The Qt Company Ltd. +** Contact: http://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 http://www.qt.io/terms-conditions. For further +** information use the contact form at http://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: http://www.gnu.org/copyleft/fdl.html. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example satelliteinfo + \title SatelliteInfo (C++/QML) + + \brief The SatelliteInfo example shows how the available satellites + at the user's current position and marks the satellites + currently contributing to the GPS fix as pink. + + \ingroup qtpositioning-examples + + Key \l{Qt Positioning} classes used in this example: + + \list + \li \l{QGeoSatelliteInfo} + \li \l{QGeoSatelliteInfoSource} + \endlist + + \image ../images/example-satelliteinfo.png + + The example displays the signal strength of all satellites in view. Any satellite + that is currently used to calculate the GPS fix has been marked pink. The number at + the bottom of each signal bar is the individual satellite identifier. + + The application operates in three different modes: + + \table + \header + \li Application mode + \li Description + \row + \li running + \li The application continuously queries the system for satellite updates. When new data + is available it will be displayed. + \row + \li stopped + \li The application stops updating the satellite information. + \row + \li single + \li The application makes a single update request with a timeout of 10s. The display + remains empty until the request was answered by the system. + \endtable + + If the platform does not provide satellite information the application automatically + switches into a demo mode whereby it continuously switches between predefined + sets of satellite data. + + \include examples-run.qdocinc +*/ diff --git a/examples/positioning/weatherinfo/doc/images/example-weatherinfo.png b/examples/positioning/weatherinfo/doc/images/example-weatherinfo.png new file mode 100644 index 00000000..6557b57b Binary files /dev/null and b/examples/positioning/weatherinfo/doc/images/example-weatherinfo.png differ diff --git a/examples/positioning/weatherinfo/doc/src/weatherinfo.qdoc b/examples/positioning/weatherinfo/doc/src/weatherinfo.qdoc new file mode 100644 index 00000000..3db6fcbf --- /dev/null +++ b/examples/positioning/weatherinfo/doc/src/weatherinfo.qdoc @@ -0,0 +1,113 @@ +/**************************************************************************** +** +** Copyright (C) 2015 The Qt Company Ltd. +** Contact: http://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 http://www.qt.io/terms-conditions. For further +** information use the contact form at http://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: 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 \l{Qt Positioning} classes used in this example: + + \list + \li \l{QGeoPositionInfo} + \li \l{QGeoPositionInfoSource} + \endlist + + \image ../images/example-weatherinfo.png + + \include examples-run.qdocinc + + The example uses weather data provided by \l http://www.openweathermap.org. + + 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 + +*/ -- cgit v1.2.3