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

KDE's Doxygen guidelines are available online.