Akonadi Contacts

contactviewer.h
1 /*
2  This file is part of Akonadi Contact.
3 
4  SPDX-FileCopyrightText: 2009 Tobias Koenig <[email protected]>
5 
6  SPDX-License-Identifier: LGPL-2.0-or-later
7 */
8 
9 #pragma once
10 
11 #include "akonadi-contact_export.h"
12 
13 #include <itemmonitor.h>
14 
15 #include <QWidget>
16 
17 namespace KContacts
18 {
19 class Address;
20 class Addressee;
21 class PhoneNumber;
22 }
23 
24 namespace Akonadi
25 {
26 class AbstractContactFormatter;
27 
28 /**
29  * @short A viewer component for contacts in Akonadi.
30  *
31  * This widgets provides a way to show a contact from the
32  * Akonadi storage or a raw contact object.
33  *
34  * Examples:
35  *
36  * @code
37  *
38  * using namespace Akonadi;
39  *
40  * const Item contact = ...
41  *
42  * ContactViewer *viewer = new ContactViewer( this );
43  * viewer->setContact( contact );
44  *
45  * @endcode
46 
47  * @code
48  *
49  * using namespace Akonadi;
50  *
51  * const KContacts::Addressee contact = ...
52  *
53  * ContactViewer *viewer = new ContactViewer( this );
54  * viewer->setContact( contact );
55  *
56  * @endcode
57  *
58  * @author Tobias Koenig <[email protected]>
59  * @since 4.4
60  */
61 class AKONADI_CONTACT_EXPORT ContactViewer : public QWidget, public Akonadi::ItemMonitor
62 {
63  Q_OBJECT
64 
65 public:
66  /**
67  * Creates a new contact viewer.
68  *
69  * @param parent The parent widget.
70  */
71  explicit ContactViewer(QWidget *parent = nullptr);
72 
73  /**
74  * Destroys the contact viewer.
75  */
76  ~ContactViewer() override;
77 
78  /**
79  * Returns the contact that is currently displayed.
80  *
81  * @note The returned contact is only valid if it was
82  * set with setContact() before.
83  */
84  Q_REQUIRED_RESULT Akonadi::Item contact() const;
85 
86  /**
87  * Returns the raw contact that is currently displayed.
88  *
89  * @since 4.5
90  */
91  Q_REQUIRED_RESULT KContacts::Addressee rawContact() const;
92 
93  /**
94  * Sets the contact @p formatter that should be used for formatting the
95  * contact. If formatter is @c 0, the standard formatter will be used.
96  * @param formatter the contact formatter to set
97  * @note The contact viewer won't take ownership of the formatter.
98  *
99  * @since 4.6
100  */
101  void setContactFormatter(AbstractContactFormatter *formatter);
102  /**
103  * @since 5.1
104  */
105  void updateView();
106 
107  /**
108  * @since 5.2
109  */
110  void setShowQRCode(bool b);
111  Q_REQUIRED_RESULT bool showQRCode() const;
112 public Q_SLOTS:
113  /**
114  * Sets the @p contact that shall be displayed in the viewer.
115  */
116  void setContact(const Akonadi::Item &contact);
117 
118  /**
119  * Sets the raw @p contact object that shall be displayed in the viewer.
120  * @param contact the contact object to set
121  * @since 4.5
122  */
123  void setRawContact(const KContacts::Addressee &contact);
124 
125 Q_SIGNALS:
126  /**
127  * This signal is emitted whenever the user has clicked on
128  * a url (e.g. homepage or blog url) in the viewer.
129  *
130  * @param url The url that has been clicked.
131  */
132  void urlClicked(const QUrl &url);
133 
134  /**
135  * This signal is emitted whenever the user has clicked on
136  * an email address in the viewer.
137  *
138  * @param name The name of the contact.
139  * @param email The plain email address of the contact.
140  */
141  void emailClicked(const QString &name, const QString &email);
142 
143  /**
144  * This signal is emitted whenever the user has clicked on a
145  * phone number (that includes fax numbers as well) in the viewer.
146  *
147  * @param number The corresponding phone number.
148  */
149  void phoneNumberClicked(const KContacts::PhoneNumber &number);
150 
151  /**
152  * This signal is emitted whenever the user has clicked on a SMS link of a
153  * phone number in the viewer.
154  *
155  * @param number The corresponding phone number.
156  */
157  void smsClicked(const KContacts::PhoneNumber &number);
158 
159  /**
160  * This signal is emitted whenever the user has clicked on an
161  * address in the viewer.
162  *
163  * @param address The corresponding address.
164  */
165  void addressClicked(const KContacts::Address &address);
166 
167 private:
168  /**
169  * This method is called whenever the displayed contact has been changed.
170  */
171  void itemChanged(const Item &contact) override;
172 
173  /**
174  * This method is called whenever the displayed contact has been
175  * removed from Akonadi.
176  */
177  void itemRemoved() override;
178 
179 private:
180  //@cond PRIVATE
181  class Private;
182  Private *const d;
183 
184  Q_PRIVATE_SLOT(d, void slotUrlClicked(const QUrl &))
185  Q_PRIVATE_SLOT(d, void slotParentCollectionFetched(KJob *))
186  //@endcond
187 };
188 }
189 
A viewer component for contacts in Akonadi.
Definition: contactviewer.h:61
The interface for all contact formatters.
This file is part of the KDE documentation.
Documentation copyright © 1996-2021 The KDE developers.
Generated on Wed Jun 23 2021 23:09:24 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.