Akonadi Contacts

contacteditor.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 <QWidget>
14 
15 #include <memory>
16 
17 namespace KContacts
18 {
19 class Addressee;
20 }
21 namespace ContactEditor
22 {
23 class AbstractContactEditorWidget;
24 }
25 namespace Akonadi
26 {
27 class Collection;
28 class Item;
29 class AkonadiContactEditorPrivate;
30 
31 /**
32  * @short An widget to edit contacts in Akonadi.
33  *
34  * This widget provides a way to create a new contact or edit
35  * an existing contact in Akonadi.
36  *
37  * Example for creating a new contact:
38  *
39  * @code
40  *
41  * using namespace Akonadi;
42  *
43  * ContactEditor *editor = new ContactEditor( Akonadi::ContactEditor::CreateMode, this );
44  *
45  * ...
46  *
47  * if ( !editor->saveContactInAddressBook() ) {
48  * qCDebug(AKONADICONTACT_LOG) << "Unable to save new contact to storage";
49  * return;
50  * }
51  *
52  * @endcode
53  *
54  * Example for editing an existing contact:
55  *
56  * @code
57  *
58  * const Akonadi::Item contact = ...;
59  *
60  * ContactEditor *editor = new ContactEditor( Akonadi::ContactEditor::EditMode, this );
61  * editor->loadContact( contact );
62  *
63  * ...
64  *
65  * editor->saveContactInAddressBook();
66  *
67  * @endcode
68  *
69  * @author Tobias Koenig <[email protected]>
70  * @since 4.4
71  */
72 class AKONADI_CONTACT_EXPORT AkonadiContactEditor : public QWidget
73 {
74  Q_OBJECT
75 
76 public:
77  /**
78  * Describes the mode of the editor.
79  */
80  enum Mode {
81  CreateMode, ///< Creates a new contact
82  EditMode ///< Edits an existing contact
83  };
84 
85  enum DisplayMode {
86  FullMode, ///< Show all pages
87  VCardMode ///< Show just pages with elements stored in vcard.
88  };
89 
90  /**
91  * Creates a new contact editor with the standard editor widget.
92  *
93  * @param mode The mode of the editor.
94  * @param parent The parent widget of the editor.
95  */
96  explicit AkonadiContactEditor(Mode mode, QWidget *parent = nullptr);
97 
98  /**
99  * Creates a new contact editor with a custom editor widget.
100  *
101  * @param mode The mode of the editor.
102  * @param editorWidget The contact editor widget that shall be used for editing.
103  * @param parent The parent widget of the editor.
104  */
105  AkonadiContactEditor(Mode mode, ContactEditor::AbstractContactEditorWidget *editorWidget, QWidget *parent = nullptr);
106 
107  /**
108  * Creates a new contact editor dialog with a custom editor widget.
109  *
110  * @param mode The mode of the dialog.
111  * @param displayMode mode for displaying the editor
112  * @param parent The parent widget of the dialog.
113  * @since 4.10
114  */
115  AkonadiContactEditor(Mode mode, DisplayMode displayMode, QWidget *parent = nullptr);
116 
117  /**
118  * Destroys the contact editor.
119  */
120  ~AkonadiContactEditor() override;
121 
122  /**
123  * Sets a @p contact that is used as template in create mode.
124  * The fields of the editor will be prefilled with the content of the contact.
125  * @param contact the contact to use as template content
126  */
127  void setContactTemplate(const KContacts::Addressee &contact);
128 
129  /**
130  * Sets the @p addressbook which shall be used to store new
131  * contacts.
132  */
133  void setDefaultAddressBook(const Akonadi::Collection &addressbook);
134 
135  /**
136  * @since 4.10
137  * @brief ContactEditor::contact
138  * @return
139  */
140  Q_REQUIRED_RESULT KContacts::Addressee contact();
141  Q_REQUIRED_RESULT bool hasNoSavedData() const;
142 public Q_SLOTS:
143  /**
144  * Loads the @p contact into the editor.
145  */
146  void loadContact(const Akonadi::Item &contact);
147 
148  /**
149  * Save the contact from the editor back to the storage. And return error.
150  * Need to connect to finished() signal, to keep time to Q_EMIT signal.
151  * @since 4.11
152  */
153  void saveContactInAddressBook();
154 
155 Q_SIGNALS:
156  /**
157  * This signal is emitted when the @p contact has been saved back
158  * to the storage.
159  */
160  void contactStored(const Akonadi::Item &contact);
161 
162  /**
163  * This signal is emitted when an error occurred during the save.
164  * @param errorMsg The error message.
165  * @since 4.11
166  */
167  void error(const QString &errorMsg);
168 
169  /**
170  * @brief finished
171  * @since 4.11
172  */
173  void finished();
174 
175 private:
176  //@cond PRIVATE
177  std::unique_ptr<AkonadiContactEditorPrivate> const d;
178  //@endcond
179 };
180 }
@ CreateMode
Creates a new contact.
Definition: contacteditor.h:81
Mode
Describes the mode of the editor.
Definition: contacteditor.h:80
An widget to edit contacts in Akonadi.
Definition: contacteditor.h:72
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.