/usr/share/qt5/doc/qtlocation/location-places-qml.html is in qtlocation5-doc-html 5.5.1-3ubuntu1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 | <?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html>
<html lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<!-- places.qdoc -->
<title>QML Places API | Qt Location 5.5</title>
<link rel="stylesheet" type="text/css" href="style/offline.css" />
</head>
<body>
<div class="header" id="qtdocheader">
<div class="main">
<div class="main-rounded">
<div class="navigationbar">
<ul>
<li>Qt 5.5</li>
<li><a href="qtlocation-index.html">Qt Location</a></li>
<li>QML Places API</li>
<li id="buildversion">Qt 5.5.1 Reference Documentation</li>
</ul>
</div>
</div>
<div class="content">
<div class="line">
<div class="content mainContent">
<div class="sidebar">
<div class="toc">
<h3><a name="toc">Contents</a></h3>
<ul>
<li class="level1"><a href="#overview">Overview</a></li>
<li class="level1"><a href="#introductory-concepts">Introductory Concepts</a></li>
<li class="level2"><a href="#plugin">Plugin</a></li>
<li class="level2"><a href="#models-views-and-delegates">Models, Views and Delegates</a></li>
<li class="level1"><a href="#common-use-cases">Common Use Cases</a></li>
<li class="level2"><a href="#searching-for-places">Searching for Places</a></li>
<li class="level2"><a href="#display-search-results-using-a-listview">Display Search Results using a ListView</a></li>
<li class="level2"><a href="#display-search-results-using-a-mapitemview">Display Search Results using a MapItemView</a></li>
<li class="level2"><a href="#fetching-place-details">Fetching Place Details</a></li>
<li class="level2"><a href="#saving-and-removing-places">Saving and Removing Places</a></li>
<li class="level2"><a href="#learn-more">Learn More</a></li>
<li class="level1"><a href="#places-types">Places Types</a></li>
<li class="level2"><a href="#data-types">Data Types</a></li>
<li class="level2"><a href="#models">Models</a></li>
</ul>
</div>
<div class="sidebar-content" id="sidebar-content"></div></div>
<h1 class="title">QML Places API</h1>
<span class="subtitle"></span>
<!-- $$$location-places-qml.html-description -->
<div class="descr"> <a name="details"></a>
<a name="overview"></a>
<h2 id="overview">Overview</h2>
<p>The Places API allows users to discover places of interest and view details about them, such as address and contact information. Some places may have additional content associated with them, such as images and reviews. The Places API also facilitates management of places and categories, allowing users to save and remove them.</p>
<a name="introductory-concepts"></a>
<h2 id="introductory-concepts">Introductory Concepts</h2>
<a name="plugin"></a>
<h3 >Plugin</h3>
<p>A <a href="location-places-qml.html#plugin">Plugin</a> is an abstraction for a backend. One <a href="location-places-qml.html#plugin">Plugin</a> might access places from a REST server while another may access places from a local database. The following instantiates a <a href="location-places-qml.html#plugin">Plugin</a> object by providing a name of "osm". The <a href="location-places-qml.html#plugin">Plugin</a> name identifies which backend to choose from. Plugins may also be provided with a set of <a href="qml-qtlocation-pluginparameter.html">parameters</a>, which essentially takes the form of a set of key-value pairs. The <a href="qml-qtlocation-pluginparameter.html">parameters</a> that can be specified vary among the different <a href="location-places-qml.html#plugin">Plugin</a> backends. For documentation on the possible <a href="qml-qtlocation-pluginparameter.html">parameters</a> and nuances of each <a href="location-places-qml.html#plugin">Plugin</a>, see the <a href="qtlocation-index.html#plugin-references-and-parameters">Plugin References</a>.</p>
<pre class="qml"><span class="type"><a href="qml-qtlocation-plugin.html">Plugin</a></span> {
<span class="name">id</span>: <span class="name">myPlugin</span>
<span class="name">name</span>: <span class="string">"osm"</span>
<span class="comment">//specify plugin parameters as necessary</span>
<span class="comment">//PluginParameter {...}</span>
<span class="comment">//PluginParameter {...}</span>
<span class="comment">//...</span>
}</pre>
<p><b>Note: </b>The HERE plugin must be supplied with some mandatory parameters as outlined in the <a href="location-plugin-here.html#mandatory-parameters">HERE Plugin</a> documentation.</p><a name="models-views-and-delegates"></a>
<h3 >Models, Views and Delegates</h3>
<p>The QML Places API is built around the notion of models, views and delegates.</p>
<div class="table"><table class="generic">
<tr valign="top" class="odd"><td ><b>Model</b></td><td >A model holds data items and maintains their structure. The model is also responsible for retrieving the items from a data source.</td></tr>
<tr valign="top" class="even"><td ><b>View</b></td><td >A view is a visual container that displays the data and manages how visual items are shown such as in a list or a grid. The view may also be responsible for navigating the data, for example, scrolling through the visual items during a flicking motion.</td></tr>
<tr valign="top" class="odd"><td ><b>Delegate</b></td><td >A delegate defines how individual data elements should appear as visual items in the view. The models expose a set of data roles and the delegate uses them to construct a visual item. The delegate may also define behaviour such as an operation to invoke when a visual item is clicked.</td></tr>
</table></div>
<p>The Common Use Cases section below demonstrates concrete examples of how these concepts fit together.</p>
<a name="common-use-cases"></a>
<h2 id="common-use-cases">Common Use Cases</h2>
<a name="searching-for-places"></a>
<h3 >Searching for Places</h3>
<p>Searching is accomplished via the <a href="qml-qtlocation-placesearchmodel.html">PlaceSearchModel</a>. The <a href="qml-qtlocation-placesearchmodel.html#plugin-prop">plugin</a> property specifies which backend to perform search operations against. Search parameters may be provided through properties such as the <a href="qml-qtlocation-placesearchmodel.html#searchTerm-prop">searchTerm</a> and <a href="qml-qtlocation-placesearchmodel.html#searchArea-prop">searchArea</a>. A search operation can then be started by invoking the <a href="qml-qtlocation-placesearchmodel.html#update-method">update()</a> method. For simplicity, the snippet below invokes <a href="qml-qtlocation-placesearchmodel.html#update-method">update()</a> once construction of the model as been completed, typically <a href="qml-qtlocation-placesearchmodel.html#update-method">update()</a> would be invoked in response to a user action such as a button click. While the search operation is underway the <a href="qml-qtlocation-placesearchmodel.html#status-prop">PlaceSearchModel::status</a> property transitions into the <code>Loading</code> state and when successfully completed moves into the <code>Ready</code> state.</p>
<pre class="qml"><span class="type"><a href="qml-qtlocation-placesearchmodel.html">PlaceSearchModel</a></span> {
<span class="name">id</span>: <span class="name">searchModel</span>
<span class="name">plugin</span>: <span class="name">myPlugin</span>
<span class="name">searchTerm</span>: <span class="string">"pizza"</span>
<span class="name">searchArea</span>: <span class="name">QtPositioning</span>.<span class="name">circle</span>(<span class="name">startCoordinate</span>);
<span class="name">Component</span>.onCompleted: <span class="name">update</span>()
}</pre>
<a name="display-search-results-using-a-listview"></a>
<h3 >Display Search Results using a ListView</h3>
<p>A ListView can be used to show the search results found by the model. It defines the visual region for where the results are shown, and in the case below fills the entirety of its parent. The ListView has built in behavior that enables the region to respond to flicking events and to scroll appropriately.</p>
<p>In the snippet below, the search model has been assigned to the ListView's model property. When the model is updated with new results, the ListView is automatically updated to reflect the model's new data items.</p>
<p>A simple delegate has been bound to the ListView's delegate property. The <a href="qml-qtlocation-placesearchmodel.html">PlaceSearchModel</a> exposes a set of <a href="qml-qtlocation-placesearchmodel.html#placesearchmodel-roles">roles</a> of which the <i>title</i> and <i>place</i> roles have been used below, these are of type string and <a href="qml-qtlocation-place.html">Place</a> respectively. Essentially for each data item that should be visible in the view, the view invokes the delegate to create a visual representation of the item.</p>
<div class="table"><table class="generic">
<tr valign="top" class="odd"><td ><pre class="qml"><span class="type">ListView</span> {
<span class="name">anchors</span>.fill: <span class="name">parent</span>
<span class="name">model</span>: <span class="name">searchModel</span>
<span class="name">delegate</span>: <span class="name">Component</span> {
<span class="type">Row</span> {
<span class="name">spacing</span>: <span class="number">5</span>
<span class="type">Marker</span> { <span class="name">height</span>: <span class="name">parent</span>.<span class="name">height</span> }
<span class="type">Column</span> {
<span class="type">Text</span> { <span class="name">text</span>: <span class="name">title</span>; <span class="name">font</span>.bold: <span class="number">true</span> }
<span class="type">Text</span> { <span class="name">text</span>: <span class="name">place</span>.<span class="name">location</span>.<span class="name">address</span>.<span class="name">text</span> }
}
}
}
}</pre>
</td><td ><img src="images/places-list.png" alt="" /></td></tr>
</table></div>
<p><b>Note: </b>For simplicty's sake we have assumed that every search result is of <a href="qml-qtlocation-placesearchmodel.html#search-result-types">type</a> <code>PlaceSearchResult</code> and so always have access to the <i>place</i> role, other search result types may not have a <i>place</i> role.</p><p>See the <a href="qtlocation-places-list-example.html">Places List</a> example for full source code.</p>
<a name="display-search-results-using-a-mapitemview"></a>
<h3 >Display Search Results using a MapItemView</h3>
<p>Instead of a ListView, the <a href="qml-qtlocation-placesearchmodel.html">PlaceSearchModel</a> can be used in conjunction with a <a href="qml-qtlocation-mapitemview.html">MapItemView</a> to display markers on a map. Firstly a <a href="qml-qtlocation-map.html">Map</a> is used to define the visual region occupied by the map, in this case it fills the entirety of its parent. Other properties are specified such as the <a href="qml-qtlocation-map.html#plugin-prop">plugin</a> providing the maps, and the map's <a href="qml-qtlocation-map.html#center-prop">center</a> and <a href="qml-qtlocation-map.html#zoomLevel-prop">zoomLevel</a>.</p>
<p>Inside the <a href="qml-qtlocation-map.html">Map</a>, a <a href="qml-qtlocation-mapitemview.html">MapItemView</a> is declared, where the <a href="qml-qtlocation-mapitemview.html#model-prop">model</a> property has been set to the search model and a <a href="qml-qtlocation-mapitemview.html#delegate-prop">delegate</a> consisting of a <a href="qml-qtlocation-mapquickitem.html">MapQuickItem</a> is used to display a marker image. A marker is shown for every place that was found by the search model. The delegate uses the <i>place</i> role to position the marker.</p>
<div class="table"><table class="generic">
<tr valign="top" class="odd"><td ><pre class="qml"><span class="type"><a href="qml-qtlocation-map.html">Map</a></span> {
<span class="name">id</span>: <span class="name">map</span>
<span class="name">anchors</span>.fill: <span class="name">parent</span>
<span class="name">plugin</span>: <span class="name">myPlugin</span>;
<span class="name">center</span>: <span class="name">locationOslo</span>
<span class="name">zoomLevel</span>: <span class="number">13</span>
<span class="type"><a href="qml-qtlocation-mapitemview.html">MapItemView</a></span> {
<span class="name">model</span>: <span class="name">searchModel</span>
<span class="name">delegate</span>: <span class="name">MapQuickItem</span> {
<span class="name">coordinate</span>: <span class="name">place</span>.<span class="name">location</span>.<span class="name">coordinate</span>
<span class="name">anchorPoint</span>.x: <span class="name">image</span>.<span class="name">width</span> <span class="operator">*</span> <span class="number">0.5</span>
<span class="name">anchorPoint</span>.y: <span class="name">image</span>.<span class="name">height</span>
<span class="name">sourceItem</span>: <span class="name">Column</span> {
<span class="type">Image</span> { <span class="name">id</span>: <span class="name">image</span>; <span class="name">source</span>: <span class="string">"marker.png"</span> }
<span class="type">Text</span> { <span class="name">text</span>: <span class="name">title</span>; <span class="name">font</span>.bold: <span class="number">true</span> }
}
}
}
}</pre>
</td><td ><img src="images/places-map.png" alt="" /></td></tr>
</table></div>
<p><b>Note: </b>For simplicty's sake we have assumed that every search result is of <a href="qml-qtlocation-placesearchmodel.html#search-result-types">type</a> <code>PlaceSearchResult</code> and so always have access to the <i>place</i> role, other search result types may not have a <i>place</i> role.</p><p>See the <a href="qtlocation-places-map-example.html">Places Map</a> example for full source code.</p>
<a name="fetching-place-details"></a>
<h3 >Fetching Place Details</h3>
<p>In order to save bandwidth, sometimes a backend will only return places which are partially populated with details. This can be checked with the <a href="qml-qtlocation-place.html#detailsFetched-prop">Place::detailsFetched</a> property which indicates whether all availalable details have been fetched or not. If not, the <a href="qml-qtlocation-place.html#getDetails-method">Place::getDetails</a>() method can be invoked to fetch the remaining details.</p>
<pre class="qml"><span class="keyword">if</span> (!<span class="name">place</span>.<span class="name">detailsFetched</span>)
<span class="name">place</span>.<span class="name">getDetails</span>();</pre>
<a name="saving-and-removing-places"></a>
<h3 >Saving and Removing Places</h3>
<p>Some backends may support saving and removing places. This can be done by calling the <a href="qml-qtlocation-place.html#save-method">Place::save</a>() and <a href="qml-qtlocation-place.html#remove-method">Place::remove</a>() methods respectively. Note that in order to save a <a href="qml-qtlocation-place.html">Place</a>, a <a href="location-places-qml.html#plugin">Plugin</a> must be assigned to specify which backend we are saving to. The <a href="qml-qtlocation-place.html#status-prop">status</a> property will transition into the <code>Saving</code> state while the save operation is happening and on successful completion will move to the <code>Ready</code> state. The following snippet shows how to save and remove a place using javascript.</p>
<pre class="qml"><span class="comment">//creating and saving a place</span>
var <span class="name">place</span> = <span class="name">Qt</span>.<span class="name">createQmlObject</span>(<span class="string">'import QtLocation 5.3; Place { }'</span>, <span class="name">parent</span>);
<span class="name">place</span>.<span class="name">plugin</span> <span class="operator">=</span> <span class="name">myPlugin</span>;
<span class="name">place</span>.<span class="name">name</span> <span class="operator">=</span> <span class="string">"New York"</span>;
<span class="name">place</span>.<span class="name">location</span>.<span class="name">coordinate</span>.<span class="name">latitude</span> <span class="operator">=</span> <span class="number">40.7</span>
<span class="name">place</span>.<span class="name">location</span>.<span class="name">coordinate</span>.<span class="name">longitude</span> <span class="operator">=</span> -<span class="number">74.0</span>
<span class="name">place</span>.<span class="name">save</span>();
<span class="comment">//removing a place</span>
<span class="name">place</span>.<span class="name">remove</span>();</pre>
<a name="learn-more"></a>
<h3 >Learn More</h3>
<p>The above snippets only exhibit a small subset of Places functionality. Refer to the <a href="location-places-qml.html#places-types">Places Types</a> shown below for richer content such as <a href="qml-qtlocation-imagemodel.html">images</a>, <a href="qml-qtlocation-reviewmodel.html">reviews</a> etc, as well as more indepth descriptions and explanations.</p>
<p>See also the <a href="qtlocation-places-example.html">Places (QML)</a> example for a more comprehensive demonstration on how to use the API.</p>
<a name="places-types"></a>
<h2 id="places-types">Places Types</h2>
<a name="data-types"></a>
<h3 >Data Types</h3>
<div class="table"><table class="annotated">
<tr class="odd topAlign"><td class="tblName"><p><a href="qml-qtlocation-category.html">Category</a></p></td><td class="tblDescr"><p>Type represents a category that a Place can be associated with</p></td></tr>
<tr class="even topAlign"><td class="tblName"><p><a href="qml-qtlocation-contactdetail.html">ContactDetail</a></p></td><td class="tblDescr"><p>Type holds a contact detail such as a phone number or a website address</p></td></tr>
<tr class="odd topAlign"><td class="tblName"><p><a href="qml-qtlocation-contactdetails.html">ContactDetails</a></p></td><td class="tblDescr"><p>Type holds contact details for a Place</p></td></tr>
<tr class="even topAlign"><td class="tblName"><p><a href="qml-qtlocation-extendedattributes.html">ExtendedAttributes</a></p></td><td class="tblDescr"><p>Type holds additional data about a Place</p></td></tr>
<tr class="odd topAlign"><td class="tblName"><p><a href="qml-qtlocation-icon.html">Icon</a></p></td><td class="tblDescr"><p>Type represents an icon image source which can have multiple sizes</p></td></tr>
<tr class="even topAlign"><td class="tblName"><p><a href="qml-qtlocation-place.html">Place</a></p></td><td class="tblDescr"><p>Type represents a location that is a position of interest</p></td></tr>
<tr class="odd topAlign"><td class="tblName"><p><a href="qml-qtlocation-placeattribute.html">PlaceAttribute</a></p></td><td class="tblDescr"><p>Type holds generic place attribute information</p></td></tr>
<tr class="even topAlign"><td class="tblName"><p><a href="qml-qtlocation-ratings.html">Ratings</a></p></td><td class="tblDescr"><p>Type holds place rating information</p></td></tr>
<tr class="odd topAlign"><td class="tblName"><p><a href="qml-qtlocation-supplier.html">Supplier</a></p></td><td class="tblDescr"><p>Holds data regarding the supplier of a place, a place's image, review, or editorial</p></td></tr>
<tr class="even topAlign"><td class="tblName"><p><a href="qml-qtlocation-user.html">User</a></p></td><td class="tblDescr"><p>Type identifies a user who contributed a particular Place content item</p></td></tr>
</table></div>
<a name="models"></a>
<h3 >Models</h3>
<div class="table"><table class="annotated">
<tr class="odd topAlign"><td class="tblName"><p><a href="qml-qtlocation-categorymodel.html">CategoryModel</a></p></td><td class="tblDescr"><p>Type provides a model of the categories supported by a Plugin</p></td></tr>
<tr class="even topAlign"><td class="tblName"><p><a href="qml-qtlocation-editorialmodel.html">EditorialModel</a></p></td><td class="tblDescr"><p>Type provides a model of place editorials</p></td></tr>
<tr class="odd topAlign"><td class="tblName"><p><a href="qml-qtlocation-imagemodel.html">ImageModel</a></p></td><td class="tblDescr"><p>Type provides a model of place images</p></td></tr>
<tr class="even topAlign"><td class="tblName"><p><a href="qml-qtlocation-placesearchmodel.html">PlaceSearchModel</a></p></td><td class="tblDescr"><p>Provides access to place search results</p></td></tr>
<tr class="odd topAlign"><td class="tblName"><p><a href="qml-qtlocation-placesearchsuggestionmodel.html">PlaceSearchSuggestionModel</a></p></td><td class="tblDescr"><p>Provides access to search term suggestions</p></td></tr>
<tr class="even topAlign"><td class="tblName"><p><a href="qml-qtlocation-reviewmodel.html">ReviewModel</a></p></td><td class="tblDescr"><p>Provides access to reviews of a Place</p></td></tr>
</table></div>
</div>
<!-- @@@location-places-qml.html -->
</div>
</div>
</div>
</div>
</div>
<div class="footer">
<p>
<acronym title="Copyright">©</acronym> 2015 The Qt Company Ltd.
Documentation contributions included herein are the copyrights of
their respective owners.<br> The documentation provided herein is licensed under the terms of the <a href="http://www.gnu.org/licenses/fdl.html">GNU Free Documentation License version 1.3</a> as published by the Free Software Foundation.<br> Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property
of their respective owners. </p>
</div>
</body>
</html>
|