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ö --- examples/location/places/doc/src/places.qdoc | 166 +++++++++++++++++++++++++++ 1 file changed, 166 insertions(+) create mode 100644 examples/location/places/doc/src/places.qdoc (limited to 'examples/location/places/doc/src/places.qdoc') diff --git a/examples/location/places/doc/src/places.qdoc b/examples/location/places/doc/src/places.qdoc new file mode 100644 index 00000000..bc93bcaf --- /dev/null +++ b/examples/location/places/doc/src/places.qdoc @@ -0,0 +1,166 @@ +/**************************************************************************** +** +** 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 places + \title Places (QML) + \ingroup qtlocation-examples + + \brief The Places example demonstrates how to search for Places and access + related content. + + \image places.png + + The Places example demonstrates how to search for Places. In particular it shows + how further information such as reviews, images and related content can be retrieved. + + \include examples-run.qdocinc + + \include example-parameters.qdocinc + + \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. + + For some plugins like \l {Qt Location HERE Plugin} 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. + + 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. + + The geo service provider can be changed by accessing the "Provider" menu. + + \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 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 during example intalization. + + Next we create a \l {ListView} to display the category model. + + \snippet places/views/CategoryView.qml CategoryModel view + + Because a hierarchical model is being used, a \l DelegateModel is needed to provide + navigation functionality. If flat list model was being used the view could use the + \l CategoryModel directly. + + The \e rootIndex property sets the root index of the \l DelegateModel. Categories are + displayed by the \e CategoryDelegate, which provides two signals. The \e onShowSubcategories + emits the \b showSubcategories() signal with root index to the current index causing the + sub categories of the selected category to be displayed. The \e onSearchCategory handler emits + the \b searchCategory() signal with a category parameter indicating which specific category + has been chosen. + + The \e CategoryDelegate displays the category name and emits the \b searchCategory() signal when + the \l {Label} is clicked: + + \snippet places/views/CategoryDelegate.qml CategoryModel delegate text + + The \e CategoryDelegate also displays \e arrow \l {ToolButton} when \e hasModelChildren property is set. + + \snippet places/views/CategoryDelegate.qml CategoryModel delegate arrow + + + \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 places/places.qml PlaceSearchSuggestionModel search text changed 1 + \snippet places/places.qml PlaceSearchSuggestionModel search text changed 2 + \snippet places/places.qml PlaceSearchSuggestionModel search text changed 3 + + Suggestions are only queried if the length of the search term is three or more characters. + + When the status of the \l PlaceSearchSuggestionModel changes, search suggestions are displayed. + + \snippet places/places.qml PlaceSearchSuggestionModel model + + The main object in the "SuggestionsShown" state is the \l ListView showing the search + suggestions. + + \snippet places/views/SuggestionView.qml PlaceSearchSuggestionModel view 1 + \codeline + \snippet places/views/SuggestionView.qml PlaceSearchSuggestionModel view 2 + + A \l {Label} 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 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 [QML]{geocircle} with a center that is linked to the current + location displayed on the \l Map. + + Finally, we define three helper functions \b searchForCategory(), \b {searchForText()} and + \b searchForRecommendations() which set either the \l {PlaceSearchModel::categories}{categories} or + \l {PlaceSearchModel::searchTerm}{searchTerm} or \l {PlaceSearchModel::recommendationId}{recommendationId} + properties and invokes the \l {PlaceSearchModel::update()}{update()} method to start the + place search. The search results are displayed in a \l ListView. + + \snippet places/views/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 places/views/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 places/views/EditorialView.qml PlaceEditorialModel view + +*/ -- cgit v1.2.1