1 | /**************************************************************************** |
2 | ** |
3 | ** Copyright (C) 2015 The Qt Company Ltd. |
4 | ** Contact: http://www.qt.io/licensing/ |
5 | ** |
6 | ** This file is part of the QtLocation module of the Qt Toolkit. |
7 | ** |
8 | ** $QT_BEGIN_LICENSE:LGPL3$ |
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 http://www.qt.io/terms-conditions. For further |
15 | ** information use the contact form at http://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.LGPLv3 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.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 later as published by the Free |
28 | ** Software Foundation and appearing in the file LICENSE.GPL included in |
29 | ** the packaging of this file. Please review the following information to |
30 | ** ensure the GNU General Public License version 2.0 requirements will be |
31 | ** met: http://www.gnu.org/licenses/gpl-2.0.html. |
32 | ** |
33 | ** $QT_END_LICENSE$ |
34 | ** |
35 | ****************************************************************************/ |
36 | |
37 | #include "qdeclarativecontactdetail_p.h" |
38 | |
39 | QT_BEGIN_NAMESPACE |
40 | |
41 | /*! |
42 | \qmltype ContactDetails |
43 | \instantiates QDeclarativeContactDetails |
44 | \inqmlmodule QtLocation |
45 | \ingroup qml-QtLocation5-places |
46 | \ingroup qml-QtLocation5-places-data |
47 | \since QtLocation 5.5 |
48 | |
49 | \brief The ContactDetails type holds contact details for a \l Place. |
50 | |
51 | The ContactDetails type is a map of \l {QtLocation::ContactDetail}{ContactDetail} objects. |
52 | To access contact details in the map use the \l keys() method to get the list of keys stored in |
53 | the map and then use the \c {[]} operator to access the |
54 | \l {QtLocation::ContactDetail}{ContactDetail} items. |
55 | |
56 | The following keys are defined in the API. \l Plugin implementations are free to define |
57 | additional keys. |
58 | |
59 | \list |
60 | \li phone |
61 | \li fax |
62 | \li email |
63 | \li website |
64 | \endlist |
65 | |
66 | ContactDetails instances are only ever used in the context of \l {Place}{Places}. It is not possible |
67 | to create a ContactDetails instance directly or re-assign ContactDetails instances to \l {Place}{Places}. |
68 | Modification of ContactDetails can only be accomplished via Javascript. |
69 | |
70 | \section1 Examples |
71 | |
72 | The following example shows how to access all \l {QtLocation::ContactDetail}{ContactDetails} |
73 | and print them to the console: |
74 | |
75 | \snippet declarative/maps.qml QtLocation import |
76 | \codeline |
77 | \snippet declarative/places.qml ContactDetails read |
78 | |
79 | The returned list of contact details is an \l {QObjectList-based model}{object list} and so can be used directly as a data model. For example, the |
80 | following demonstrates how to display a list of contact phone numbers in a list view: |
81 | |
82 | \snippet declarative/places.qml QtQuick import |
83 | \snippet declarative/maps.qml QtLocation import |
84 | \codeline |
85 | \snippet declarative/places.qml ContactDetails phoneList |
86 | |
87 | The following example demonstrates how to assign a single phone number to a place in JavaScript: |
88 | \snippet declarative/places.qml ContactDetails write single |
89 | |
90 | The following demonstrates how to assign multiple phone numbers to a place in JavaScript: |
91 | \snippet declarative/places.qml ContactDetails write multiple |
92 | */ |
93 | |
94 | /*! |
95 | \qmlmethod variant ContactDetails::keys() |
96 | |
97 | Returns an array of contact detail keys currently stored in the map. |
98 | */ |
99 | QDeclarativeContactDetails::QDeclarativeContactDetails(QObject *parent) |
100 | : QQmlPropertyMap(parent) |
101 | { |
102 | } |
103 | |
104 | QVariant QDeclarativeContactDetails::updateValue(const QString &, const QVariant &input) |
105 | { |
106 | if (input.userType() == QMetaType::QObjectStar) { |
107 | QDeclarativeContactDetail *detail = |
108 | qobject_cast<QDeclarativeContactDetail *>(object: input.value<QObject *>()); |
109 | if (detail) { |
110 | QVariantList varList; |
111 | varList.append(t: input); |
112 | return varList; |
113 | } |
114 | } |
115 | |
116 | return input; |
117 | } |
118 | |
119 | /*! |
120 | \qmltype ContactDetail |
121 | \instantiates QDeclarativeContactDetail |
122 | \inqmlmodule QtLocation |
123 | \ingroup qml-QtLocation5-places |
124 | \ingroup qml-QtLocation5-places-data |
125 | \since QtLocation 5.5 |
126 | |
127 | \brief The ContactDetail type holds a contact detail such as a phone number or a website |
128 | address. |
129 | |
130 | The ContactDetail provides a single detail on how one could contact a \l Place. The |
131 | ContactDetail consists of a \l label, which is a localized string describing the contact |
132 | method, and a \l value representing the actual contact detail. |
133 | |
134 | \section1 Examples |
135 | |
136 | The following example demonstrates how to assign a single phone number to a place in JavaScript: |
137 | \snippet declarative/places.qml ContactDetails write single |
138 | |
139 | The following demonstrates how to assign multiple phone numbers to a place in JavaScript: |
140 | \snippet declarative/places.qml ContactDetails write multiple |
141 | |
142 | Note, due to limitations of the QQmlPropertyMap, it is not possible |
143 | to declaratively specify the contact details in QML, it can only be accomplished |
144 | via JavaScript. |
145 | */ |
146 | QDeclarativeContactDetail::QDeclarativeContactDetail(QObject *parent) |
147 | : QObject(parent) |
148 | { |
149 | } |
150 | |
151 | QDeclarativeContactDetail::QDeclarativeContactDetail(const QPlaceContactDetail &src, QObject *parent) |
152 | : QObject(parent), m_contactDetail(src) |
153 | { |
154 | } |
155 | |
156 | QDeclarativeContactDetail::~QDeclarativeContactDetail() |
157 | { |
158 | } |
159 | |
160 | /*! |
161 | \qmlproperty QPlaceContactDetail QtLocation::ContactDetail::contactDetail |
162 | |
163 | For details on how to use this property to interface between C++ and QML see |
164 | "\l {ContactDetail - QDeclarativeContactDetail} {Interfaces between C++ and QML Code}". |
165 | */ |
166 | void QDeclarativeContactDetail::setContactDetail(const QPlaceContactDetail &src) |
167 | { |
168 | QPlaceContactDetail prevContactDetail = m_contactDetail; |
169 | m_contactDetail = src; |
170 | |
171 | if (m_contactDetail.label() != prevContactDetail.label()) |
172 | emit labelChanged(); |
173 | if (m_contactDetail.value() != prevContactDetail.value()) |
174 | emit valueChanged(); |
175 | } |
176 | |
177 | QPlaceContactDetail QDeclarativeContactDetail::contactDetail() const |
178 | { |
179 | return m_contactDetail; |
180 | } |
181 | |
182 | /*! |
183 | \qmlproperty string QtLocation::ContactDetail::label |
184 | |
185 | This property holds a label describing the contact detail. |
186 | |
187 | The label can potentially be localized. The language is dependent on the entity that sets it, |
188 | typically this is the \l {Plugin}. The \l {Plugin::locales} property defines |
189 | what language is used. |
190 | */ |
191 | QString QDeclarativeContactDetail::label() const |
192 | { |
193 | return m_contactDetail.label(); |
194 | } |
195 | |
196 | void QDeclarativeContactDetail::setLabel(const QString &label) |
197 | { |
198 | if (m_contactDetail.label() != label) { |
199 | m_contactDetail.setLabel(label); |
200 | emit labelChanged(); |
201 | } |
202 | } |
203 | |
204 | /*! |
205 | \qmlproperty string QtLocation::ContactDetail::value |
206 | |
207 | This property holds the value of the contact detail which may be a phone number, an email |
208 | address, a website url and so on. |
209 | */ |
210 | QString QDeclarativeContactDetail::value() const |
211 | { |
212 | return m_contactDetail.value(); |
213 | } |
214 | |
215 | void QDeclarativeContactDetail::setValue(const QString &value) |
216 | { |
217 | if (m_contactDetail.value() != value) { |
218 | m_contactDetail.setValue(value); |
219 | emit valueChanged(); |
220 | } |
221 | } |
222 | |
223 | QT_END_NAMESPACE |
224 | |