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 QtContacts module of the Qt Toolkit.
7**
8** $QT_BEGIN_LICENSE:LGPL21$
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 2.1 or version 3 as published by the Free
20** Software Foundation and appearing in the file LICENSE.LGPLv21 and
21** LICENSE.LGPLv3 included in the packaging of this file. Please review the
22** following information to ensure the GNU Lesser General Public License
23** requirements will be met: https://www.gnu.org/licenses/lgpl.html and
24** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
25**
26** As a special exception, The Qt Company gives you certain additional
27** rights. These rights are described in The Qt Company LGPL Exception
28** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
29**
30** $QT_END_LICENSE$
31**
32****************************************************************************/
33
34#include "qcontactrelationshipfilter.h"
35#include "qcontactrelationshipfilter_p.h"
36
37QT_BEGIN_NAMESPACE_CONTACTS
38
39/*!
40 \class QContactRelationshipFilter
41 \brief The QContactRelationshipFilter class provides a filter based
42 around relationship criteria.
43
44
45 \inmodule QtContacts
46
47 \ingroup contacts-filters
48
49 It may be used to select contacts which are involved in relationships
50 which are of a certain type, or which involve certain contacts.
51
52 One common use-case might be to select the contacts which are a member of a particular group.
53 This use-case may be met with the following filter:
54
55 \code
56 QContactRelationshipFilter groupFilter; // select all contacts which are involved
57 groupFilter.setRelationshipType(QContactRelationship::HasMember); // in a group relationship
58 groupFilter.setRelatedContactId(groupContact.id()); // with the group contact
59 groupFilter.setRelatedContactRole(QContactRelationship::First); // where the group contact is the first participant
60 \endcode
61
62 Another common use-case might be to select the groups which a particular contact is a member of.
63 This use-case may be met with the following filter:
64
65 \code
66 QContactRelationshipFilter whichGroupsFilter; // select all contacts which are involved
67 whichGroupsFilter.setRelationshipType(QContactRelationship::HasMember); // in a group relationship
68 whichGroupsFilter.setRelatedContactId(particularContact.id()); // with the particular contact
69 whichGroupsFilter.setRelatedContactRole(QContactRelationship::Second); // where the particular contact is the second participant
70 \endcode
71
72 Relationships are also used to define composition of facets into contacts. To find the
73 facets from which a contact is composed:
74
75 \code
76 QContactRelationshipFilter whichFacetsFilter; // select all facets which are involved
77 whichFacetsFilter.setRelationshipType(QContactRelationship::Aggregates); // in an aggregation relationship
78 whichFacetsFilter.setRelatedContact(particularContact()); // with the particular contact
79 whichFacetsFilter.setRelatedContactRole(QContactRelationship::First); // where the particular contact is the first participant
80 \endcode
81
82 */
83
84Q_IMPLEMENT_CONTACTFILTER_PRIVATE(QContactRelationshipFilter)
85
86/*!
87 \fn QContactRelationshipFilter::QContactRelationshipFilter(const QContactFilter& other)
88 Constructs a copy of \a other if possible, else constructs a new QContactRelationshipFilter.
89 */
90
91/*!
92 Constructs a new relationship filter
93 */
94QContactRelationshipFilter::QContactRelationshipFilter()
95 : QContactFilter(new QContactRelationshipFilterPrivate)
96{
97}
98
99/*!
100 Sets the type of relationship which a contact must have in order to match this filter to \a relationshipType
101 */
102void QContactRelationshipFilter::setRelationshipType(const QString& relationshipType)
103{
104 Q_D(QContactRelationshipFilter);
105 d->m_relationshipType = relationshipType;
106}
107
108/*!
109 Returns the type of relationship that a contact must have in order to match the filter
110 */
111QString QContactRelationshipFilter::relationshipType() const
112{
113 Q_D(const QContactRelationshipFilter);
114 return d->m_relationshipType;
115}
116
117/*!
118 Sets the ID of the contact with whom the tested contact must have a relationship in order for the tested contact to match this filter, to be \a relatedContactId
119 */
120void QContactRelationshipFilter::setRelatedContactId(const QContactId &relatedContactId)
121{
122 Q_D(QContactRelationshipFilter);
123 d->m_relatedContactId = relatedContactId;
124}
125
126/*!
127 Returns the ID of the contact with whom the tested contact must have a relationship in order for the tested contact to match this filter
128 */
129QContactId QContactRelationshipFilter::relatedContactId() const
130{
131 Q_D(const QContactRelationshipFilter);
132 return d->m_relatedContactId;
133}
134
135/*!
136 Sets the role in the relationship with the tested contact that the related contact must play in order for the tested contact to match this filter to be \a relatedContactRole
137 */
138void QContactRelationshipFilter::setRelatedContactRole(QContactRelationship::Role relatedContactRole)
139{
140 Q_D(QContactRelationshipFilter);
141 d->m_relatedContactRole = relatedContactRole;
142}
143
144/*!
145 Returns the role in the relationship with the tested contact that the related contact must play in order for the tested contact to match this filter
146 */
147QContactRelationship::Role QContactRelationshipFilter::relatedContactRole() const
148{
149 Q_D(const QContactRelationshipFilter);
150 return d->m_relatedContactRole;
151}
152
153
154QT_END_NAMESPACE_CONTACTS
155

source code of qtpim/src/contacts/filters/qcontactrelationshipfilter.cpp