Akonadi Contacts

contacteditor.h
1/*
2 This file is part of Akonadi Contact.
3
4 SPDX-FileCopyrightText: 2009 Tobias Koenig <tokoe@kde.org>
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
17namespace KContacts
18{
19class Addressee;
20}
21namespace Akonadi
22{
23class Collection;
24class Item;
25class AbstractContactEditorWidget;
26class 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 <tokoe@kde.org>
67 * @since 4.4
68 */
69class AKONADI_CONTACT_WIDGETS_EXPORT AkonadiContactEditor : public QWidget
70{
71 Q_OBJECT
72
73public:
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
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 */
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 [[nodiscard]] KContacts::Addressee contact();
138 [[nodiscard]] bool hasNoSavedData() const;
139public 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
152Q_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
172private:
173 //@cond PRIVATE
174 std::unique_ptr<AkonadiContactEditorPrivate> const d;
175 //@endcond
176};
177}
An widget to edit contacts in Akonadi.
void contactStored(const Akonadi::Item &contact)
This signal is emitted when the contact has been saved back to the storage.
~AkonadiContactEditor() override
Destroys the contact editor.
void error(const QString &errorMsg)
This signal is emitted when an error occurred during the save.
Mode
Describes the mode of the editor.
@ CreateMode
Creates a new contact.
A widget for editing the display name of a contact.
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Sat Dec 21 2024 17:05:46 by doxygen 1.12.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.