/usr/share/qt5/doc/qtlocation/qml-qtlocation-place.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 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 | <?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html>
<html lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<!-- qdeclarativeplace.cpp -->
<title>Place QML Type | 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><a href="qtlocation-qmlmodule.html">QML Types</a></li>
<li>Place QML Type</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="#properties">Properties</a></li>
<li class="level1"><a href="#methods">Methods</a></li>
<li class="level1"><a href="#details">Detailed Description</a></li>
<li class="level2"><a href="#saving-a-place">Saving a Place</a></li>
<li class="level2"><a href="#removing-a-place">Removing a Place</a></li>
<li class="level2"><a href="#favorites">Favorites</a></li>
</ul>
</div>
<div class="sidebar-content" id="sidebar-content"></div></div>
<h1 class="title">Place QML Type</h1>
<span class="subtitle"></span>
<!-- $$$Place-brief -->
<p>The Place type represents a location that is a position of interest. <a href="#details">More...</a></p>
<!-- @@@Place -->
<div class="table"><table class="alignedsummary">
<tr><td class="memItemLeft rightAlign topAlign"> Import Statement:</td><td class="memItemRight bottomAlign"> import QtLocation 5.3</td></tr><tr><td class="memItemLeft rightAlign topAlign"> Since:</td><td class="memItemRight bottomAlign"> Qt Location 5.5</td></tr></table></div><ul>
<li><a href="qml-qtlocation-place-members.html">List of all members, including inherited members</a></li>
</ul>
<a name="properties"></a>
<h2 id="properties">Properties</h2>
<ul>
<li class="fn"><b><b><a href="qml-qtlocation-place.html#attribution-prop">attribution</a></b></b> : string</li>
<li class="fn"><b><b><a href="qml-qtlocation-place.html#categories-prop">categories</a></b></b> : list<Category></li>
<li class="fn"><b><b><a href="qml-qtlocation-place.html#contactDetails-prop">contactDetails</a></b></b> : ContactDetails</li>
<li class="fn"><b><b><a href="qml-qtlocation-place.html#detailsFetched-prop">detailsFetched</a></b></b> : bool</li>
<li class="fn"><b><b><a href="qml-qtlocation-place.html#editorialModel-prop">editorialModel</a></b></b> : EditorialModel</li>
<li class="fn"><b><b><a href="qml-qtlocation-place.html#extendedAttributes-prop">extendedAttributes</a></b></b> : ExtendedAttributes</li>
<li class="fn"><b><b><a href="qml-qtlocation-place.html#favorite-prop">favorite</a></b></b> : Place</li>
<li class="fn"><b><b><a href="qml-qtlocation-place.html#icon-prop">icon</a></b></b> : Icon</li>
<li class="fn"><b><b><a href="qml-qtlocation-place.html#imageModel-prop">imageModel</a></b></b> : ImageModel</li>
<li class="fn"><b><b><a href="qml-qtlocation-place.html#location-prop">location</a></b></b> : QtPositioning::Location</li>
<li class="fn"><b><b><a href="qml-qtlocation-place.html#name-prop">name</a></b></b> : string</li>
<li class="fn"><b><b><a href="qml-qtlocation-place.html#place-prop">place</a></b></b> : QPlace</li>
<li class="fn"><b><b><a href="qml-qtlocation-place.html#placeId-prop">placeId</a></b></b> : string</li>
<li class="fn"><b><b><a href="qml-qtlocation-place.html#plugin-prop">plugin</a></b></b> : Plugin</li>
<li class="fn"><b><b><a href="qml-qtlocation-place.html#primaryEmail-prop">primaryEmail</a></b></b> : string</li>
<li class="fn"><b><b><a href="qml-qtlocation-place.html#primaryFax-prop">primaryFax</a></b></b> : string</li>
<li class="fn"><b><b><a href="qml-qtlocation-place.html#primaryPhone-prop">primaryPhone</a></b></b> : string</li>
<li class="fn"><b><b><a href="qml-qtlocation-place.html#primaryWebsite-prop">primaryWebsite</a></b></b> : string</li>
<li class="fn"><b><b><a href="qml-qtlocation-place.html#ratings-prop">ratings</a></b></b> : Ratings</li>
<li class="fn"><b><b><a href="qml-qtlocation-place.html#reviewModel-prop">reviewModel</a></b></b> : ReviewModel</li>
<li class="fn"><b><b><a href="qml-qtlocation-place.html#status-prop">status</a></b></b> : enumeration</li>
<li class="fn"><b><b><a href="qml-qtlocation-place.html#supplier-prop">supplier</a></b></b> : Supplier</li>
<li class="fn"><b><b><a href="qml-qtlocation-place.html#visibility-prop">visibility</a></b></b> : enumeration</li>
</ul>
<a name="methods"></a>
<h2 id="methods">Methods</h2>
<ul>
<li class="fn">void <b><b><a href="qml-qtlocation-place.html#copyFrom-method">copyFrom</a></b></b>(Place <i> original</i>)</li>
<li class="fn">string <b><b><a href="qml-qtlocation-place.html#errorString-method">errorString</a></b></b>()</li>
<li class="fn">void <b><b><a href="qml-qtlocation-place.html#getDetails-method">getDetails</a></b></b>()</li>
<li class="fn">void <b><b><a href="qml-qtlocation-place.html#initializeFavorite-method">initializeFavorite</a></b></b>(Plugin <i> destinationPlugin</i>)</li>
<li class="fn">void <b><b><a href="qml-qtlocation-place.html#remove-method">remove</a></b></b>()</li>
<li class="fn">void <b><b><a href="qml-qtlocation-place.html#save-method">save</a></b></b>()</li>
</ul>
<!-- $$$Place-description -->
<a name="details"></a>
<h2 id="details">Detailed Description</h2>
</p>
<p>The Place type represents a physical location with additional metadata describing that location. Contrasted with Location, Address, and coordinate type which are used to describe where a location is. The basic properties of a Place are its <a href="qml-qtlocation-place.html#name-prop">name</a> and <a href="qml-qtlocation-place.html#location-prop">location</a>.</p>
<p>Place objects are typically obtained from a search model and will generally only have their basic properties set. The <a href="qml-qtlocation-place.html#detailsFetched-prop">detailsFetched</a> property can be used to test if further property values need to be fetched from the <a href="location-places-qml.html#plugin">Plugin</a>. This can be done by invoking the <a href="qml-qtlocation-place.html#getDetails-method">getDetails()</a> method. Progress of the fetching operation can be monitored with the <a href="qml-qtlocation-place.html#status-prop">status</a> property, which will be set to Place.Fetching when the details are being fetched.</p>
<p>The Place type has many properties holding information about the location. Details on how to contact the place are available from the <a href="qml-qtlocation-place.html#contactDetails-prop">contactDetails</a> property. Convenience properties for obtaining the primary <a href="qml-qtlocation-place.html#primaryPhone-prop">phone</a>, <a href="qml-qtlocation-place.html#primaryFax-prop">fax</a>, <a href="qml-qtlocation-place.html#primaryEmail-prop">email</a> and <a href="qml-qtlocation-place.html#primaryWebsite-prop">website</a> are also available.</p>
<p>Each place is assigned zero or more <a href="location-places-backend.html#categories">categories</a>. Categories are typically used when searching for a particular kind of place, such as a restaurant or hotel. Some places have a <a href="qml-qtlocation-place.html#ratings-prop">ratings</a> object, which gives an indication of the quality of the place.</p>
<p>Place metadata is provided by a <a href="qml-qtlocation-place.html#supplier-prop">supplier</a> who may require that an <a href="qplace.html#attribution">attribution</a> message be displayed to the user when the place details are viewed.</p>
<p>Places have an associated <a href="qml-qtlocation-place.html#icon-prop">icon</a> which can be used to represent a place on a map or to decorate a delegate in a view.</p>
<p>Places may have additional rich content associated with them. The currently supported rich content include editorial descriptions, reviews and images. These are exposed as a set of models for retrieving the content. Editorial descriptions of the place are available from the <a href="qml-qtlocation-place.html#editorialModel-prop">editorialModel</a> property. Reviews of the place are available from the <a href="qml-qtlocation-place.html#reviewModel-prop">reviewModel</a> property. A gallery of pictures of the place can be accessed using the <a href="qml-qtlocation-place.html#imageModel-prop">imageModel</a> property.</p>
<p>Places may have additional attributes which are not covered in the formal API. The <a href="qml-qtlocation-place.html#extendedAttributes-prop">extendedAttributes</a> property provides access to these. The type of extended attributes available is specific to each <a href="location-places-qml.html#plugin">Plugin</a>.</p>
<p>A Place is almost always tied to a <a href="location-places-qml.html#plugin">plugin</a>. The <a href="location-places-qml.html#plugin">plugin</a> property must be set before it is possible to call <a href="qml-qtlocation-place.html#save-method">save()</a>, <a href="qml-qtlocation-place.html#remove-method">remove()</a> or <a href="qml-qtlocation-place.html#getDetails-method">getDetails()</a>. The <a href="qml-qtlocation-place.html#reviewModel-prop">reviewModel</a>, <a href="qml-qtlocation-place.html#imageModel-prop">imageModel</a> and <a href="qml-qtlocation-place.html#editorialModel-prop">editorialModel</a> are only valid then the <a href="location-places-qml.html#plugin">plugin</a> property is set.</p>
<a name="saving-a-place"></a>
<h3 >Saving a Place</h3>
<p>If the <a href="location-places-qml.html#plugin">Plugin</a> supports it, the Place type can be used to save a place. First create a new Place and set its properties:</p>
<pre class="qml"><span class="type"><a href="qml-qtlocation-place.html">Place</a></span> {
<span class="name">id</span>: <span class="name">myPlace</span>
<span class="name">plugin</span>: <span class="name">myPlugin</span>
<span class="name">name</span>: <span class="string">"Brisbane Technology Park"</span>
<span class="name">location</span>: <span class="name">Location</span> {
<span class="name">address</span>: <span class="name">Address</span> {
<span class="name">street</span>: <span class="string">"53 Brandl Street"</span>
<span class="name">city</span>: <span class="string">"Eight Mile Plains"</span>
<span class="name">postalCode</span>: <span class="string">"4113"</span>
<span class="name">country</span>: <span class="string">"Australia"</span>
}
<span class="type">coordinate</span> {
<span class="name">latitude</span>: -<span class="number">27.579646</span>
<span class="name">longitude</span>: <span class="number">153.100308</span>
}
}
<span class="name">visibility</span>: <span class="name">Place</span>.<span class="name">PrivateVisibility</span>
}</pre>
<p>Then invoke the <a href="qml-qtlocation-place.html#save-method">save()</a> method:</p>
<pre class="qml"> <span class="name">myPlace</span>.<span class="name">save</span>();</pre>
<p>The <a href="qml-qtlocation-place.html#status-prop">status</a> property will change to Place.Saving and then to Place.Ready if the save was successful or to Place.Error if an error occurs.</p>
<p>If the <a href="qml-qtlocation-place.html#placeId-prop">placeId</a> property is set, the backend will update an existing place otherwise it will create a new place. On success the <a href="qml-qtlocation-place.html#placeId-prop">placeId</a> property will be updated with the identifier of the newly saved place.</p>
<a name="caveats"></a>
<h4 >Caveats</h4>
<p>The Places API is currently designed for only saving <i>core</i> details. Saving rich content like images and reviews or details like supplier and rating is not a supported use case. Typically a manager will generally ignore these fields upon save and may produce a warning message if they are populated.</p>
<p>The Places API only supports saving of the following <i>core details</i>:</p>
<ul>
<li>name</li>
<li>place id</li>
<li>location</li>
<li>contact details</li>
<li>icon</li>
<li>categories (tag-like names to describe a place)</li>
<li>visibility scope</li>
</ul>
<p>It is possible that providers may only support a subset of these. See the <a href="qtlocation-index.html#plugin-references-and-parameters">plugin documentation</a> for more details.</p>
<p>Saving of properties such as the rating, extended attributes, images, reviews, editorials and supplier is explicitly not supported by the Places API.</p>
<a name="saving-between-plugins"></a>
<h4 >Saving Between Plugins</h4>
<p>When saving places between plugins, there are a few things to be aware of. Some fields of a place such as the id, categories and icons are plugin specific entities. For example the categories in one manager may not be recognised in another. Therefore trying to save a place directly from one plugin to another is not possible.</p>
<p>It is generally recommended that saving across plugins be handled as saving <a href="qml-qtlocation-place.html#favorites">favorites</a> as explained in the Favorites section. However there is another approach which is to create a new place, set its (destination) plugin and then use the <a href="qml-qtlocation-place.html#copyFrom-method">copyFrom()</a> method to copy the details of the original place. Using <a href="qml-qtlocation-place.html#copyFrom-method">copyFrom()</a> only copies data that is supported by the destination plugin, plugin specific data such as the place identifier is not copied over. Once the copy is done, the place is in a suitable state to be saved.</p>
<p>The following snippet provides an example of saving a place to a different plugin using the <a href="qml-qtlocation-place.html#copyFrom-method">copyFrom</a> method:</p>
<pre class="qml">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">destinationPlugin</span>;
<span class="name">place</span>.<span class="name">copyFrom</span>(<span class="name">originalPlace</span>);
<span class="name">place</span>.<span class="name">save</span>();</pre>
<a name="removing-a-place"></a>
<h3 >Removing a Place</h3>
<p>To remove a place, ensure that a Place object with a valid <a href="qml-qtlocation-place.html#placeId-prop">placeId</a> property exists and call its <a href="qml-qtlocation-place.html#remove-method">remove()</a> method. The <a href="qml-qtlocation-place.html#status-prop">status</a> property will change to Place.Removing and then to Place.Ready if the save was successful or to Place.Error if an error occurs.</p>
<a name="favorites"></a>
<h3 >Favorites</h3>
<p>The Places API supports the concept of favorites. Favorites are generally implemented by using two plugins, the first plugin is typically a read-only source of places (origin plugin) and a second read/write plugin (destination plugin) is used to store places from the origin as favorites.</p>
<p>Each Place has a favorite property which is intended to contain the corresponding place from the destination plugin (the place itself is sourced from the origin plugin). Because both the original place and favorite instances are available, the developer can choose which properties to show to the user. For example the favorite may have a modified name which should be displayed rather than the original name.</p>
<pre class="qml"><span class="type">Text</span> { <span class="name">text</span>: <span class="name">place</span>.<span class="name">favorite</span> ? <span class="name">place</span>.<span class="name">favorite</span>.<span class="name">name</span> : <span class="name">place</span>.<span class="name">name</span> }</pre>
<p>The following demonstrates how to save a new favorite instance. A call is made to create/initialize the favorite instance and then the instance is saved.</p>
<pre class="qml"><span class="name">place</span>.<span class="name">initializeFavorite</span>(<span class="name">destinationPlugin</span>);
<span class="comment">//if necessary customizations to the favorite can be made here.</span>
<span class="comment">//...</span>
<span class="name">place</span>.<span class="name">favorite</span>.<span class="name">save</span>();</pre>
<p>The following demonstrates favorite removal:</p>
<pre class="qml"><span class="name">place</span>.<span class="name">favorite</span>.<span class="name">remove</span>();
...
<span class="comment">//check successful removal of the favorite by monitoring its status.</span>
<span class="comment">//once that is done we can assign null to the favorite</span>
<span class="name">place</span>.<span class="name">favorite</span> <span class="operator">=</span> <span class="number">null</span>;</pre>
<p>The <a href="qml-qtlocation-placesearchmodel.html">PlaceSearchModel</a> has a favoritesPlugin property. If the property is set, any places found during a search are checked against the favoritesPlugin to see if there is a corresponding favorite place. If so, the favorite property of the Place is set, otherwise the favorite property is remains null.</p>
<p><b>See also </b><a href="qml-qtlocation-placesearchmodel.html">PlaceSearchModel</a>.</p>
<!-- @@@Place -->
<h2>Property Documentation</h2>
<!-- $$$attribution -->
<div class="qmlitem"><div class="qmlproto"><div class="table"><table class="qmlname"><tr valign="top" class="odd" id="attribution-prop"><td class="tblQmlPropNode"><p><a name="attribution-prop"></a><span class="name">attribution</span> : <span class="type">string</span></p></td></tr></table></div></div><div class="qmldoc"><p>This property holds a rich text attribution string for the place. Some providers may require that the attribution be shown to the user whenever a place is displayed. The contents of this property should be shown to the user if it is not empty.</p>
</div></div><!-- @@@attribution -->
<br/>
<!-- $$$categories -->
<div class="qmlitem"><div class="qmlproto"><div class="table"><table class="qmlname"><tr valign="top" class="odd" id="categories-prop"><td class="tblQmlPropNode"><p><a name="categories-prop"></a><span class="name">categories</span> : <span class="type">list</span><<span class="type"><a href="qml-qtlocation-category.html">Category</a></span>></p></td></tr></table></div></div><div class="qmldoc"><p>This property holds the list of categories this place is a member of. The categories that can be assigned to a place are specific to each <a href="location-places-qml.html#plugin">plugin</a>.</p>
</div></div><!-- @@@categories -->
<br/>
<!-- $$$contactDetails -->
<div class="qmlitem"><div class="qmlproto"><div class="table"><table class="qmlname"><tr valign="top" class="odd" id="contactDetails-prop"><td class="tblQmlPropNode"><p><a name="contactDetails-prop"></a><span class="name">contactDetails</span> : <span class="type"><a href="qml-qtlocation-contactdetails.html">ContactDetails</a></span></p></td></tr></table></div></div><div class="qmldoc"><p>This property holds the contact information for this place, for example a phone number or a website URL. This property is a map of <a href="qml-qtlocation-contactdetail.html">ContactDetail</a> objects.</p>
</div></div><!-- @@@contactDetails -->
<br/>
<!-- $$$detailsFetched -->
<div class="qmlitem"><div class="qmlproto"><div class="table"><table class="qmlname"><tr valign="top" class="odd" id="detailsFetched-prop"><td class="tblQmlPropNode"><p><a name="detailsFetched-prop"></a><span class="name">detailsFetched</span> : <span class="type">bool</span></p></td></tr></table></div></div><div class="qmldoc"><p>This property indicates whether the details of the place have been fetched. If this property is false, the place details have not yet been fetched. Fetching can be done by invoking the <a href="qml-qtlocation-place.html#getDetails-method">getDetails()</a> method.</p>
<p><b>See also </b><a href="qml-qtlocation-place.html#getDetails-method">getDetails()</a>.</p>
</div></div><!-- @@@detailsFetched -->
<br/>
<!-- $$$editorialModel -->
<div class="qmlitem"><div class="qmlproto"><div class="table"><table class="qmlname"><tr valign="top" class="odd" id="editorialModel-prop"><td class="tblQmlPropNode"><p><a name="editorialModel-prop"></a><span class="name">editorialModel</span> : <span class="type"><a href="qml-qtlocation-editorialmodel.html">EditorialModel</a></span></p></td></tr></table></div></div><div class="qmldoc"><p>This property holds a model which can be used to retrieve editorial descriptions of the place.</p>
</div></div><!-- @@@editorialModel -->
<br/>
<!-- $$$extendedAttributes -->
<div class="qmlitem"><div class="qmlproto"><div class="table"><table class="qmlname"><tr valign="top" class="odd" id="extendedAttributes-prop"><td class="tblQmlPropNode"><p><a name="extendedAttributes-prop"></a><span class="name">extendedAttributes</span> : <span class="type"><a href="qml-qtlocation-extendedattributes.html">ExtendedAttributes</a></span></p></td></tr></table></div></div><div class="qmldoc"><p>This property holds the extended attributes of a place. Extended attributes are additional information about a place not covered by the place's properties.</p>
</div></div><!-- @@@extendedAttributes -->
<br/>
<!-- $$$favorite -->
<div class="qmlitem"><div class="qmlproto"><div class="table"><table class="qmlname"><tr valign="top" class="odd" id="favorite-prop"><td class="tblQmlPropNode"><p><a name="favorite-prop"></a><span class="name">favorite</span> : <span class="type"><a href="qml-qtlocation-place.html">Place</a></span></p></td></tr></table></div></div><div class="qmldoc"><p>This property holds the favorite instance of a place.</p>
</div></div><!-- @@@favorite -->
<br/>
<!-- $$$icon -->
<div class="qmlitem"><div class="qmlproto"><div class="table"><table class="qmlname"><tr valign="top" class="odd" id="icon-prop"><td class="tblQmlPropNode"><p><a name="icon-prop"></a><span class="name">icon</span> : <span class="type"><a href="qml-qtlocation-icon.html">Icon</a></span></p></td></tr></table></div></div><div class="qmldoc"><p>This property holds a graphical icon which can be used to represent the place.</p>
</div></div><!-- @@@icon -->
<br/>
<!-- $$$imageModel -->
<div class="qmlitem"><div class="qmlproto"><div class="table"><table class="qmlname"><tr valign="top" class="odd" id="imageModel-prop"><td class="tblQmlPropNode"><p><a name="imageModel-prop"></a><span class="name">imageModel</span> : <span class="type"><a href="qml-qtlocation-imagemodel.html">ImageModel</a></span></p></td></tr></table></div></div><div class="qmldoc"><p>This property holds a model which can be used to retrieve images of the place.</p>
</div></div><!-- @@@imageModel -->
<br/>
<!-- $$$location -->
<div class="qmlitem"><div class="qmlproto"><div class="table"><table class="qmlname"><tr valign="top" class="odd" id="location-prop"><td class="tblQmlPropNode"><p><a name="location-prop"></a><span class="name">location</span> : <span class="type">QtPositioning::Location</span></p></td></tr></table></div></div><div class="qmldoc"><p>This property holds the location of the place which can be used to retrieve the coordinate, address and the bounding box.</p>
</div></div><!-- @@@location -->
<br/>
<!-- $$$name -->
<div class="qmlitem"><div class="qmlproto"><div class="table"><table class="qmlname"><tr valign="top" class="odd" id="name-prop"><td class="tblQmlPropNode"><p><a name="name-prop"></a><span class="name">name</span> : <span class="type">string</span></p></td></tr></table></div></div><div class="qmldoc"><p>This property holds the name of the place which can be used to represent the place.</p>
</div></div><!-- @@@name -->
<br/>
<!-- $$$place -->
<div class="qmlitem"><div class="qmlproto"><div class="table"><table class="qmlname"><tr valign="top" class="odd" id="place-prop"><td class="tblQmlPropNode"><p><a name="place-prop"></a><span class="name">place</span> : <span class="type"><a href="qplace.html">QPlace</a></span></p></td></tr></table></div></div><div class="qmldoc"><p>For details on how to use this property to interface between C++ and QML see "<a href="location-cpp-qml.html#place-qplace">Interfaces between C++ and QML Code</a>".</p>
</div></div><!-- @@@place -->
<br/>
<!-- $$$placeId -->
<div class="qmlitem"><div class="qmlproto"><div class="table"><table class="qmlname"><tr valign="top" class="odd" id="placeId-prop"><td class="tblQmlPropNode"><p><a name="placeId-prop"></a><span class="name">placeId</span> : <span class="type">string</span></p></td></tr></table></div></div><div class="qmldoc"><p>This property holds the unique identifier of the place. The place identifier is only meaningful to the <a href="location-places-qml.html#plugin">Plugin</a> that generated it and is not transferable between <a href="location-places-qml.html#plugin">Plugins</a>. The place id is not guaranteed to be universally unique, but unique within the <a href="location-places-qml.html#plugin">Plugin</a> that generated it.</p>
<p>If only the place identifier is known, all other place data can fetched from the <a href="location-places-qml.html#plugin">Plugin</a>.</p>
<pre class="qml"> <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">placeId</span> <span class="operator">=</span> <span class="string">"known-place-id"</span>;
<span class="name">place</span>.<span class="name">getDetails</span>();</pre>
</div></div><!-- @@@placeId -->
<br/>
<!-- $$$plugin -->
<div class="qmlitem"><div class="qmlproto"><div class="table"><table class="qmlname"><tr valign="top" class="odd" id="plugin-prop"><td class="tblQmlPropNode"><p><a name="plugin-prop"></a><span class="name">plugin</span> : <span class="type"><a href="qml-qtlocation-plugin.html">Plugin</a></span></p></td></tr></table></div></div><div class="qmldoc"><p>This property holds the <a href="location-places-qml.html#plugin">Plugin</a> that provided this place which can be used to retrieve more information about the service.</p>
</div></div><!-- @@@plugin -->
<br/>
<!-- $$$primaryEmail -->
<div class="qmlitem"><div class="qmlproto"><div class="table"><table class="qmlname"><tr valign="top" class="odd" id="primaryEmail-prop"><td class="tblQmlPropNode"><p><a name="primaryEmail-prop"></a><span class="name">primaryEmail</span> : <span class="type">string</span></p></td></tr></table></div></div><div class="qmldoc"><p>This property holds the primary email address of the place. If no "email" contact detail is defined for this place this property will be an empty string. It is equivalent to</p>
<pre class="qml"> var <span class="name">primaryEmail</span>;
<span class="keyword">if</span> (<span class="name">place</span>.<span class="name">contactDetails</span>[<span class="string">"email"</span>].<span class="name">length</span> <span class="operator">></span> <span class="number">0</span>)
<span class="name">primaryEmail</span> <span class="operator">=</span> <span class="name">place</span>.<span class="name">contactDetails</span>[<span class="string">"email"</span>][<span class="number">0</span>].<span class="name">value</span>;</pre>
</div></div><!-- @@@primaryEmail -->
<br/>
<!-- $$$primaryFax -->
<div class="qmlitem"><div class="qmlproto"><div class="table"><table class="qmlname"><tr valign="top" class="odd" id="primaryFax-prop"><td class="tblQmlPropNode"><p><a name="primaryFax-prop"></a><span class="name">primaryFax</span> : <span class="type">string</span></p></td></tr></table></div></div><div class="qmldoc"><p>This property holds the primary fax number of the place. If no "fax" contact detail is defined for this place this property will be an empty string. It is equivalent to</p>
<pre class="qml"> var <span class="name">primaryFax</span>;
<span class="keyword">if</span> (<span class="name">place</span>.<span class="name">contactDetails</span>[<span class="string">"fax"</span>].<span class="name">length</span> <span class="operator">></span> <span class="number">0</span>)
<span class="name">primaryFax</span> <span class="operator">=</span> <span class="name">place</span>.<span class="name">contactDetails</span>[<span class="string">"fax"</span>][<span class="number">0</span>].<span class="name">value</span>;</pre>
</div></div><!-- @@@primaryFax -->
<br/>
<!-- $$$primaryPhone -->
<div class="qmlitem"><div class="qmlproto"><div class="table"><table class="qmlname"><tr valign="top" class="odd" id="primaryPhone-prop"><td class="tblQmlPropNode"><p><a name="primaryPhone-prop"></a><span class="name">primaryPhone</span> : <span class="type">string</span></p></td></tr></table></div></div><div class="qmldoc"><p>This property holds the primary phone number of the place. If no "phone" contact detail is defined for this place, this property will be an empty string. It is equivalent to:</p>
<pre class="qml"> var <span class="name">primaryPhone</span>;
<span class="keyword">if</span> (<span class="name">place</span>.<span class="name">contactDetails</span>[<span class="string">"phone"</span>].<span class="name">length</span> <span class="operator">></span> <span class="number">0</span>)
<span class="name">primaryPhone</span> <span class="operator">=</span> <span class="name">place</span>.<span class="name">contactDetails</span>[<span class="string">"phone"</span>][<span class="number">0</span>].<span class="name">value</span>;</pre>
</div></div><!-- @@@primaryPhone -->
<br/>
<!-- $$$primaryWebsite -->
<div class="qmlitem"><div class="qmlproto"><div class="table"><table class="qmlname"><tr valign="top" class="odd" id="primaryWebsite-prop"><td class="tblQmlPropNode"><p><a name="primaryWebsite-prop"></a><span class="name">primaryWebsite</span> : <span class="type">string</span></p></td></tr></table></div></div><div class="qmldoc"><p>This property holds the primary website url of the place. If no "website" contact detail is defined for this place this property will be an empty string. It is equivalent to</p>
<pre class="qml"> var <span class="name">primaryWebsite</span>;
<span class="keyword">if</span> (<span class="name">place</span>.<span class="name">contactDetails</span>[<span class="string">"website"</span>].<span class="name">length</span> <span class="operator">></span> <span class="number">0</span>)
<span class="name">primaryWebsite</span> <span class="operator">=</span> <span class="name">place</span>.<span class="name">contactDetails</span>[<span class="string">"website"</span>][<span class="number">0</span>].<span class="name">value</span>;</pre>
</div></div><!-- @@@primaryWebsite -->
<br/>
<!-- $$$ratings -->
<div class="qmlitem"><div class="qmlproto"><div class="table"><table class="qmlname"><tr valign="top" class="odd" id="ratings-prop"><td class="tblQmlPropNode"><p><a name="ratings-prop"></a><span class="name">ratings</span> : <span class="type"><a href="qml-qtlocation-ratings.html">Ratings</a></span></p></td></tr></table></div></div><div class="qmldoc"><p>This property holds ratings of the place. The ratings provide an indication of the quality of a place.</p>
</div></div><!-- @@@ratings -->
<br/>
<!-- $$$reviewModel -->
<div class="qmlitem"><div class="qmlproto"><div class="table"><table class="qmlname"><tr valign="top" class="odd" id="reviewModel-prop"><td class="tblQmlPropNode"><p><a name="reviewModel-prop"></a><span class="name">reviewModel</span> : <span class="type"><a href="qml-qtlocation-reviewmodel.html">ReviewModel</a></span></p></td></tr></table></div></div><div class="qmldoc"><p>This property holds a model which can be used to retrieve reviews about the place.</p>
</div></div><!-- @@@reviewModel -->
<br/>
<!-- $$$status -->
<div class="qmlitem"><div class="qmlproto"><div class="table"><table class="qmlname"><tr valign="top" class="odd" id="status-prop"><td class="tblQmlPropNode"><p><a name="status-prop"></a><span class="name">status</span> : <span class="type">enumeration</span></p></td></tr></table></div></div><div class="qmldoc"><p>This property holds the status of the place. It can be one of:</p>
<div class="table"><table class="generic">
<tr valign="top" class="odd"><td >Place.Ready</td><td >No error occurred during the last operation, further operations may be performed on the place.</td></tr>
<tr valign="top" class="even"><td >Place.Saving</td><td >The place is currently being saved, no other operation may be performed until complete.</td></tr>
<tr valign="top" class="odd"><td >Place.Fetching</td><td >The place details are currently being fetched, no other operations may be performed until complete.</td></tr>
<tr valign="top" class="even"><td >Place.Removing</td><td >The place is currently being removed, no other operations can be performed until complete.</td></tr>
<tr valign="top" class="odd"><td >Place.Error</td><td >An error occurred during the last operation, further operations can still be performed on the place.</td></tr>
</table></div>
<p>The status of a place can be checked by connecting the status property to a handler function, and then have the handler function process the change in status.</p>
<pre class="qml"><span class="name">place</span>.<span class="name">statusChanged</span>.<span class="name">connect</span>(<span class="name">statusChangedHandler</span>);
...
<span class="keyword">function</span> <span class="name">statusChangedHandler</span>() {
<span class="keyword">if</span> (<span class="name">statusChangedHandler</span>.<span class="name">prevStatus</span> <span class="operator">===</span> <span class="name">Place</span>.<span class="name">Saving</span>) {
<span class="keyword">switch</span> (<span class="name">place</span>.<span class="name">status</span>) {
<span class="keyword">case</span> <span class="name">Place</span>.<span class="name">Ready</span>:
<span class="name">console</span>.<span class="name">log</span>(<span class="string">'Save successful'</span>);
<span class="keyword">break</span>;
<span class="keyword">case</span> <span class="name">Place</span>.<span class="name">Error</span>:
<span class="name">console</span>.<span class="name">log</span>(<span class="string">'Save failed'</span>);
<span class="keyword">break</span>;
<span class="keyword">default</span>:
<span class="keyword">break</span>;
}
}
<span class="name">statusChangedHandler</span>.<span class="name">prevStatus</span> <span class="operator">=</span> <span class="name">place</span>.<span class="name">status</span>;
}</pre>
</div></div><!-- @@@status -->
<br/>
<!-- $$$supplier -->
<div class="qmlitem"><div class="qmlproto"><div class="table"><table class="qmlname"><tr valign="top" class="odd" id="supplier-prop"><td class="tblQmlPropNode"><p><a name="supplier-prop"></a><span class="name">supplier</span> : <span class="type"><a href="qml-qtlocation-supplier.html">Supplier</a></span></p></td></tr></table></div></div><div class="qmldoc"><p>This property holds the supplier of the place data. The supplier is typically a business or organization that collected the data about the place.</p>
</div></div><!-- @@@supplier -->
<br/>
<!-- $$$visibility -->
<div class="qmlitem"><div class="qmlproto"><div class="table"><table class="qmlname"><tr valign="top" class="odd" id="visibility-prop"><td class="tblQmlPropNode"><p><a name="visibility-prop"></a><span class="name">visibility</span> : <span class="type">enumeration</span></p></td></tr></table></div></div><div class="qmldoc"><p>This property holds the visibility of the place. It can be one of:</p>
<div class="table"><table class="generic">
<tr valign="top" class="odd"><td >Place.UnspecifiedVisibility</td><td >The visibility of the place is unspecified, the default visibility of the <a href="location-places-qml.html#plugin">Plugin</a> will be used.</td></tr>
<tr valign="top" class="even"><td >Place.DeviceVisibility</td><td >The place is limited to the current device. The place will not be transferred off of the device.</td></tr>
<tr valign="top" class="odd"><td >Place.PrivateVisibility</td><td >The place is private to the current user. The place may be transferred to an online service but is only ever visible to the current user.</td></tr>
<tr valign="top" class="even"><td >Place.PublicVisibility</td><td >The place is public.</td></tr>
</table></div>
<p>Note that visibility does not affect how the place is displayed in the user-interface of an application on the device. Instead, it defines the sharing semantics of the place.</p>
</div></div><!-- @@@visibility -->
<br/>
<h2>Method Documentation</h2>
<!-- $$$copyFrom -->
<div class="qmlitem"><div class="qmlproto"><div class="table"><table class="qmlname"><tr valign="top" class="odd" id="copyFrom-method"><td class="tblQmlFuncNode"><p><a name="copyFrom-method"></a><span class="type">void</span> <span class="name">copyFrom</span>(<span class="type"><a href="qml-qtlocation-place.html">Place</a></span><i> original</i>)</p></td></tr></table></div></div><div class="qmldoc"><p>Copies data from an <i>original</i> place into this place. Only data that is supported by this place's plugin is copied over and plugin specific data such as place identifier is not copied over.</p>
</div></div><!-- @@@copyFrom -->
<br/>
<!-- $$$errorString -->
<div class="qmlitem"><div class="qmlproto"><div class="table"><table class="qmlname"><tr valign="top" class="odd" id="errorString-method"><td class="tblQmlFuncNode"><p><a name="errorString-method"></a><span class="type">string</span> <span class="name">errorString</span>()</p></td></tr></table></div></div><div class="qmldoc"><p>Returns a string description of the error of the last operation. If the last operation completed successfully then the string is empty.</p>
</div></div><!-- @@@errorString -->
<br/>
<!-- $$$getDetails -->
<div class="qmlitem"><div class="qmlproto"><div class="table"><table class="qmlname"><tr valign="top" class="odd" id="getDetails-method"><td class="tblQmlFuncNode"><p><a name="getDetails-method"></a><span class="type">void</span> <span class="name">getDetails</span>()</p></td></tr></table></div></div><div class="qmldoc"><p>This method starts fetching place details.</p>
<p>The <a href="qml-qtlocation-place.html#status-prop">status</a> property will change to Place.Fetching while the fetch is in progress. On success the object's properties will be updated, <a href="qml-qtlocation-place.html#status-prop">status</a> will be set to Place.Ready and <a href="qml-qtlocation-place.html#detailsFetched-prop">detailsFetched</a> will be set to true. On error <a href="qml-qtlocation-place.html#status-prop">status</a> will be set to Place.Error. The <a href="qml-qtlocation-place.html#errorString-method">errorString()</a> method can be used to get the details of the error.</p>
</div></div><!-- @@@getDetails -->
<br/>
<!-- $$$initializeFavorite -->
<div class="qmlitem"><div class="qmlproto"><div class="table"><table class="qmlname"><tr valign="top" class="odd" id="initializeFavorite-method"><td class="tblQmlFuncNode"><p><a name="initializeFavorite-method"></a><span class="type">void</span> <span class="name">initializeFavorite</span>(<span class="type"><a href="qml-qtlocation-plugin.html">Plugin</a></span><i> destinationPlugin</i>)</p></td></tr></table></div></div><div class="qmldoc"><p>Creates a favorite instance for the place which is to be saved into the <i>destination</i> plugin. This method does nothing if the favorite property is not null.</p>
</div></div><!-- @@@initializeFavorite -->
<br/>
<!-- $$$remove -->
<div class="qmlitem"><div class="qmlproto"><div class="table"><table class="qmlname"><tr valign="top" class="odd" id="remove-method"><td class="tblQmlFuncNode"><p><a name="remove-method"></a><span class="type">void</span> <span class="name">remove</span>()</p></td></tr></table></div></div><div class="qmldoc"><p>This method performs a remove operation on the place.</p>
<p>The <a href="qml-qtlocation-place.html#status-prop">status</a> property will change to Place.Removing while the save operation is in progress. On success <a href="qml-qtlocation-place.html#status-prop">status</a> will be set to Place.Ready. On error <a href="qml-qtlocation-place.html#status-prop">status</a> will be set to Place.Error. The <a href="qml-qtlocation-place.html#errorString-method">errorString()</a> method can be used to get the details of the error.</p>
</div></div><!-- @@@remove -->
<br/>
<!-- $$$save -->
<div class="qmlitem"><div class="qmlproto"><div class="table"><table class="qmlname"><tr valign="top" class="odd" id="save-method"><td class="tblQmlFuncNode"><p><a name="save-method"></a><span class="type">void</span> <span class="name">save</span>()</p></td></tr></table></div></div><div class="qmldoc"><p>This method performs a save operation on the place.</p>
<p>The <a href="qml-qtlocation-place.html#status-prop">status</a> property will change to Place.Saving while the save operation is in progress. On success the <a href="qml-qtlocation-place.html#status-prop">status</a> will be set to Place.Ready. On error <a href="qml-qtlocation-place.html#status-prop">status</a> will be set to Place.Error. The <a href="qml-qtlocation-place.html#errorString-method">errorString()</a> method can be used to get the details of the error.</p>
<p>If the <a href="qml-qtlocation-place.html#placeId-prop">placeId</a> property was previously empty, it will be assigned a valid value automatically during a successful save operation.</p>
<p>Note that a <a href="qml-qtlocation-placesearchmodel.html">PlaceSearchModel</a> will call <a href="qml-qtlocation-place.html#getDetails-method">Place::getDetails</a> on any place that it detects an update on. A consequence of this is that whenever a Place from a <a href="qml-qtlocation-placesearchmodel.html">PlaceSearchModel</a> is successfully saved, it will be followed by a fetch of place details, leading to a sequence of state changes of <code>Saving</code>, <code>Ready</code>, <code>Fetching</code>, <code>Ready</code>.</p>
</div></div><!-- @@@save -->
<br/>
</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>
|