Akonadi Calendar

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

KDE's Doxygen guidelines are available online.