Incidenceeditor

editoritemmanager.h
1/*
2 SPDX-FileCopyrightText: 2010 Bertjan Broeksema <broeksema@kde.org>
3 SPDX-FileCopyrightText: 2010 Klaralvdalens Datakonsult AB, a KDAB Group company <info@kdab.net>
4
5 SPDX-License-Identifier: LGPL-2.0-or-later
6*/
7
8#pragma once
9
10#include <Akonadi/Collection>
11#include <Akonadi/IncidenceChanger>
12#include <QObject>
13
14#include <memory>
15
16namespace Akonadi
17{
18class Item;
19}
20
21class KJob;
22
23namespace IncidenceEditorNG
24{
25class ItemEditorUi;
26class ItemEditorPrivate;
27
28/**
29 * Helper class for creating dialogs that let the user create and edit the payload
30 * of Akonadi items (e.g. events, contacts, etc). This class supports editing of
31 * one item at a time and handles all Akonadi specific logic like Item creation,
32 * Item modifying and monitoring of changes to the item during editing.
33 */
34// template <typename PayloadT>
36{
38public:
39 enum ItipPrivacy {
40 ItipPrivacyPlain = 0,
41 ItipPrivacySign = 1,
42 ItipPrivacyEncrypt = 2
43 };
44 Q_DECLARE_FLAGS(ItipPrivacyFlags, ItipPrivacy)
45
46 /**
47 * Creates an ItemEditor for a new Item.
48 * Receives an option IncidenceChanger, so you can share the undo/redo stack with your
49 * application.
50 */
51 explicit EditorItemManager(ItemEditorUi *ui, Akonadi::IncidenceChanger *changer = nullptr);
52
53 /**
54 * Destructs the ItemEditor. Unsaved changes will get lost at this point.
55 */
57
58 enum ItemState {
59 AfterSave, /**< Returns the last saved item */
60 BeforeSave /**< Returns an item with the original payload before the last save call */
61 };
62
63 /**
64 * Returns the last saved item with payload or an invalid item when save is
65 * not called yet.
66 */
67 [[nodiscard]] Akonadi::Item item(ItemState state = AfterSave) const;
68
69 /**
70 * Loads the @param item into the editor. The item passed must be
71 * a valid item.
72 */
73 void load(const Akonadi::Item &item);
74
75 /**
76 * Saves the new or modified item. This method does nothing when the
77 * ui is not dirty.
78 */
79 void save(ItipPrivacyFlags itipPrivacy = ItipPrivacyPlain);
80
82 Create, /**< A new item was created */
83 Modify, /**< An existing item was modified */
84 None, /**< Nothing happened. */
85 Move, /**< An existing item was moved to another collection */
86 MoveAndModify /**< An existing item was moved to another collection and modified */
87 };
88
89 void setIsCounterProposal(bool isCounterProposal);
90
92 void itemSaveFinished(IncidenceEditorNG::EditorItemManager::SaveAction action);
93
94 void itemSaveFailed(IncidenceEditorNG::EditorItemManager::SaveAction action, const QString &message);
95
96 void revertFinished();
97 void revertFailed(const QString &message);
98
99private:
100 std::unique_ptr<ItemEditorPrivate> const d_ptr;
101 Q_DECLARE_PRIVATE(ItemEditor)
102 Q_DISABLE_COPY(EditorItemManager)
103};
104
105class ItemEditorUi
106{
107public:
108 enum RejectReason {
109 ItemFetchFailed, ///> Either the fetchjob failed or no items where returned
110 ItemHasInvalidPayload, ///> The fetched item has an invalid payload
111 ItemMoveFailed ///> Item move failed
112 };
113
114 virtual ~ItemEditorUi();
115
116 /**
117 * Returns whether or not the identifier set contains payload identifiers that
118 * are displayed/editable in the Gui.
119 */
120 virtual bool containsPayloadIdentifiers(const QSet<QByteArray> &partIdentifiers) const = 0;
121
122 /**
123 * Returns whether or not @param item has a payload type that is supported by
124 * the gui.
125 */
126 virtual bool hasSupportedPayload(const Akonadi::Item &item) const = 0;
127
128 /**
129 * Returns whether or not the values in the ui differ from the original (i.e.
130 * either an empty or a loaded item). This method <em>only</em> involves
131 * payload fields. I.e. if only the collection in which the item should be
132 * stored has changed, this method should return false.
133 */
134 virtual bool isDirty() const = 0;
135
136 /**
137 * Returns whether or not the values in the ui are valid. This method can also
138 * be used to update the ui if necessary. The default implementation returns
139 * true, so if the ui doesn't need validation there is no need to reimplement
140 * this method.
141 */
142 virtual bool isValid() const;
143
144 /**
145 * Fills the ui with the values of the payload of @param item. The item is
146 * guaranteed to have a payload.
147 */
148 virtual void load(const Akonadi::Item &item) = 0;
149
150 /**
151 * Stores the values of the ui into the payload of @param item and returns the
152 * item with an updated payload. The returned item must have a valid mimetype
153 * too.
154 */
155 virtual Akonadi::Item save(const Akonadi::Item &item) = 0;
156
157 /**
158 * Returns the currently selected collection in which the item will be stored.
159 */
160 virtual Akonadi::Collection selectedCollection() const = 0;
161
162 /**
163 * This function is called if for some reason the creation or editing of the
164 * item cannot be continued. The implementing class must abort editing at
165 * this point.
166 */
167 virtual void reject(RejectReason reason, const QString &errorMessage = QString()) = 0;
168};
169}
170
Helper class for creating dialogs that let the user create and edit the payload of Akonadi items (e....
~EditorItemManager() override
Destructs the ItemEditor.
void load(const Akonadi::Item &item)
Loads the.
void save(ItipPrivacyFlags itipPrivacy=ItipPrivacyPlain)
Saves the new or modified item.
EditorItemManager(ItemEditorUi *ui, Akonadi::IncidenceChanger *changer=nullptr)
Creates an ItemEditor for a new Item.
@ Modify
An existing item was modified.
@ MoveAndModify
An existing item was moved to another collection and modified.
@ Move
An existing item was moved to another collection.
Akonadi::Item item(ItemState state=AfterSave) const
Returns the last saved item with payload or an invalid item when save is not called yet.
@ AfterSave
Returns the last saved item.
@ BeforeSave
Returns an item with the original payload before the last save call.
Q_OBJECTQ_OBJECT
Q_SIGNALSQ_SIGNALS
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Sat Dec 21 2024 16:58:15 by doxygen 1.12.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.