diff options
Diffstat (limited to 'src/location/doc/src/examples/declarative-places.qdoc')
| -rw-r--r-- | src/location/doc/src/examples/declarative-places.qdoc | 220 |
1 files changed, 220 insertions, 0 deletions
diff --git a/src/location/doc/src/examples/declarative-places.qdoc b/src/location/doc/src/examples/declarative-places.qdoc new file mode 100644 index 00000000..30848740 --- /dev/null +++ b/src/location/doc/src/examples/declarative-places.qdoc @@ -0,0 +1,220 @@ +/**************************************************************************** +** +** 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/places + \title Places (QML) + \ingroup qtlocation-examples + + \brief The Places example demonstrates how to search for Places and access + related content. + + \image qml-places.png + + \section1 Overview + + The Places example presents an application window displaying a map. At the top of the window + is a search box, which is used to enter a place search query. To search for a place enter a + search term into the text box and click the magnifying glass icon. To search for a place by + category, click the category icon to display the list of available categories and select the + desired category. The place search query will be for places that are near the current location + shown on the map. + + The search box provides search term suggestions when three or more characters are entered. + Selecting one of the suggestions will cause a place search to be performed with the selected + search text. + + Search results are available from the slide out tab on the left. Clicking on a search result + will display details about the place. If a places has rich content (editorials, reviews and + images), these can be accessed by the buttons on the details page. To find similar places + click the "Find similar" button. If the current Geo service provider supports it, buttons to + edit and remove a place will also be available. + + The geo service provider can be changed by accessing the "Provider" menu at the bottom of the + window. Depending on the features supported by the provider, the "New" menu allows creating + new Places and Categories. To create a new place, select "Place" from the "New" menu and fill + in the fields. Click "Go!" to save the place. To create a new category, select "Category" + from the "New" menu and fill in the fields. Click "Go!" to save the category. + + The Places example can work with any of the available geo services plugins. However, some + plugins may require additional \l {QtLocation5::PluginParameter}{plugin parameters} in order to + function correctly. \l {QtLocation5::PluginParameter}{Plugin parameters} can be passed on the + command line using the \c {--plugin} argument, which takes the form: + + \code + --plugin.<parameter name> <parameter value> + \endcode + + Refer to the documentation for each of the geo services plugins for details on what plugin + parameters they support. The Nokia services plugin supplied with Qt requires an \e app_id and + \e token pair. See "\l {Qt Location Nokia Plugin}" for details. + + \section1 Displaying Categories + + Before search by category can be performed, the list of available categories needs to be + retrieved. This is achieved by creating a \l CategoryModel. + + \snippet declarative/places/places.qml CategoryModel model + + The \l CategoryModel type provides a model of the available categories. It can provide + either a flat list or a hierarchical tree model. In this example, we use a hierarchical tree + model, by setting the \l {CategoryModel::hierarchical}{hierarchical} property to \e true. The + \l {CategoryModel::plugin}{plugin} property is set to \e placesPlugin which is the \e identifier of the + \l Plugin object used for place search throughout the example. + + Next we create a view to display the category model. + + \snippet declarative/places/content/places/CategoryView.qml CategoryModel view 1 + \codeline + \snippet declarative/places/content/places/CategoryView.qml CategoryModel view 2 + \codeline + \snippet declarative/places/content/places/CategoryView.qml CategoryModel view 3 + + Because a hierarchical model is being used, a \l VisualDataModel is needed to provide + navigation functionality. If flat list model was being used the view could use the + \l CategoryModel directly. + + The view contains a header item that is used as a back button to navigate up the category tree. + The \e onClicked handler sets the root index of the \l VisualDataModel to the parent of the + current index. Categories are displayed by the \e CategoryDelegate, which provides four + signals. The \e onArrowClicked handler sets the root index to the current index causing the + sub categories of the selected category to be displayed. The \e onClicked handler emits + the \b categoryClicked() signal with a category parameter indicating which specific category + has been chosen. The \e onCrossClicked handler will invoke the + categories \l {Category::remove()}{remove()} method. The \e onEditClicked handler invokes the + \b editClicked() signal of the root item, this is used to notify which particular category + is to be edited. + + The \e CategoryDelegate displays the category name and emits the \e clicked signal when + the text is clicked: + + \snippet declarative/places/content/places/CategoryDelegate.qml CategoryModel delegate text + + The \e CategoryDelegate also displays icons for editing, removing and displaying child + categories. These icons are shown as desired when the \e showSave and \e showRemove + and \e showChildren properties are set and only then in cases where the function is + supported. + + \snippet declarative/places/content/places/CategoryDelegate.qml CategoryModel delegate icon + + + \target Presenting-Search-Suggestions + \section1 Presenting Search Suggestions + + The \l PlaceSearchSuggestionModel type is used to fetch suggested search terms based on a + partially entered search term. + + A new suggestion search is triggered whenever the entered search term is changed. + + \snippet declarative/places/content/places/SearchBox.qml PlaceSearchSuggestionModel search text changed + + The \e suggestionsEnabled property is used to temporarily disable search suggestions when a + suggestion is selected (selecting it updates the search term text). Suggestions are only + queried if the length of the search term is three or more characters, otherwise the search + boxes state is reset. + + When the status of the \l PlaceSearchSuggestionModel changes, the state of the search box is + changed to display the search suggestions. + + \snippet declarative/places/content/places/SearchBox.qml PlaceSearchSuggestionModel model + + The main object in the "SuggestionsShown" state is the \l ListView showing the search + suggestions. + + \snippet declarative/places/content/places/SearchBox.qml PlaceSearchSuggestionModel view 1 + \codeline + \snippet declarative/places/content/places/SearchBox.qml PlaceSearchSuggestionModel view 2 + + A \l Text object is used as the delegate to display the suggestion text. Clicking on the + suggested search term updates the search term and triggers a place search using the search + suggestion. + + + \section1 Searching for Places + + The \l PlaceSearchModel type is used to search for places. + + \snippet declarative/places/places.qml PlaceSearchModel model + + First some of the model's properties are set, which will be used to form the search request. + The \l {PlaceSearchModel::searchArea}{searchArea} property is set to the + \e searchRegion object which is a \l GeoCircle with a center that is linked to the current + location displayed on the \l Map. + + Finally, we define two helper functions \b searchForCategory() and \b {searchForText()}, + which set either the \l {PlaceSearchModel::categories}{categories} or + \l {PlaceSearchModel::searchTerm}{searchTerm} properties and invokes the + \l {PlaceSearchModel::update()}{update()} method to start the place search. The search + results are displayed in a \l ListView. + + \snippet declarative/places/content/places/SearchResultView.qml PlaceSearchModel place list + + The delegate used in the \l ListView, \e SearchResultDelegate, is designed to handle multiple + search result types via a \l Loader object. For results of type \e PlaceResult the delegate + is: + + \snippet declarative/places/content/places/SearchResultDelegate.qml PlaceSearchModel place delegate + + \section1 Displaying Place Content + + Places can have additional rich content, including editorials, reviews and images. Rich + content is accessed via a set of models. Content models are generally not created directly by + the application developer, instead models are obtained from the + \l {Place::editorialModel}{editorialModel}, \l {Place::reviewModel}{reviewModel} and + \l {Place::imageModel}{imageModel} properties of the \l Place type. + + \snippet declarative/places/content/places/PlaceEditorials.qml PlaceEditorialModel view + + + \section1 Place and Category Creation + + Some backends may support creation and saving of new places and categories. Plugin support can + be checked an run-time with the \l Plugin::supportsPlaces() method. + + To save a new place, first create a new \l Place object, using the + \l {Qt::createQmlObject()}{Qt.createQmlObject()} method. Assign the appropriate plugin and + place properties and invoke the \l {Place::save()}{save()} method. + + \snippet declarative/places/content/places/PlaceDialog.qml Place save + + Category creation is similar: + + \snippet declarative/places/content/places/CategoryDialog.qml Category save + + Support for place and category removal can be checked at run-time by using the + \l {Plugin::supportsPlaces} method, passing in a \l {Plugin::supportsPlaces}{Plugin::PlacesFeatures} flag and + getting back \e true if the feature is supported. For example one would invoke + \e {supportsPlaces(Plugin.RemovePlaceFeature)} to check if the \e Plugin.RemovePlaceFeature is supported. + + + To remove a place, invoke its \l {Place::remove()}{remove()} method. To remove a category, + invoke its \l {Category::remove()}{remove()} method. + + \section1 Running the Example + The example detects which plugins are available and has an option to show them in the via + the Provider button. +*/ |