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

KDE's Doxygen guidelines are available online.