Refactor Icons

Change-Id: I702e8a1b6f0e80cb990315165f1bf331a82e65a5
Reviewed-by: Aaron McCarthy <aaron.mccarthy@nokia.com>

5 files changed, 158 insertions, 63 deletions

diff --git a/doc/src/plugins/jsondb.qdoc b/doc/src/plugins/jsondb.qdoc
index f417c95f..1ac1bf8e 100644
--- a/doc/src/plugins/jsondb.qdoc
+++ b/doc/src/plugins/jsondb.qdoc
@@ -55,8 +55,8 @@ capabiliies are outlined below:
         \o Read/Write
         \o read/write
     \row
-        \o Icon url type(see \l {Icon internals} {QPlaceIcon})
-        \o full  url
+        \o Icons
+        \o yes
     \row
         \o Search term suggestions
         \o no
@@ -123,10 +123,135 @@ available details are fetched during a search.  The JsonDb plugin
 does not support saving of any other details.
 
 \section3 Icons
-The icon urls for the JsonDb plugin take the form of a file path.
-There can only be one icon image per icon, hence only the
-\l {Icon internals} {full url} is supported.  No icon variations are
-supported.
+\section4 Parameter Reference
+The JsonDbPlugin supports the following icon parameter values
+\table
+    \header
+        \o Key
+        \o Value
+    \row
+        \o smallUrl
+        \o Holds the URL for the small icon
+    \row
+        \o smallSize
+        \o Holds the dimensions of the small icon
+    \row
+        \o smallSourceUrl
+        \o Holds the source URL from which the small icon is to be copied from.
+    \row
+        \o mediumUrl
+        \o Holds the URL for the medium sized icon.
+    \row
+        \o mediumSize
+        \o Holds the dimensions of the medium sized icon.
+    \row
+        \o mediumSourceUrl
+        \o Holds the source URL from which the medium icon is to be copied from.
+    \row
+        \o largeUrl
+        \o Holds the URL for the large icon.
+    \row
+        \o largeSize
+        \o Holds the dimensions of the large icon.
+    \row
+        \o largeSourceUrl
+        \o Holds the source URL from which the large icon is to be copied from.
+    \row
+        \o fullscreenUrl
+        \o Holds the URL for the fullscreen icon.
+    \row
+        \o fullscreenSize
+        \o Holds the dimensions of the fullscreen icon.
+    \row
+        \o fullscreenSourceUrl
+        \o Holds the source URL from which the fullscreen icon is to be copied from.
+\endtable
+
+In C++ the value of the URLs must always be a QUrl.
+In QML the values of the URLs may be url or string types.
+
+\section4 Typical Usage
+During a typical place search, the icon parameters might be populated like so
+\code
+smallUrl: file:///foo/bar/icon_s.png
+smallSize: QSize(20,20)
+largeUrl: file:///foo/bar/icon_l.png
+largeSize: QSize(50,50)
+\endcode
+
+Only small and large icons were available in this case.  Note that for a given size URL, its dimensions will also be populated.
+These URLs and dimensions are used by the JsonDb plugin to determine the correct URL to return when QPlaceIcon::url() or \l {QtLocation5::Icon::url()} {Icon::url()}
+is called.
+
+If we wish to change the icons we, can simply specify a different set of parameter values and then save the place/category containing the icon.
+\code
+smallUrl: file:///opt/icons/new_icon_small.png
+(smallSize: QSize(20,20)) //optional
+largeUrl: file:///opt/icons/new_icon_large.png
+(largeSize: QSize(50,50)) // optional
+\endcode
+
+All we need to do is set the URLs to where the new icon image is.  The size typically does not need to be specified
+since it is generally automatically calculated.  In some cases where the size cannot be calculated, e.g. if the
+specified URL cannot currently be accessed, it is necessary to specify a recommended size.
+If the size of the image can be calculated and a size is also specified, then the specified size is ignored.
+
+\section4 Copying icons to a specified destination
+When copying or saving icons, we use the source parameters to hold the URL of the source image we are copying from
+\code
+smallSourceUrl: file:///foo/icon_s.png
+smallUrl: file:///bar/icon_small.png
+(smallSize: QSize(20,20) //optional
+\endcode
+
+Using the parameters above will copy the icon from \c smallSourceUrl to the \c smallUrl.  At present both the
+smallSourceUrl and smallUrl must be local file URLs.  If the smallUrl already exists, it is overwritten, otherwise it is created.
+\c smallSize typically does not need to be set since an attempt will be made to calculate the icon's size.   In some cases where the size cannot be calculated, e.g. if the
+specified URL cannot currently be accessed, it is necessary to specify a recommended size.
+If the size of the image can be calculated and a size is also specified, then the specified size is ignored.
+
+\section4 Copying icons without a specified destination
+It is possible to copy icons, when a place/category is saved, and not have to specify a destination.  In this case a data URL will be
+created for the icon in the underlying database.  A data URL contains the icon image embedded into the URL itself.  A destination
+size is chosen for the icon depending on it's calculated size.
+
+\code
+//input parameters
+smallSourceUrl: file:///foo/icon_small.png
+
+//(1) Result if the source icon's actual size corresponded to small
+smallUrl: data:image/png;base64,iVBORw0K….
+smallSize: QSize(20,20)
+
+//(2) Result if the source icon's actual size corresponded to medium
+mediumUrl: data:image/png;base64,iVBORw0K….
+mediumSize: QSize(30,30)
+\endcode
+
+The above shows that for a given input source URL, an appropriate destination is chosen for the data URL.
+The icon will not necessarily be placed into smallUrl, since the size is calculated and a destination
+chosen.  The image at the sourceUrl must always been accessible so that the data URL can be generated,
+consequently this preprequisite also means that a size need not be specified since can always be calculated.
+
+This behaviour of automatically choosing a destination is necessary because when an icon from a different plugin is saved,
+it isn't known whether there is only one URL by the JsonDb plugin.  When creating a compatible place from another
+plugin, the JsonDbPlugin tries to get the URLs for the standard small, medium and large sizes.  It is possible
+however that all these may end up being the same URL.  The JsonDb plugn filters out these duplicates and chooses
+an appropriate destination based on size.
+\code
+//The resultant place's icon after calling QPlaceManager::compatiblePlace()
+smallSourceUrl: file:///bar/foo.png
+mediumSourceUrl: file:///bar/foo.png
+largeSourceUrl: file:///bar/foo.png
+
+//on save, the plugin filters out the duplicates and determines an appropriate size
+//in this case the data URL for the large size has been created.
+largeUrl: data:image/png;base64,qVyOZw0p….
+largeSize: QSize(50,50)
+\endcode
+
+The fullscreen icon is never retrieved and converted into a data URL because data URLs are only meant
+for small icon images.
 
 \section3 Visibility scope
 The JsonDb plugin only supports places of the QtLocation::PrivateVisibility scope.
diff --git a/doc/src/plugins/nokia.qdoc b/doc/src/plugins/nokia.qdoc
index 01a57064..44079f10 100644
--- a/doc/src/plugins/nokia.qdoc
+++ b/doc/src/plugins/nokia.qdoc
@@ -145,8 +145,8 @@ and behaviours are outlined below:
         \o Read/Write
         \o read-only
     \row
-        \o Icon url type(see \l {Icon internals} {QPlaceIcon})
-        \o not supported
+        \o Icons
+        \o No
     \row
         \o Search term suggestions
         \o yes
diff --git a/doc/src/plugins/places-backend.qdoc b/doc/src/plugins/places-backend.qdoc
index 1c9ddd41..3abeb826 100644
--- a/doc/src/plugins/places-backend.qdoc
+++ b/doc/src/plugins/places-backend.qdoc
@@ -83,58 +83,16 @@ Also note that the \c finished signals should always be emitted when a reply is
 an error has been encountred, i.e. if there is an error, both the \c error and \c finished signals
 should be emitted while if there is no error, only the \c finished signals are emitted.
 
-\section1 Icon Urls
-
+\section1 Icon URLs
 Icon URLs are provided through the QPlaceManagerEngine::constructIconUrl() function.
-Two important concepts regarding icons that needs to be discused
-is that of the \e baseUrl and \e fullUrl.
-A \e {baseUrl} is an incomplete URL similar to the following:
-\code
-http://www.example.com/icons/icon_
-or
-file://home/user/icons/icon_
-or
-http://www.example.com/icons/icon
-or
-file://home/user/icons/icon
-\endcode
-
-A \e {fullUrl} is a complete URL like:
-\code
-http://www.example.com/icons/icon.png
-or
-file://home/user/icons/icon.png
-\endcode
-
-The purpose of the \e {baseUrl} is to accommodate different variations
-of the same icon.  e.g. A server may provide icons with dimensions of
-16x16 but also 48x48 to allow for clients which have different form factors.
-Some providers may have a set of icons suited for maps, as well as another
-set more suited for lists.  These kinds of engines populate the \e {baseUrl} of a place's
-QPlaceIcon,
-
-The \e {baseUrl} is used in conjunction with the
-requested size and usage flag parameters of
-QPlaceManagerEngine::constructIconUrl() to give the closest matching
-url of the icon.  e.g.
-\code
-//base
-http://www.example.com/icons/icon_
-//constructed icons
-http://www.example.com/icons/icon_48_selected.png
-http://www.example.com/icons/icon_16_map.png
-http://www.example.com/icons/icon_16_selected_map.png
-\endcode
-
-If a datastore does not support icon variations, then the \e {fullUrl}
-of the QPlaceIcon should be populated.  The \e baseUrl and \e {fullUrl}
-are mutually exclusive, if one is set the other is implicitly cleared.
-If the \e {fullUrl} of an icon is used, then the manager engine should
-always returns the contents of the \e {fullUrl} as is, regardless of
-the variation parameters specified.
-
-\note It is possible for icon URLs to be \l {http://dataurl.net}{data URLs} where the icon image
-itself is embedded into the URL.
+The expected behaviour is that the engine will use the QPlaceIcon::parameters()
+in order to construct an appropriate URL.  When a QPlace object is returned
+from the manager either from a search or a query to get place details,
+it is expected the engine will correctly populate the parameters as necessary.
+
+The backend is free to choose what the parameter key and values are, however
+if a backend only ever has one URL per icon it is recommended that the QPlaceIcon::SingleUrl
+be used as the key.
 
 \section1 Categories
 The categories of a manager engine are relatively static entities; for engines accessing
@@ -143,12 +101,18 @@ querying a server every time QPlaceManagerEngine::initializeCategories() is call
 Depending on how dynamic the categories are, always downloading the freshest
 set of categories may be more appropriate.
 
-\section1 Saving between managers.
+\section1 Saving places to the manager
 A place generally cannot be saved directly between managers as is because it contains manager specific data such as icons
-and categories.  In order to facilitate saving between managers, engine implementers should implement
+and categories.  In order to facilitate saving to one's own manager, engine implementers should implement
 the QPlaceManagerEngine::compatiblePlace() function.  This function returns a copy of the input place
 with properties pruned or modified as necessary such that the copy can be saved into manager.
 
+Construction of a compatible place may involve ignoring certain properties from the
+original place, e.g. if contact details are not supported, these are left out of the
+compatible place.  Other times it may involve modifying certain properties, e.g.
+modifying the icon parameters to facilitate copying or downloading of the original
+place's icon to a location that the backend can access.
+
 \section1 Cross-referencing places between managers.
 Sometimes a situation may arise where we wish to cross-reference and match places between managers.
 Such a situation may arise where one manager provides read-only access to places (origin manager), while another second r/w
diff --git a/doc/src/snippets/declarative/places.qml b/doc/src/snippets/declarative/places.qml
index b937621d..472b0045 100644
--- a/doc/src/snippets/declarative/places.qml
+++ b/doc/src/snippets/declarative/places.qml
@@ -103,10 +103,16 @@ Item {
 
     //! [Icon]
     Image {
-        source: icon.url(Qt.size(64, 64), Icon.Selected | Icon.List)
+        source: icon.url(Qt.size(64, 64))
     }
     //! [Icon]
 
+    Image {
+    //! [Icon default]
+    source: icon.url()
+    //! [Icon default]
+    }
+
     //! [PlaceSearchModel]
     PlaceSearchModel {
         id: searchModel
diff --git a/doc/src/snippets/places/requesthandler.h b/doc/src/snippets/places/requesthandler.h
index 67dad2b2..6b52728a 100644
--- a/doc/src/snippets/places/requesthandler.h
+++ b/doc/src/snippets/places/requesthandler.h
@@ -292,7 +292,7 @@ public:
     void icon() {
         QPlace place;
         //! [icon]
-        QUrl iconSourceUrl = place.icon().url(QSize(32,32), QPlaceIcon::Selected | QPlaceIcon::List);
+        QUrl iconSourceUrl = place.icon().url(QSize(32,32));
 
         //A default icon may also be requested like so
         iconSourceUrl = place.icon().url();