| /**************************************************************************** |
| ** |
| ** 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$ |
| ** |
| ****************************************************************************/ |
| |
| /*! |
| \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 |
| |
| */ |