KContacts

contactgroup.h
1 /*
2  This file is part of the KContacts framework.
3  SPDX-FileCopyrightText: 2008 Tobias Koenig <[email protected]>
4 
5  SPDX-License-Identifier: LGPL-2.0-or-later
6 */
7 
8 #ifndef KCONTACTS_CONTACTGROUP_H
9 #define KCONTACTS_CONTACTGROUP_H
10 
11 #include <QMetaType>
12 #include <QSharedDataPointer>
13 #include <QVector>
14 
15 #include "kcontacts_export.h"
16 
17 class QString;
18 
19 namespace KContacts
20 {
21 /**
22  * @short This class represents a group of contacts.
23  *
24  * It can contain two types of contacts, either a reference
25  * or data.
26  * The reference entry is just an unique identifier which
27  * identifies the real contact in the system.
28  * The data entry contains a name and an email address.
29  *
30  * @author Tobias Koenig <[email protected]>
31  * @since 4.3
32  */
33 class KCONTACTS_EXPORT ContactGroup
34 {
35 public:
36  /**
37  * This class represents a contact reference
38  */
39  class KCONTACTS_EXPORT ContactReference
40  {
41  public:
42  /**
43  * A list of contact references.
44  */
46 
47  /**
48  * Creates an empty contact reference.
49  */
51 
52  /**
53  * Creates a contact reference from an @p other reference.
54  */
55  ContactReference(const ContactReference &other);
56 
57  /**
58  * Creates a contact reference for the given contact @p uid.
59  */
60  ContactReference(const QString &uid);
61 
62  /**
63  * Destroys the contact reference.
64  */
66 
67  /**
68  * Sets the contact uid of the contact reference.
69  * @param uid identifier of the contact to reference
70  * @note That is the Akonadi Item ID of the contact that
71  * is referenced here.
72  */
73  void setUid(const QString &uid);
74 
75  /**
76  * Returns the contact uid of the contact reference.
77  *
78  * @note That is the Akonadi Item ID of the contact that
79  * is referenced here.
80  */
81  Q_REQUIRED_RESULT QString uid() const;
82 
83  /**
84  * Sets the contact gid of the contact reference.
85  * @param gid globally unique identifier of the contact to reference
86  * @since 4.12
87  */
88  void setGid(const QString &gid);
89 
90  /**
91  * Returns the contact GID of the contact reference.
92  * @since 4.12
93  */
94  Q_REQUIRED_RESULT QString gid() const;
95 
96  /**
97  * Sets the preferred email address.
98  */
99  void setPreferredEmail(const QString &email);
100 
101  /**
102  * Returns the preferred email address, or an empty string
103  * if no preferred email address is set.
104  */
105  Q_REQUIRED_RESULT QString preferredEmail() const;
106 
107  /**
108  * Inserts a custom entry.
109  * If an entry with the same @p key already exists, it is
110  * overwritten.
111  *
112  * @param key The unique key.
113  * @param value The value.
114  */
115  void insertCustom(const QString &key, const QString &value);
116 
117  /**
118  * Removes the custom entry with the given @p key.
119  */
120  void removeCustom(const QString &key);
121 
122  /**
123  * Returns the value for the given @p key, or an empty string
124  * if the entry for that key does not exists.
125  */
126  Q_REQUIRED_RESULT QString custom(const QString &key) const;
127 
128  /**
129  * @internal
130  */
131  ContactReference &operator=(const ContactReference &other);
132 
133  /**
134  * @internal
135  */
136  Q_REQUIRED_RESULT bool operator==(const ContactReference &other) const;
137 
138  private:
139  class ContactReferencePrivate;
141  };
142 
143  /**
144  * This class represents a contact group reference
145  */
146  class KCONTACTS_EXPORT ContactGroupReference
147  {
148  public:
149  /**
150  * A list of contact group references.
151  */
153 
154  /**
155  * Creates an empty contact group reference.
156  */
158 
159  /**
160  * Creates a contact group reference from an @p other reference.
161  */
163 
164  /**
165  * Creates a contact group reference for the given contact group @p uid.
166  */
167  ContactGroupReference(const QString &uid);
168 
169  /**
170  * Destroys the contact group reference.
171  */
173 
174  /**
175  * Sets the contact group uid of the contact group reference.
176  */
177  void setUid(const QString &uid);
178 
179  /**
180  * Returns the contact group uid of the contact group reference.
181  */
182  QString uid() const;
183 
184  /**
185  * Inserts a custom entry.
186  * If an entry with the same @p key already exists, it is
187  * overwritten.
188  *
189  * @param key The unique key.
190  * @param value The value.
191  */
192  void insertCustom(const QString &key, const QString &value);
193 
194  /**
195  * Removes the custom entry with the given @p key.
196  */
197  void removeCustom(const QString &key);
198 
199  /**
200  * Returns the value for the given @p key, or an empty string
201  * if the entry for that key does not exists.
202  */
203  QString custom(const QString &key) const;
204 
205  /**
206  * @internal
207  */
208  ContactGroupReference &operator=(const ContactGroupReference &other);
209 
210  /**
211  * @internal
212  */
213  bool operator==(const ContactGroupReference &other) const;
214 
215  private:
216  class ContactGroupReferencePrivate;
218  };
219 
220  /**
221  * This class represents a contact data object
222  */
223  class KCONTACTS_EXPORT Data
224  {
225  public:
226  /**
227  * A list of contact data.
228  */
230 
231  /**
232  * Creates an empty contact data object.
233  */
234  Data();
235 
236  /**
237  * Creates a contact data object from an @p other data object.
238  */
239  Data(const Data &other);
240 
241  /**
242  * Creates a contact data object with the given @p name and @p email address.
243  */
244  Data(const QString &name, const QString &email);
245 
246  /**
247  * Destroys the contact data object.
248  */
249  ~Data();
250 
251  /**
252  * Sets the @p name of the contact data object.
253  */
254  void setName(const QString &name);
255 
256  /**
257  * Returns the name of the contact data object.
258  */
259  Q_REQUIRED_RESULT QString name() const;
260 
261  /**
262  * Sets the @p email address of the contact data object.
263  */
264  void setEmail(const QString &email);
265 
266  /**
267  * Returns the email address of the contact data object.
268  */
269  Q_REQUIRED_RESULT QString email() const;
270 
271  /**
272  * Inserts a custom entry.
273  * If an entry with the same @p key already exists, it is
274  * overwritten.
275  *
276  * @param key The unique key.
277  * @param value The value.
278  */
279  void insertCustom(const QString &key, const QString &value);
280 
281  /**
282  * Removes the custom entry with the given @p key.
283  */
284  void removeCustom(const QString &key);
285 
286  /**
287  * Returns the value for the given @p key, or an empty string
288  * if the entry for that key does not exists.
289  */
290  Q_REQUIRED_RESULT QString custom(const QString &key) const;
291 
292  /**
293  * @internal
294  */
295  Data &operator=(const Data &other);
296 
297  /**
298  * @internal
299  */
300  Q_REQUIRED_RESULT bool operator==(const Data &other) const;
301 
302  private:
303  class DataPrivate;
305  };
306 
307  /**
308  * A list of contact groups.
309  */
311 
312  /**
313  * Creates an empty contact group.
314  */
315  ContactGroup();
316 
317  /**
318  * Creates a contact group from an @p other group.
319  */
320  ContactGroup(const ContactGroup &other);
321 
322  /**
323  * Creates a contact group with the given name.
324  */
325  ContactGroup(const QString &name);
326 
327  /**
328  * Destroys the contact group.
329  */
330  ~ContactGroup();
331 
332  /**
333  * Sets the unique @p id of the contact group.
334  */
335  void setId(const QString &id);
336 
337  /**
338  * Returns the unique id of the contact group.
339  */
340  Q_REQUIRED_RESULT QString id() const;
341 
342  /**
343  * Sets the i18n'd @p name of the contact group.
344  */
345  void setName(const QString &name);
346 
347  /**
348  * Returns the i18n'd name of the contact group.
349  */
350  Q_REQUIRED_RESULT QString name() const;
351 
352  /**
353  * Returns the number of contacts in this group.
354  * That includes the contact references and contact data.
355  */
356  Q_REQUIRED_RESULT int count() const;
357 
358  /**
359  * Returns the number of contact references in this group.
360  */
361  Q_REQUIRED_RESULT int contactReferenceCount() const;
362 
363  /**
364  * Returns the number of group references in this group.
365  */
366  Q_REQUIRED_RESULT int contactGroupReferenceCount() const;
367 
368  /**
369  * Returns the number of contact data objects in this group.
370  */
371  Q_REQUIRED_RESULT int dataCount() const;
372 
373  /**
374  * Returns the contact reference at the given @p index.
375  */
376  Q_REQUIRED_RESULT ContactReference &contactReference(int index);
377 
378  /**
379  * Returns the contact reference at the given @p index.
380  */
381  const ContactReference &contactReference(int index) const;
382 
383  /**
384  * Returns the contact group reference at the given @p index.
385  */
386  ContactGroupReference &contactGroupReference(int index);
387 
388  /**
389  * Returns the contact group reference at the given @p index.
390  */
391  const ContactGroupReference &contactGroupReference(int index) const;
392 
393  /**
394  * Returns the contact data object at the given @p index.
395  */
396  Data &data(int index);
397 
398  /**
399  * Returns the contact data object at the given @p index.
400  */
401  const Data &data(int index) const;
402 
403  /**
404  * Appends a new contact @p reference to the contact group.
405  */
406  void append(const ContactReference &reference);
407 
408  /**
409  * Appends a new contact group @p reference to the contact group.
410  */
411  void append(const ContactGroupReference &reference);
412 
413  /**
414  * Appends a new contact @p data object to the contact group.
415  */
416  void append(const Data &data);
417 
418  /**
419  * Removes the given contact @p reference from the contact group.
420  */
421  void remove(const ContactReference &reference);
422 
423  /**
424  * Removes the given contact group @p reference from the contact group.
425  */
426  void remove(const ContactGroupReference &reference);
427 
428  /**
429  * Removes the given contact @p data object from the contact group.
430  */
431  void remove(const Data &data);
432 
433  /**
434  * Removes all contact references from the contact group.
435  */
436  void removeAllContactReferences();
437 
438  /**
439  * Removes all contact group references from the contact group.
440  */
441  void removeAllContactGroupReferences();
442 
443  /**
444  * Removes all contact data from the contact group.
445  */
446  void removeAllContactData();
447 
448  /**
449  * @internal
450  */
451  ContactGroup &operator=(const ContactGroup &other);
452 
453  /**
454  * @internal
455  */
456  Q_REQUIRED_RESULT bool operator==(const ContactGroup &other) const;
457 
458  /**
459  * Returns the MIME type used for Contact Groups
460  */
461  static QString mimeType();
462 
463 private:
464  class Private;
466 };
467 }
468 Q_DECLARE_TYPEINFO(KContacts::ContactGroup::ContactGroupReference, Q_MOVABLE_TYPE);
469 Q_DECLARE_TYPEINFO(KContacts::ContactGroup::ContactReference, Q_MOVABLE_TYPE);
470 
471 #define KCONTACTS_CONTACTGROUP_METATYPE_DEFINED
472 Q_DECLARE_METATYPE(KContacts::ContactGroup)
473 
474 #endif
This class represents a group of contacts.
Definition: contactgroup.h:33
This class represents a contact group reference.
Definition: contactgroup.h:146
QVector< Data > List
A list of contact data.
Definition: contactgroup.h:229
QVector< ContactGroup > List
A list of contact groups.
Definition: contactgroup.h:310
This class represents a contact reference.
Definition: contactgroup.h:39
QVector< ContactGroupReference > List
A list of contact group references.
Definition: contactgroup.h:152
This class represents a contact data object.
Definition: contactgroup.h:223
QVector< ContactReference > List
A list of contact references.
Definition: contactgroup.h:45
This file is part of the KDE documentation.
Documentation copyright © 1996-2021 The KDE developers.
Generated on Fri Jun 18 2021 22:54:48 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.