Akonadi Calendar

history.h
1/*
2 SPDX-FileCopyrightText: 2010-2012 Sérgio Martins <iamsergio@gmail.com>
3
4 SPDX-License-Identifier: LGPL-2.0-or-later
5*/
6
7#pragma once
8
9#include "akonadi-calendar_export.h"
10#include "incidencechanger.h"
11
12#include <Akonadi/Item>
13#include <KCalendarCore/Incidence>
14#include <QWidget>
15
16#include <memory>
17
18class HistoryTest;
19
20namespace Akonadi
21{
22class IncidenceChanger;
23class HistoryPrivate;
24
25/**
26 @short History class for implementing undo/redo of calendar operations
27
28 Whenever you use IncidenceChanger to create, delete or modify incidences,
29 this class is used to record those changes onto a stack, so they can be
30 undone or redone.
31
32 If needed, groupware invitations will be sent to attendees and organizers when
33 undoing or redoing changes.
34
35 This class can't be instantiated directly, use it through IncidenceChanger:
36
37 @code
38 Akonadi::IncidenceChanger *myIncidenceChanger = new Akonadi::IncidenceChanger();
39 connect(undoAction, &QAction::triggered, myIncidenceChanger->history(), &Akonadi::IncidenceChanger::undo);
40 connect(redoAction, &QAction::triggered, myIncidenceChanger->history(), &Akonadi::IncidenceChanger::redo);
41 @endcode
42
43 @author Sérgio Martins <iamsergio@gmail.com>
44 @since 4.11
45*/
46
47class AKONADI_CALENDAR_EXPORT History : public QObject
48{
49 Q_OBJECT
50public:
51 /**
52 * This enum describes the possible result codes (success/error values) for an
53 * undo or redo operation.
54 * @see undone()
55 * @see redone()
56 */
58 ResultCodeSuccess = 0, ///< Success
59 ResultCodeError ///< An error occurred. Call lastErrorString() for the error message. This isn't very verbose because IncidenceChanger hasn't been
60 ///< refactored yet.
61 };
62
63 /**
64 * Destroys the History instance.
65 */
66 ~History() override;
67
68 /**
69 * Pushes an incidence creation onto the undo stack. The creation can be
70 * undone calling undo().
71 *
72 * @param item the item that was created. Must be valid and have a Incidence::Ptr payload
73 * @param description text that can be used in the undo/redo menu item to describe the operation
74 * If empty, a default one will be provided.
75 * @param atomicOperationId if not 0, specifies which group of changes this change belongs to.
76 * When a change is undone/redone, all other changes which are in the same group are also
77 * undone/redone
78 */
79 void recordCreation(const Akonadi::Item &item, const QString &description, const uint atomicOperationId = 0);
80
81 /**
82 * Pushes an incidence modification onto the undo stack. The modification can be undone calling
83 * undo().
84 *
85 * @param oldItem item containing the payload before the change. Must be valid
86 * and contain an Incidence::Ptr payload.
87 * @param newItem item containing the new payload. Must be valid and contain
88 * an Incidence::Ptr payload.
89 * @param description text that can be used in the undo/redo menu item to describe the operation
90 * If empty, a default one will be provided.
91 * @param atomicOperationId if not 0, specifies which group of changes this change belongs to.
92 * When a change is undone/redone, all other changes which are in the same group are also
93 * undone/redone
94 */
95 void recordModification(const Akonadi::Item &oldItem, const Akonadi::Item &newItem, const QString &description, const uint atomicOperationId = 0);
96
97 /**
98 * Pushes an incidence deletion onto the undo stack. The deletion can be
99 * undone calling undo().
100 *
101 * @param item The item to delete. Must be valid, doesn't need to contain a
102 * payload.
103 * @param description text that can be used in the undo/redo menu item to describe the operation
104 * If empty, a default one will be provided.
105 * @param atomicOperationId if not 0, specifies which group of changes this change belongs to.
106 * When a change is undone/redone, all other changes which are in the same group are also
107 * undone/redone
108 */
109 void recordDeletion(const Akonadi::Item &item, const QString &description, const uint atomicOperationId = 0);
110
111 /**
112 * Pushes a list of incidence deletions onto the undo stack. The deletions can
113 * be undone calling undo() once.
114 *
115 * @param items The list of items to delete. All items must be valid.
116 * @param description text that can be used in the undo/redo menu item to describe the operation
117 * If empty, a default one will be provided.
118 * @param atomicOperationId If != 0, specifies which group of changes thischange belongs to.
119 * Will be useful for atomic undoing/redoing, not implemented yet.
120 */
121 void recordDeletions(const Akonadi::Item::List &items, const QString &description, const uint atomicOperationId = 0);
122
123 /**
124 * Returns the last error message.
125 *
126 * Call this immediately after catching the undone()/redone() signal
127 * with an ResultCode != ResultCodeSuccess.
128 *
129 * The message is translated.
130 */
131 [[nodiscard]] QString lastErrorString() const;
132
133 /**
134 * Reverts every change in the undo stack.
135 *
136 * @param parent will be passed to dialogs created by IncidenceChanger,
137 * for example those asking if you want to send invitations.
138 */
139 void undoAll(QWidget *parent = nullptr);
140
141 /**
142 * Returns true if there are changes that can be undone.
143 */
144 [[nodiscard]] bool undoAvailable() const;
145
146 /**
147 * Returns true if there are changes that can be redone.
148 */
149 [[nodiscard]] bool redoAvailable() const;
150
151 /**
152 * Returns the description of the next undo.
153 *
154 * This is the description that was passed when calling recordCreation(),
155 * recordDeletion() or recordModification().
156 *
157 * @see nextRedoDescription()
158 */
159 [[nodiscard]] QString nextUndoDescription() const;
160
161 /**
162 * Returns the description of the next redo.
163 *
164 * This is the description that was passed when calling recordCreation(),
165 * recordDeletion() or recordModification().
166 *
167 * @see nextUndoDescription()
168 */
169 [[nodiscard]] QString nextRedoDescription() const;
170
171public Q_SLOTS:
172 /**
173 * Clears the undo and redo stacks.
174 * Won't do anything if there's a undo/redo job currently running.
175 *
176 * @return true if the stacks were cleared, false if there was a job running
177 */
178 bool clear();
179
180 /**
181 * Reverts the change that's on top of the undo stack.
182 * Can't be called if there's an undo/redo operation running, asserts.
183 * Can be called if the stack is empty, in this case, nothing happens.
184 * This function is async, catch signal undone() to know when the operation
185 * finishes.
186 *
187 * @param parent will be passed to dialogs created by IncidenceChanger,
188 * for example those asking if you want to send invitations.
189 *
190 * @see redo()
191 * @see undone()
192 */
193 void undo(QWidget *parent = nullptr);
194
195 /**
196 * Reverts the change that's on top of the redo stack.
197 * Can't be called if there's an undo/redo operation running, asserts.
198 * Can be called if the stack is empty, in this case, nothing happens.
199 * This function is async, catch signal redone() to know when the operation
200 * finishes.
201 *
202 * @param parent will be passed to dialogs created by IncidenceChanger,
203 * for example those asking if you want to send invitations.
204 *
205 * @see undo()
206 * @see redone()
207 */
208 void redo(QWidget *parent = nullptr);
209
210Q_SIGNALS:
211 /**
212 * This signal is emitted when an undo operation finishes.
213 * @param resultCode History::ResultCodeSuccess on success.
214 * @see lastErrorString()
215 */
217
218 /**
219 * This signal is emitted when an redo operation finishes.
220 * @param resultCode History::ResultCodeSuccess on success.
221 * @see lastErrorString()
222 */
224
225 /**
226 * The redo/undo stacks have changed.
227 */
228 void changed();
229
230private:
231 friend class ::HistoryTest;
232 friend class IncidenceChanger;
233 friend class IncidenceChangerPrivate;
234 friend class Entry;
235
236 // Only IncidenceChanger can create History classes
237 explicit History(QObject *parent = nullptr);
238
239 // Used by unit-tests
240 Akonadi::IncidenceChanger *incidenceChanger() const;
241
242private:
243 //@cond PRIVATE
244 std::unique_ptr<HistoryPrivate> const d;
245 //@endcond
246};
247}
History class for implementing undo/redo of calendar operations.
Definition history.h:48
void changed()
The redo/undo stacks have changed.
void undone(Akonadi::History::ResultCode resultCode)
This signal is emitted when an undo operation finishes.
~History() override
Destroys the History instance.
ResultCode
This enum describes the possible result codes (success/error values) for an undo or redo operation.
Definition history.h:57
void redone(Akonadi::History::ResultCode resultCode)
This signal is emitted when an redo operation finishes.
FreeBusyManager::Singleton.
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Fri Jul 19 2024 11:52:11 by doxygen 1.11.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.