diff options
author | Michal Klocek <michal.klocek@theqtcompany.com> | 2015-05-13 11:47:14 +0200 |
---|---|---|
committer | Alex Blasche <alexander.blasche@theqtcompany.com> | 2015-05-29 14:08:57 +0000 |
commit | f49cff62775b6699a6a2edcdcfe0c9f6b3ecc7d2 (patch) | |
tree | 2545df35f0867facc8b96a5c637fa95f4b4aee84 | |
parent | e396c1908dd1b06f4139db4179890de3bdb5ab95 (diff) | |
download | qtlocation-f49cff62775b6699a6a2edcdcfe0c9f6b3ecc7d2.tar.gz |
Fix documenation in 'places' example
Change-Id: Id224d73d2b68a947bc6c7121175a2f83bd0059fa
Reviewed-by: Alex Blasche <alexander.blasche@theqtcompany.com>
-rw-r--r-- | examples/location/places/places.qml | 17 | ||||
-rw-r--r-- | examples/location/places/views/CategoryDelegate.qml | 27 | ||||
-rw-r--r-- | examples/location/places/views/CategoryView.qml | 20 | ||||
-rw-r--r-- | src/imports/location/declarativeplaces/qdeclarativereviewmodel.cpp | 2 | ||||
-rw-r--r-- | src/location/doc/images/example-places.png | bin | 0 -> 151611 bytes | |||
-rw-r--r-- | src/location/doc/images/qml-places.png | bin | 77501 -> 0 bytes | |||
-rw-r--r-- | src/location/doc/qtlocation.qdocconf | 2 | ||||
-rw-r--r-- | src/location/doc/src/examples/declarative-places.qdoc | 126 |
8 files changed, 72 insertions, 122 deletions
diff --git a/examples/location/places/places.qml b/examples/location/places/places.qml index f5586268..5598fdc7 100644 --- a/examples/location/places/places.qml +++ b/examples/location/places/places.qml @@ -158,8 +158,10 @@ ApplicationWindow { } } + //! [PlaceSearchSuggestionModel search text changed 1] SearchBar { id: searchBar + //! [PlaceSearchSuggestionModel search text changed 1] width: appWindow.width searchBarVisbile: stackView.depth > 1 && stackView.currentItem && @@ -171,21 +173,22 @@ ApplicationWindow { } } onGoBack: stackView.pop() + //! [PlaceSearchSuggestionModel search text changed 2] onSearchTextChanged: { - if (searchText.length >= 3) { - if (suggestionModel != null) { - suggestionModel.searchTerm = searchText; - suggestionModel.update(); - } + if (searchText.length >= 3 && suggestionModel != null) { + suggestionModel.searchTerm = searchText; + suggestionModel.update(); } } + //! [PlaceSearchSuggestionModel search text changed 2] onDoSearch: { if (searchText.length > 0) placeSearchModel.searchForText(searchText); } onShowMap: stackView.pop(page) - + //! [PlaceSearchSuggestionModel search text changed 3] } + //! [PlaceSearchSuggestionModel search text changed 3] StackView { id: stackView @@ -217,7 +220,7 @@ ApplicationWindow { properties: { "categoryModel": categoryModel, "rootIndex" : index }}) - currentItem.enterCategory.connect(stackView.enterCategory) + currentItem.showSubcategories.connect(stackView.enterCategory) currentItem.searchCategory.connect(placeSearchModel.searchForCategory) } diff --git a/examples/location/places/views/CategoryDelegate.qml b/examples/location/places/views/CategoryDelegate.qml index 2ac0a339..75f7060e 100644 --- a/examples/location/places/views/CategoryDelegate.qml +++ b/examples/location/places/views/CategoryDelegate.qml @@ -45,15 +45,14 @@ import QtLocation 5.5 Item { id: root - property alias text: textItem.text + property alias text: labelItem.text property bool checked: false signal searchCategory() - signal showSubcategory() + signal showSubcategories() width: parent.width - height: Math.max(icon.height, textItem.height * 2) + height: Math.max(icon.height, labelItem.height * 2) - //! [CategoryModel delegate icon] Image { id: icon anchors.left: parent.left @@ -61,7 +60,6 @@ Item { anchors.verticalCenter: parent.verticalCenter source: category.icon.url() } - //! [CategoryModel delegate icon] Rectangle { anchors.fill: parent @@ -71,12 +69,18 @@ Item { //! [CategoryModel delegate text] Label { - id: textItem + id: labelItem text: category.name anchors.left: icon.right anchors.verticalCenter: parent.verticalCenter anchors.right: arrow.left } + + MouseArea { + id: mouse + anchors.fill: parent + onClicked: root.searchCategory() + } //! [CategoryModel delegate text] Rectangle { @@ -86,13 +90,7 @@ Item { height: 1 color: "#46a2da" } - - MouseArea { - id: mouse - anchors.fill: parent - onClicked: root.searchCategory() - } - + //! [CategoryModel delegate arrow] ToolButton { id: arrow anchors.right: parent.right @@ -100,6 +98,7 @@ Item { anchors.rightMargin: 15 visible: model.hasModelChildren iconSource: "../../resources/right.png" - onClicked: root.showSubcategory() + onClicked: root.showSubcategories() } + //! [CategoryModel delegate arrow] } diff --git a/examples/location/places/views/CategoryView.qml b/examples/location/places/views/CategoryView.qml index d476300a..b17f3e79 100644 --- a/examples/location/places/views/CategoryView.qml +++ b/examples/location/places/views/CategoryView.qml @@ -40,32 +40,28 @@ import QtQuick 2.5 import QtLocation 5.5 +import QtQml.Models 2.1 -//! [CategoryModel view 1] +//! [CategoryModel view] ListView { id: root property variant categoryModel property variant rootIndex signal searchCategory(variant category) - signal enterCategory(variant index) -//! [CategoryModel view 1] - snapMode: ListView.SnapToItem - -//! [CategoryModel view 2] + signal showSubcategories(variant index) -//! [CategoryModel view 2] + snapMode: ListView.SnapToItem -//! [CategoryModel view 3] - model: VisualDataModel { - id: visalDataModel + model: DelegateModel { + id: delegeteDataModel model: root.categoryModel rootIndex: root.rootIndex delegate: CategoryDelegate { onSearchCategory: root.searchCategory(category); - onShowSubcategory: root.enterCategory(visalDataModel.modelIndex(index)) + onShowSubcategories: root.showSubcategories(delegeteDataModel.modelIndex(index)) } } } -//! [CategoryModel view 3] +//! [CategoryModel view] diff --git a/src/imports/location/declarativeplaces/qdeclarativereviewmodel.cpp b/src/imports/location/declarativeplaces/qdeclarativereviewmodel.cpp index 892a9a88..b7237bc9 100644 --- a/src/imports/location/declarativeplaces/qdeclarativereviewmodel.cpp +++ b/src/imports/location/declarativeplaces/qdeclarativereviewmodel.cpp @@ -60,7 +60,7 @@ QT_BEGIN_NAMESPACE To use the ReviewModel we need a view and a delegate. In this snippet we see the setting up of a ListView with a ReviewModel model and a delegate. - \snippet places/content/places/PlaceReviews.qml ReviewModel delegate + \snippet places/views/ReviewView.qml ReviewModel delegate The model returns data for the following roles: diff --git a/src/location/doc/images/example-places.png b/src/location/doc/images/example-places.png Binary files differnew file mode 100644 index 00000000..0b1ac8b7 --- /dev/null +++ b/src/location/doc/images/example-places.png diff --git a/src/location/doc/images/qml-places.png b/src/location/doc/images/qml-places.png Binary files differdeleted file mode 100644 index 970f1dc4..00000000 --- a/src/location/doc/images/qml-places.png +++ /dev/null diff --git a/src/location/doc/qtlocation.qdocconf b/src/location/doc/qtlocation.qdocconf index 09a200f7..695860a0 100644 --- a/src/location/doc/qtlocation.qdocconf +++ b/src/location/doc/qtlocation.qdocconf @@ -32,7 +32,7 @@ qhp.QtLocation.subprojects.examples.selectors = fake:example tagfile = ../../../doc/qtlocation/qtlocation.tags -depends += qtcore qtdoc qtquick qtqml qtnetwork qtpositioning +depends += qtcore qtdoc qtquick qtqml qtnetwork qtpositioning qtquickcontrols headerdirs += .. \ ../../imports/location diff --git a/src/location/doc/src/examples/declarative-places.qdoc b/src/location/doc/src/examples/declarative-places.qdoc index dc5ef8d0..414ccfca 100644 --- a/src/location/doc/src/examples/declarative-places.qdoc +++ b/src/location/doc/src/examples/declarative-places.qdoc @@ -33,7 +33,7 @@ \brief The Places example demonstrates how to search for Places and access related content. - \image qml-places.png + \image example-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. @@ -51,21 +51,15 @@ 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. + 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. - 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. + 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 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 geo service provider can be changed by accessing the "Provider" menu. \section1 Displaying Categories @@ -77,43 +71,31 @@ 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. + \l {CategoryModel::plugin}{plugin} property is set during example intalization. - Next we create a view to display the category model. + Next we create a \l {ListView} to display the category model. - \snippet places/content/places/CategoryView.qml CategoryModel view 1 - \codeline - \snippet places/content/places/CategoryView.qml CategoryModel view 2 - \codeline - \snippet places/content/places/CategoryView.qml CategoryModel view 3 + \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 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 DelegateModel 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 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 \e clicked signal when - the text is clicked: + The \e CategoryDelegate displays the category name and emits the \b searchCategory() signal when + the \l {Label} is clicked: - \snippet places/content/places/CategoryDelegate.qml CategoryModel delegate text + \snippet places/views/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. + The \e CategoryDelegate also displays \e arrow \l {ToolButton} when \e hasModelChildren property is set. - \snippet places/content/places/CategoryDelegate.qml CategoryModel delegate icon + \snippet places/views/CategoryDelegate.qml CategoryModel delegate arrow \target Presenting-Search-Suggestions @@ -124,26 +106,24 @@ A new suggestion search is triggered whenever the entered search term is changed. - \snippet places/content/places/SearchBox.qml PlaceSearchSuggestionModel search text 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 - 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. + Suggestions are only queried if the length of the search term is three or more characters. - When the status of the \l PlaceSearchSuggestionModel changes, the state of the search box is - changed to display the search suggestions. + When the status of the \l PlaceSearchSuggestionModel changes, search suggestions are displayed. - \snippet places/content/places/SearchBox.qml PlaceSearchSuggestionModel model + \snippet places/places.qml PlaceSearchSuggestionModel model The main object in the "SuggestionsShown" state is the \l ListView showing the search suggestions. - \snippet places/content/places/SearchBox.qml PlaceSearchSuggestionModel view 1 + \snippet places/views/SuggestionView.qml PlaceSearchSuggestionModel view 1 \codeline - \snippet places/content/places/SearchBox.qml PlaceSearchSuggestionModel view 2 + \snippet places/views/SuggestionView.qml PlaceSearchSuggestionModel view 2 - A \l Text object is used as the delegate to display the suggestion text. Clicking on the + 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. @@ -159,19 +139,19 @@ \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 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. + 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/content/places/SearchResultView.qml PlaceSearchModel place list + \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/content/places/SearchResultDelegate.qml PlaceSearchModel place delegate + \snippet places/views/SearchResultDelegate.qml PlaceSearchModel place delegate \section1 Displaying Place Content @@ -181,34 +161,6 @@ \l {Place::editorialModel}{editorialModel}, \l {Place::reviewModel}{reviewModel} and \l {Place::imageModel}{imageModel} properties of the \l Place type. - \snippet 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 places/content/places/PlaceDialog.qml Place save - - Category creation is similar: - - \snippet 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. + \snippet places/views/EditorialView.qml PlaceEditorialModel view - \section1 Running the Example - The example detects which plugins are available and has an option to show them in the via - the Provider button. */ |