1 /****************************************************************************
2 **
3 ** Copyright (C) 2016 The Qt Company Ltd.
4 ** Contact: https://www.qt.io/licensing/
5 **
6 ** This file is part of the QtPositioning module of the Qt Toolkit.
7 **
8 ** $QT_BEGIN_LICENSE:LGPL$
9 ** Commercial License Usage
10 ** Licensees holding valid commercial Qt licenses may use this file in
11 ** accordance with the commercial license agreement provided with the
12 ** Software or, alternatively, in accordance with the terms contained in
13 ** a written agreement between you and The Qt Company. For licensing terms
14 ** and conditions see https://www.qt.io/terms-conditions. For further
15 ** information use the contact form at https://www.qt.io/contact-us.
16 **
17 ** GNU Lesser General Public License Usage
18 ** Alternatively, this file may be used under the terms of the GNU Lesser
19 ** General Public License version 3 as published by the Free Software
20 ** Foundation and appearing in the file LICENSE.LGPL3 included in the
21 ** packaging of this file. Please review the following information to
22 ** ensure the GNU Lesser General Public License version 3 requirements
23 ** will be met: https://www.gnu.org/licenses/lgpl-3.0.html.
24 **
25 ** GNU General Public License Usage
26 ** Alternatively, this file may be used under the terms of the GNU
27 ** General Public License version 2.0 or (at your option) the GNU General
28 ** Public license version 3 or any later version approved by the KDE Free
29 ** Qt Foundation. The licenses are as published by the Free Software
30 ** Foundation and appearing in the file LICENSE.GPL2 and LICENSE.GPL3
31 ** included in the packaging of this file. Please review the following
32 ** information to ensure the GNU General Public License requirements will
33 ** be met: https://www.gnu.org/licenses/gpl-2.0.html and
34 ** https://www.gnu.org/licenses/gpl-3.0.html.
35 **
36 ** $QT_END_LICENSE$
37 **
38 ***************************************************************************/
39
40 #include "qdeclarativegeoaddress_p.h"
41
42 QT_BEGIN_NAMESPACE
43
44 /*!
45 \qmltype Address
46 \inqmlmodule QtPositioning
47 \since 5.2
48
49 \brief The Address QML type represents a specific location as a street address.
50
51 An Address is used as a unit of data for queries such as (Reverse) Geocoding
52 or Places searches -- many of these operations either accept an Address
53 or return one.
54
55 Not all properties of an Address are necessarily available or relevant
56 in all parts of the world and all locales. The \l district, \l state and
57 \l county properties are particularly area-specific for many data sources,
58 and often only one or two of these are available or useful.
59
60 The Address has a \l text property which holds a formatted string. It
61 is the recommended way to display an address to the user and typically
62 takes the format of an address as found on an envelope, but this is not always
63 the case. The \l text may be automatically generated from constituent
64 address properties such as \l street, \l city and and so on, but can also
65 be explicitly assigned. See \l text for details.
66
67 \section2 Example Usage
68
69 The following code snippet shows the declaration of an Address object.
70
71 \code
72 Address {
73 id: address
74 street: "53 Brandl St"
75 city: "Eight Mile Plains"
76 country: "Australia"
77 countryCode: "AUS"
78 }
79 \endcode
80
81 This could then be used, for example, as the value of a geocoding query,
82 to get an exact longitude and latitude for the address.
83
84 \sa {QGeoAddress}
85 */
86
QDeclarativeGeoAddress(QObject * parent)87 QDeclarativeGeoAddress::QDeclarativeGeoAddress(QObject *parent) :
88 QObject(parent)
89 {
90 }
91
QDeclarativeGeoAddress(const QGeoAddress & address,QObject * parent)92 QDeclarativeGeoAddress::QDeclarativeGeoAddress(const QGeoAddress &address, QObject *parent) :
93 QObject(parent), m_address(address)
94 {
95 }
96
97 /*!
98 \qmlproperty QGeoAddress QtPositioning::Address::address
99
100 For details on how to use this property to interface between C++ and QML see
101 "\l {Address - QGeoAddress} {Interfaces between C++ and QML Code}".
102 */
address() const103 QGeoAddress QDeclarativeGeoAddress::address() const
104 {
105 return m_address;
106 }
107
setAddress(const QGeoAddress & address)108 void QDeclarativeGeoAddress::setAddress(const QGeoAddress &address)
109 {
110 // Elaborate but takes care of emiting needed signals
111 setText(address.text());
112 setCountry(address.country());
113 setCountryCode(address.countryCode());
114 setState(address.state());
115 setCounty(address.county());
116 setCity(address.city());
117 setDistrict(address.district());
118 setStreet(address.street());
119 setPostalCode(address.postalCode());
120 m_address = address;
121 }
122
123 /*!
124 \qmlproperty string QtPositioning::Address::text
125
126 This property holds the address as a single formatted string. It is the recommended
127 string to use to display the address to the user. It typically takes the format of
128 an address as found on an envelope, but this is not always necessarily the case.
129
130 The address \c text is either automatically generated or explicitly assigned,
131 this can be determined by checking \l isTextGenerated.
132
133 If an empty string is assigned to \c text, then \l isTextGenerated will be set
134 to true and \c text will return a string which is locally formatted according to
135 \l countryCode and based on the properties of the address. Modifying the address
136 properties such as \l street, \l city and so on may cause the contents of \c text to
137 change.
138
139 If a non-empty string is assigned to \c text, then \l isTextGenerated will be
140 set to false and \c text will always return the explicitly assigned string.
141 Modifying address properties will not affect the \c text property.
142 */
text() const143 QString QDeclarativeGeoAddress::text() const
144 {
145 return m_address.text();
146 }
147
setText(const QString & address)148 void QDeclarativeGeoAddress::setText(const QString &address)
149 {
150 QString oldText = m_address.text();
151 bool oldIsTextGenerated = m_address.isTextGenerated();
152 m_address.setText(address);
153
154 if (oldText != m_address.text())
155 emit textChanged();
156 if (oldIsTextGenerated != m_address.isTextGenerated())
157 emit isTextGeneratedChanged();
158 }
159
160 /*!
161 \qmlproperty string QtPositioning::Address::country
162
163 This property holds the country of the address as a single formatted string.
164 */
country() const165 QString QDeclarativeGeoAddress::country() const
166 {
167 return m_address.country();
168 }
169
setCountry(const QString & country)170 void QDeclarativeGeoAddress::setCountry(const QString &country)
171 {
172 if (m_address.country() == country)
173 return;
174 QString oldText = m_address.text();
175 m_address.setCountry(country);
176 emit countryChanged();
177
178 if (m_address.isTextGenerated() && oldText != m_address.text())
179 emit textChanged();
180 }
181
182 /*!
183 \qmlproperty string QtPositioning::Address::countryCode
184
185 This property holds the country code of the address as a single formatted string.
186 */
countryCode() const187 QString QDeclarativeGeoAddress::countryCode() const
188 {
189 return m_address.countryCode();
190 }
191
setCountryCode(const QString & countryCode)192 void QDeclarativeGeoAddress::setCountryCode(const QString &countryCode)
193 {
194 if (m_address.countryCode() == countryCode)
195 return;
196 QString oldText = m_address.text();
197 m_address.setCountryCode(countryCode);
198 emit countryCodeChanged();
199
200 if (m_address.isTextGenerated() && oldText != m_address.text())
201 emit textChanged();
202 }
203
204 /*!
205 \qmlproperty string QtPositioning::Address::state
206
207 This property holds the state of the address as a single formatted string.
208 */
state() const209 QString QDeclarativeGeoAddress::state() const
210 {
211 return m_address.state();
212 }
213
setState(const QString & state)214 void QDeclarativeGeoAddress::setState(const QString &state)
215 {
216 if (m_address.state() == state)
217 return;
218 QString oldText = m_address.text();
219 m_address.setState(state);
220 emit stateChanged();
221
222 if (m_address.isTextGenerated() && oldText != m_address.text())
223 emit textChanged();
224 }
225
226 /*!
227 \qmlproperty string QtPositioning::Address::county
228
229 This property holds the county of the address as a single formatted string.
230 */
county() const231 QString QDeclarativeGeoAddress::county() const
232 {
233 return m_address.county();
234 }
235
setCounty(const QString & county)236 void QDeclarativeGeoAddress::setCounty(const QString &county)
237 {
238 if (m_address.county() == county)
239 return;
240 QString oldText = m_address.text();
241 m_address.setCounty(county);
242 emit countyChanged();
243
244 if (m_address.isTextGenerated() && oldText != m_address.text())
245 emit textChanged();
246 }
247
248 /*!
249 \qmlproperty string QtPositioning::Address::city
250
251 This property holds the city of the address as a single formatted string.
252 */
city() const253 QString QDeclarativeGeoAddress::city() const
254 {
255 return m_address.city();
256 }
257
setCity(const QString & city)258 void QDeclarativeGeoAddress::setCity(const QString &city)
259 {
260 if (m_address.city() == city)
261 return;
262 QString oldText = m_address.text();
263 m_address.setCity(city);
264 emit cityChanged();
265
266 if (m_address.isTextGenerated() && oldText != m_address.text())
267 emit textChanged();
268 }
269
270 /*!
271 \qmlproperty string QtPositioning::Address::district
272
273 This property holds the district of the address as a single formatted string.
274 */
district() const275 QString QDeclarativeGeoAddress::district() const
276 {
277 return m_address.district();
278 }
279
setDistrict(const QString & district)280 void QDeclarativeGeoAddress::setDistrict(const QString &district)
281 {
282 if (m_address.district() == district)
283 return;
284 QString oldText = m_address.text();
285 m_address.setDistrict(district);
286 emit districtChanged();
287
288 if (m_address.isTextGenerated() && oldText != m_address.text())
289 emit textChanged();
290 }
291
292 /*!
293 \qmlproperty string QtPositioning::Address::street
294
295 This property holds the street of the address but
296 may also contain things like a unit number, a building
297 name, or anything else that might be used to
298 distinguish one address from another.
299 */
street() const300 QString QDeclarativeGeoAddress::street() const
301 {
302 return m_address.street();
303 }
304
setStreet(const QString & street)305 void QDeclarativeGeoAddress::setStreet(const QString &street)
306 {
307 if (m_address.street() == street)
308 return;
309 QString oldText = m_address.text();
310 m_address.setStreet(street);
311 emit streetChanged();
312
313 if (m_address.isTextGenerated() && oldText != m_address.text())
314 emit textChanged();
315 }
316
317 /*!
318 \qmlproperty string QtPositioning::Address::postalCode
319
320 This property holds the postal code of the address as a single formatted string.
321 */
postalCode() const322 QString QDeclarativeGeoAddress::postalCode() const
323 {
324 return m_address.postalCode();
325 }
326
setPostalCode(const QString & postalCode)327 void QDeclarativeGeoAddress::setPostalCode(const QString &postalCode)
328 {
329 if (m_address.postalCode() == postalCode)
330 return;
331 QString oldText = m_address.text();
332 m_address.setPostalCode(postalCode);
333 emit postalCodeChanged();
334
335 if (m_address.isTextGenerated() && oldText != m_address.text())
336 emit textChanged();
337 }
338
339 /*!
340 \qmlproperty bool QtPositioning::Address::isTextGenerated
341
342 This property holds a boolean that if true, indicates that \l text is automatically
343 generated from address properties. If false, it indicates that the \l text has been
344 explicitly assigned.
345
346 */
isTextGenerated() const347 bool QDeclarativeGeoAddress::isTextGenerated() const
348 {
349 return m_address.isTextGenerated();
350 }
351
352 QT_END_NAMESPACE
353