Fix documenation in 'places' example

Change-Id: Id224d73d2b68a947bc6c7121175a2f83bd0059fa
Reviewed-by: Alex Blasche <alexander.blasche@theqtcompany.com>

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
new 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
deleted 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.
 */