Akonadi Calendar

history.h
1 /*
2  SPDX-FileCopyrightText: 2010-2012 Sérgio Martins <[email protected]mail.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 
18 class HistoryTest;
19 
20 namespace Akonadi
21 {
22 class IncidenceChanger;
23 class 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 <[email protected]>
44  @since 4.11
45 */
46 
47 class AKONADI_CALENDAR_EXPORT History : public QObject
48 {
49  Q_OBJECT
50 public:
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  */
57  enum ResultCode {
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  Q_REQUIRED_RESULT 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  Q_REQUIRED_RESULT bool undoAvailable() const;
145 
146  /**
147  * Returns true if there are changes that can be redone.
148  */
149  Q_REQUIRED_RESULT 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  Q_REQUIRED_RESULT 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  Q_REQUIRED_RESULT QString nextRedoDescription() const;
170 
171 public 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 
210 Q_SIGNALS:
211  /**
212  * This signal is emitted when an undo operation finishes.
213  * @param resultCode History::ResultCodeSuccess on success.
214  * @see lastErrorString()
215  */
216  void undone(Akonadi::History::ResultCode resultCode);
217 
218  /**
219  * This signal is emitted when an redo operation finishes.
220  * @param resultCode History::ResultCodeSuccess on success.
221  * @see lastErrorString()
222  */
223  void redone(Akonadi::History::ResultCode resultCode);
224 
225  /**
226  * The redo/undo stacks have changed.
227  */
228  void changed();
229 
230 private:
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 
242 private:
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:47
ResultCode
This enum describes the possible result codes (success/error values) for an undo or redo operation.
Definition: history.h:57
FreeBusyManager::Singleton.
This file is part of the KDE documentation.
Documentation copyright © 1996-2022 The KDE developers.
Generated on Wed Sep 28 2022 03:52:06 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.