Fix documenation in 'places' example

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

5 files changed, 41 insertions, 89 deletions

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