Akonadi Calendar

incidencechanger.h
1 /*
2  SPDX-FileCopyrightText: 2004 Reinhold Kainhofer <[email protected]>
3  SPDX-FileCopyrightText: 2010-2012 Sérgio Martins <[email protected]>
4 
5  SPDX-License-Identifier: LGPL-2.0-or-later
6 */
7 #pragma once
8 
9 #include "akonadi-calendar_export.h"
10 
11 #include "itiphandler.h"
12 #include <collection.h>
13 #include <item.h>
14 
15 #include <KCalendarCore/Incidence>
16 
17 #include <QWidget>
18 
19 namespace Akonadi
20 {
21 class EntityTreeModel;
22 /**
23  * @short IncidenceChanger is the preferred way to easily create, modify and delete incidences.
24  *
25  * It hides the communication with akonadi from the library user.
26  *
27  * It provides the following features that ItemCreateJob, ItemModifyJob and
28  * ItemDeleteJob do not:
29  * - Sending groupware ( iTip ) messages to attendees and organizers.
30  * - Aware of recurrences, allowing to only change one occurrence.
31  * - Undo/Redo
32  * - Group operations which are executed in an atomic manner.
33  * - Collection ACLs
34  * - Error dialogs with calendaring lingo
35  *
36  * In the context of this API, "change", means "creation", "deletion" or incidence "modification".
37  *
38  * @code
39  * IncidenceChanger *changer = new IncidenceChanger( parent );
40  * connect( changer,
41  * SIGNAL(createFinished(int,Akonadi::Item,Akonadi::IncidenceChanger::ResultCode,QString)),
42  * SLOT(slotCreateFinished(int,Akonadi::Item,Akonadi::IncidenceChanger::ResultCode,QString)) );
43  *
44  * connect( changer,
45  * SIGNAL(deleteFinished(int,QVector<Akonadi::Item::Id>,Akonadi::IncidenceChanger::ResultCode,QString)),
46  * SLOT(slotDeleteFinished(int,QVector<Akonadi::Item::Id>,Akonadi::IncidenceChanger::ResultCode,QString)) );
47  *
48  * connect( changer,SIGNAL(modifyFinished(int,Akonadi::Item,Akonadi::IncidenceChanger::ResultCode,QString)),
49  * SLOT(slotModifyFinished(int,Akonadi::Item,Akonadi::IncidenceChanger::ResultCode,QString)) );
50  *
51  * changer->setDestinationPolicy( IncidenceChanger::DestinationPolicyAsk );
52  *
53  * KCalendarCore::Incidence::Ptr incidence = (...);
54  * int changeId = changer->createIncidence( incidence, Akonadi::Collection() );
55  *
56  *
57  * if ( changeId == -1 )
58  * {
59  * // Invalid parameters, incidence is null.
60  * }
61  *
62  * @endcode
63  *
64  * @author Sérgio Martins <[email protected]>
65  * @since 4.11
66  */
67 
68 class History;
69 
70 class AKONADI_CALENDAR_EXPORT IncidenceChanger : public QObject
71 {
72  Q_OBJECT
73 public:
74  /**
75  * This enum describes result codes which are returned by createFinished(),
76  * modifyfinished() and deleteFinished() signals.
77  */
78  enum ResultCode {
79  ResultCodeSuccess = 0,
80  ResultCodeJobError, ///< ItemCreateJob, ItemModifyJob or ItemDeleteJob weren't successful
81  ResultCodeAlreadyDeleted, ///< That incidence was already deleted, or currently being deleted.
82  ResultCodeInvalidDefaultCollection, ///< Default collection is invalid and DestinationPolicyNeverAsk was used
83  ResultCodeRolledback, ///< One change belonging to an atomic operation failed. All other changes were rolled back.
84  ResultCodePermissions, ///< The parent collection doesn't have ACLs for this operation
85  ResultCodeUserCanceled, ///< User canceled the operation
86  ResultCodeInvalidUserCollection, ///< User somehow chose an invalid collection in the collection dialog ( should not happen )
87  ResultCodeModificationDiscarded, ///< A new modification came in, the old one is discarded
88  ResultCodeDuplicateId ///< Duplicate Akonadi::Item::Ids must be unique in group operations
89  };
90 
91  /**
92  * This enum describes destination policies.
93  * Destination policies control how the createIncidence() method chooses the
94  * collection where the item will be created.
95  */
96  enum DestinationPolicy {
97  DestinationPolicyDefault, ///< The default collection is used, if it's invalid, the user is prompted. @see setDefaultCollection().
98  DestinationPolicyAsk, ///< User is always asked which collection to use.
99  DestinationPolicyNeverAsk ///< The default collection is used, if it's invalid, an error is returned, and the incidence isn't added.
100  };
101 
102  /**
103  * Enum for controlling "Do you want to e-mail attendees" type of dialogs.
104  * This is only honoured if groupware communication is active.
105  *
106  * @see groupwareCommunication()
107  * @since 4.12
108  */
109  enum InvitationPolicy {
110  InvitationPolicySend = 0, ///< Invitation e-mails are sent without asking the user if he wants to.
111  InvitationPolicyAsk, ///< The user is asked if an e-mail should be sent. This is the default.
112  InvitationPolicyDontSend ///< E-mails aren't sent
113  };
114 
115  /**
116  * This enum describes change types.
117  */
118  enum ChangeType {
119  ChangeTypeCreate, ///> Represents an incidence creation.
120  ChangeTypeModify, ///> Represents an incidence modification.
121  ChangeTypeDelete ///> Represents an incidence deletion.
122  };
123 
124  /**
125  * Creates a new IncidenceChanger instance.
126  * creates a default ITIPHandlerComponentFactory object.
127  * @param parent parent QObject
128  */
129  explicit IncidenceChanger(QObject *parent = nullptr);
130 
131  /**
132  * Creates a new IncidenceChanger instance.
133  * @param factory factory for creating dialogs and the mail transport job. To create a default
134  * factory set factory == 0
135  * @param parent parent QObject
136  * @since 4.15
137  */
138  explicit IncidenceChanger(ITIPHandlerComponentFactory *factory, QObject *parent);
139 
140  /**
141  * Destroys this IncidenceChanger instance.
142  */
143  ~IncidenceChanger();
144 
145  /**
146  * Creates a new incidence.
147  *
148  * @param incidence Incidence to create, must be valid.
149  * @param collection Collection where the incidence will be created. If invalid, one according
150  * to the DestinationPolicy will be used. You can know which collection was
151  * used by calling lastCollectionUsed();
152  * @param parent widget parent to be used in dialogs.
153  *
154  * @return Returns an integer which identifies this change. This identifier is useful
155  * to correlate this operation with the IncidenceChanger::createFinished() signal.
156  *
157  * Returns -1 if @p incidence is invalid. The createFinished() signal
158  * won't be emitted in this case.
159  */
160  int createIncidence(const KCalendarCore::Incidence::Ptr &incidence, const Akonadi::Collection &collection = Akonadi::Collection(), QWidget *parent = nullptr);
161 
162  /**
163  * Creates a new incidence.
164  *
165  * @param item Item containing the incidence to create and metadata, such as tags.
166  * @param collection Collection where the incidence will be created. If invalid, one according
167  * to the DestinationPolicy will be used. You can know which collection was
168  * used by calling lastCollectionUsed();
169  * @param parent widget parent to be used in dialogs.
170  *
171  * @return Returns an integer which identifies this change. This identifier is useful
172  * to correlate this operation with the IncidenceChanger::createFinished() signal.
173  *
174  * Returns -1 if @p item is invalid. The createFinished() signal
175  * won't be emitted in this case.
176  */
177  int createFromItem(const Akonadi::Item &item, const Akonadi::Collection &collection = Akonadi::Collection(), QWidget *parent = nullptr);
178 
179  /**
180  * Deletes an incidence. If it's recurring, all occurrences are deleted.
181  *
182  * @param item Item to delete. Item must be valid.
183  * @param parent Parent to be used in dialogs.
184  *
185  * @return Returns an integer which identifies this deletion. This identifier is useful
186  * to correlate this deletion with the IncidenceChanger::deleteFinished() signal.
187  *
188  * Returns -1 if item is invalid. The deleteFinished() signal won't be emitted in this
189  * case.
190  */
191  int deleteIncidence(const Akonadi::Item &item, QWidget *parent = nullptr);
192 
193  /**
194  * Deletes a list of Items.
195  *
196  * @param items List of items do delete. They must be valid.
197  * @param parent Parent to be used in dialogs.
198  * @return Returns an integer which identifies this deletion. This identifier is useful
199  * to correlate this operation with the IncidenceChanger::deleteFinished() signal.
200  *
201  * Returns -1 if any item is invalid or if @p items is empty. The deleteFinished() signal
202  * won't be emitted in this case.
203  */
204  int deleteIncidences(const Akonadi::Item::List &items, QWidget *parent = nullptr);
205 
206  /**
207  * Modifies an incidence.
208  *
209  * @param item A valid item, with the new payload.
210  * @param originalPayload The payload before the modification. If invalid it won't be recorded
211  * to the undo stack and groupware functionality won't be used for this
212  * deletion.
213  * @param parent Parent to be used in dialogs.
214  *
215  * @return Returns an integer which identifies this modification. This identifier is useful
216  * to correlate this operation with the IncidenceChanger::modifyFinished() signal.
217  *
218  * Returns -1 if the item doesn't have a valid payload. The modifyFinished() signal
219  * won't be emitted in this case.
220  */
221  int modifyIncidence(const Akonadi::Item &item,
223  QWidget *parent = nullptr);
224 
225  /**
226  * Some incidence operations require more than one change. Like dissociating
227  * occurrences, which needs an incidence add and an incidence change.
228  *
229  * If you want to prevent that the same dialogs are presented multiple times
230  * use this function to start a batch operation.
231  *
232  * If one change belonging to a batch operation fails, all other changes
233  * are rolled back.
234  *
235  * @param operationDescription Describes what the atomic operation does.
236  * This will be what incidenceChanger->history()->descriptionForNextUndo()
237  * if you have history enabled.
238  *
239  * @see endAtomicOperation()
240  */
241  void startAtomicOperation(const QString &operationDescription = QString());
242 
243  /**
244  * Tells IncidenceChanger you finished doing changes that belong to a
245  * batch operation.
246  *
247  * @see startAtomicOperation()
248  */
249  void endAtomicOperation();
250 
251  /**
252  * Sets the base ETM tree model
253  * Used by the editor dialog's collection combobox, for instance.
254  */
255  void setEntityTreeModel(Akonadi::EntityTreeModel *model);
256 
257  /**
258  * Returns the base ETM tree model
259  */
260  Akonadi::EntityTreeModel *entityTreeModel() const;
261 
262  /**
263  * Sets the default collection.
264  * @param collection The collection to be used in createIncidence() if the
265  * proper destination policy is set.
266  * @see createIncidence()
267  * @see destinationPolicy()
268  * @see defaultCollection()
269  */
270  void setDefaultCollection(const Akonadi::Collection &collection);
271 
272  /**
273  * Returns the defaultCollection.
274  * If none is set, an invalid Collection is returned.
275  * @see setDefaultCollection()
276  * @see DestinationPolicy
277  */
278  Q_REQUIRED_RESULT Akonadi::Collection defaultCollection() const;
279 
280  /**
281  * Sets the destination policy to use. The destination policy determines the
282  * collection to use in createIncidence()
283  *
284  * @see createIncidence()
285  * @see destinationPolicy()
286  */
287  void setDestinationPolicy(DestinationPolicy destinationPolicy);
288 
289  /**
290  * Returns the current destination policy.
291  * If none is set, DestinationPolicyDefault is returned.
292  * @see setDestinationPolicy()
293  * @see DestinationPolicy
294  */
295  Q_REQUIRED_RESULT DestinationPolicy destinationPolicy() const;
296 
297  /**
298  * Sets if IncidenceChanger should show error dialogs.
299  */
300  void setShowDialogsOnError(bool enable);
301 
302  /**
303  * Returns true if error dialogs are shown by IncidenceChanger.
304  * The default is true.
305  *
306  * @see setShowDialogsOnError()
307  */
308  Q_REQUIRED_RESULT bool showDialogsOnError() const;
309 
310  /**
311  * Sets if IncidenceChanger should honour collection's ACLs by disallowing changes if
312  * necessary.
313  */
314  void setRespectsCollectionRights(bool respect);
315 
316  /**
317  * Returns true if IncidenceChanger honors collection's ACLs by disallowing
318  * changes if necessary.
319  *
320  * The default is true.
321  * @see setRespectsCollectionRights()
322  * @see ResultCode::ResultCodePermissions
323  */
324  Q_REQUIRED_RESULT bool respectsCollectionRights() const;
325 
326  /**
327  * Enable or disable history.
328  * With history enabled all changes are recored into the undo/redo stack.
329  *
330  * @see history()
331  * @see historyEnabled()
332  */
333  void setHistoryEnabled(bool enable);
334 
335  /**
336  * Returns true if changes are added into the undo stack.
337  * Default is true.
338  *
339  * @see history()
340  * @see historyEnabled()
341  */
342  Q_REQUIRED_RESULT bool historyEnabled() const;
343 
344  /**
345  * Returns a pointer to the history object.
346  * It's always valid.
347  * Ownership remains with IncidenceChanger.
348  */
349  History *history() const;
350 
351  /**
352  * For performance reasons, IncidenceChanger internaly caches the ids of the last deleted items,
353  * to avoid creating useless delete jobs.
354  *
355  * This function exposes that functionality so it can be used in other scenarios.
356  * One popular scenario is when you're using an ETM and the user is deleting items very fast,
357  * ETM doesn't know about the deletions immediately, so it can happen that some items are
358  * deleted more than once, resulting in an error.
359  *
360  * @return true if the item was deleted recently, false otherwise.
361  */
362  Q_REQUIRED_RESULT bool deletedRecently(Akonadi::Item::Id) const;
363 
364  /**
365  * Enables or disabled groupware communication.
366  * With groupware communication enabled, invitations and update e-mails will be sent to each
367  * attendee.
368  */
369  void setGroupwareCommunication(bool enabled);
370 
371  /**
372  * Returns if we're using groupware communication.
373  * Default is false.
374  * @see setGroupwareCommuniation()
375  */
376  Q_REQUIRED_RESULT bool groupwareCommunication() const;
377 
378  /**
379  * Makes modifyIncidence() adjust recurrence parameters when modifying DTSTART.
380  */
381  void setAutoAdjustRecurrence(bool enable);
382 
383  /**
384  * True if recurrence parameters are adjusted when modifying DTSTART.
385  * Default is true.
386  */
387  Q_REQUIRED_RESULT bool autoAdjustRecurrence() const;
388 
389  /**
390  * Sets the invitation policy.
391  *
392  * @since 4.12
393  */
394  void setInvitationPolicy(InvitationPolicy policy);
395 
396  /**
397  * Returns the invitation policy.
398  * The default is InvitationPolicyAsk.
399  *
400  * @since 4.12
401  */
402  Q_REQUIRED_RESULT InvitationPolicy invitationPolicy() const;
403 
404  /**
405  * Returns the collection that the last createIncidence() used.
406  * Will be invalid if no incidences were created yet.
407  *
408  * @see createIncidence().
409  */
410  Q_REQUIRED_RESULT Akonadi::Collection lastCollectionUsed() const;
411 
412 Q_SIGNALS:
413  /**
414  * Emitted when IncidenceChanger creates an Incidence in akonadi.
415  *
416  * @param changeId the unique identifier of this change, returned by createIncidence().
417  * @param item the created item, might be invalid if the @p resultCode is not ResultCodeSuccess
418  * @param resultCode success/error code
419  * @param errorString if @p resultCode is not ResultCodeSuccess, contains an i18n'ed error
420  * message. If you enabled error dialogs, this string was already presented to the user.
421  */
422  void createFinished(int changeId, const Akonadi::Item &item, Akonadi::IncidenceChanger::ResultCode resultCode, const QString &errorString);
423  /**
424  * Emitted when IncidenceChanger modifies an Incidence in akonadi.
425  *
426  * @param changeId the unique identifier of this change, returned by modifyIncidence().
427  * @param item the modified item, might be invalid if the @p resultCode is not ResultCodeSuccess
428  * @param resultCode success/error code
429  * @param errorString if @p resultCode is not ResultCodeSuccess, contains an i18n'ed error
430  * message. If you enabled error dialogs, this string was already presented to the user.
431  */
432  void modifyFinished(int changeId, const Akonadi::Item &item, Akonadi::IncidenceChanger::ResultCode resultCode, const QString &errorString);
433  /**
434  * Emitted when IncidenceChanger deletes an Incidence in akonadi.
435  *
436  * @param changeId the unique identifier of this change, returned by deletedIncidence().
437  * @param itemIdList list of deleted item ids, might be emptu if the @p resultCode is not
438  * ResultCodeSuccess
439  * @param resultCode success/error code
440  * @param errorString if @p resultCode is not ResultCodeSuccess, contains an i18n'ed error
441  * message. If you enabled error dialogs, this string was already presented to the user.
442  */
443  void
444  deleteFinished(int changeId, const QVector<Akonadi::Item::Id> &itemIdList, Akonadi::IncidenceChanger::ResultCode resultCode, const QString &errorString);
445 
446 private:
447  //@cond PRIVATE
448  friend class History;
449  friend class AtomicOperation;
450  // used internally by the History class
451  explicit IncidenceChanger(bool enableHistory, QObject *parent = nullptr);
452  class Private;
453  Private *const d;
454  //@endcond
455 };
456 }
457 
458 Q_DECLARE_METATYPE(Akonadi::IncidenceChanger::DestinationPolicy)
459 Q_DECLARE_METATYPE(Akonadi::IncidenceChanger::ResultCode)
460 Q_DECLARE_METATYPE(Akonadi::IncidenceChanger::ChangeType)
461 
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.