KPeople

persondata.h
1 /*
2  KPeople
3  SPDX-FileCopyrightText: 2013 David Edmundson ([email protected])
4 
5  SPDX-License-Identifier: LGPL-2.1-or-later
6 */
7 
8 #ifndef PERSONDATA_H
9 #define PERSONDATA_H
10 
11 #include <kpeople/kpeople_export.h>
12 
13 #include <QObject>
14 #include <QPixmap>
15 
16 #include "global.h"
17 
18 namespace KPeople
19 {
20 class PersonDataPrivate;
21 
22 class PersonData;
23 
24 /**
25  * @brief Allows to query the information about a given person
26  *
27  * PersonData exposes the information of a given person (in contrast to everyone
28  * available, which is done by PersonsModel).
29  * This class will provide comfortable interfaces so it can be easily adopted
30  * in any application.
31  *
32  * @since 5.8
33  */
34 class KPEOPLE_EXPORT PersonData : public QObject
35 {
36  Q_OBJECT
37  Q_PROPERTY(QString name READ name NOTIFY dataChanged)
38  Q_PROPERTY(QPixmap photo READ photo NOTIFY dataChanged)
39  Q_PROPERTY(QString presenceIconName READ presenceIconName NOTIFY dataChanged)
40 
41  /**
42  * @returns whether setContactCustomProperty can be called on this contact
43  *
44  * @since 5.62
45  */
46  Q_PROPERTY(bool isEditable READ isEditable CONSTANT)
47 
48 public:
49  /** Creates a Person object from a given ID.
50  * The ID can be either a local application specific ID (such as akonadi://?item=15)
51  * or a kpeople ID in the form kpeople://15
52  */
53  PersonData(const QString &id, QObject *parent = nullptr);
54 
55  ~PersonData() override;
56 
57  /**
58  * Returns true if this PersonData is mapped to some existing contact
59  * @since 5.22
60  */
61  bool isValid() const;
62 
63  /** Returns the person's id */
64  QString personUri() const;
65 
66  /**
67  * Returns a list of contact ids that identify the PersonData instance.
68  */
69  QStringList contactUris() const;
70 
71  /**
72  * @returns the name of the person
73  */
74  QString name() const;
75 
76  /**
77  * @returns an icon name that represents the IM status of the person
78  */
79  QString presenceIconName() const;
80 
81  /**
82  * @returns a pixmap with the photo of the person, or a default one if not available
83  */
84  QPixmap photo() const;
85 
86  /**
87  * @returns the property for a said @p key.
88  */
89  Q_SCRIPTABLE QVariant contactCustomProperty(const QString &key) const;
90 
91  /**
92  * Sends a desired @p value for the contact according to the @p key.
93  * It's not necessarily implemented. The back-end gets to decide whether a property
94  * can be set or not.
95  *
96  * @returns whether the property value was changed
97  *
98  * @since 5.62
99  */
100  Q_SCRIPTABLE bool setContactCustomProperty(const QString &key, const QVariant &value);
101 
102  /**
103  * Returns the contact's online presence.
104  */
105  QString presence() const;
106 
107  /**
108  * Returns the contact's preferred email address.
109  */
110  QString email() const;
111 
112  /**
113  * Returns a the url of the picture that represents the contact.
114  */
115  QUrl pictureUrl() const;
116 
117  /** Returns all groups the person is in. */
118  QStringList groups() const;
119 
120  /** Returns all e-mail addresses from the person. */
121  QStringList allEmails() const;
122 
123  /**
124  * @returns whether the contact can be edited.
125  *
126  * @since 5.62
127  */
128  bool isEditable() const;
129 
130  // struct PhoneNumber {
131  // QString name;
132  // QString number;
133  // };
134  // QVector<PhoneNumber> phoneNumbers() const { createPhoneNumbers(customProperty("phoneNumbers")); };
135 
136 Q_SIGNALS:
137  /**
138  * One of the contact sources has changed
139  */
140  void dataChanged();
141 
142 private Q_SLOTS:
143  KPEOPLE_NO_EXPORT void onContactChanged();
144 
145 private:
146  Q_DISABLE_COPY(PersonData)
147  Q_DECLARE_PRIVATE(PersonData)
148  PersonDataPrivate *d_ptr;
149 };
150 }
151 
152 #endif // PERSONDATA_H
Allows to query the information about a given person.
Definition: persondata.h:34
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Sat Sep 30 2023 03:53:09 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.