Akonadi Calendar

calendarbase.h
1 /*
2  SPDX-FileCopyrightText: 2011 Sérgio Martins <[email protected]>
3  SPDX-FileCopyrightText: 2012 Sérgio Martins <[email protected]>
4 
5  SPDX-License-Identifier: LGPL-2.0-or-later
6 */
7 
8 #pragma once
9 
10 #include "akonadi-calendar_export.h"
11 
12 #include <KCalendarCore/Incidence>
13 #include <KCalendarCore/MemoryCalendar>
14 #include <collection.h>
15 #include <item.h>
16 
17 namespace Akonadi
18 {
19 class CalendarBasePrivate;
20 class IncidenceChanger;
21 
22 /**
23  * @short The base class for all akonadi aware calendars.
24  *
25  * Because it inherits KCalendarCore::Calendar, it provides seamless integration
26  * with KCalendarCore and KCalUtils libraries eliminating any need for adapter
27  * ( akonadi<->KCalendarCore ) classes.
28  *
29  * @see ETMCalendar
30  * @see FetchJobCalendar
31  *
32  * @author Sérgio Martins <[email protected]>
33  * @since 4.11
34  */
35 class AKONADI_CALENDAR_EXPORT CalendarBase : public KCalendarCore::MemoryCalendar
36 {
37  Q_OBJECT
38 public:
40 
41  /**
42  * Constructs a CalendarBase object.
43  */
44  explicit CalendarBase(QObject *parent = nullptr);
45 
46  /**
47  * Destroys the calendar.
48  */
49  ~CalendarBase() override;
50 
51  /**
52  * Returns the Item containing the incidence with uid @p uid or an invalid Item
53  * if the incidence isn't found.
54  * @see Use item(Incidence::Ptr) instead where possible. This function doesn't take exceptions (recurrenceId) into account (and thus always returns the main
55  * event).
56  */
57  Q_REQUIRED_RESULT Akonadi::Item item(const QString &uid) const;
58 
59  /**
60  * Returns the Item containing @p incidence or an invalid Item if the incidence isn't found.
61  */
62  Q_REQUIRED_RESULT Akonadi::Item item(const KCalendarCore::Incidence::Ptr &incidence) const;
63 
64  /**
65  * Returns the Item with @p id or an invalid Item if not found.
66  */
67  Q_REQUIRED_RESULT Akonadi::Item item(Akonadi::Item::Id) const;
68 
69  /**
70  * Returns the list of items contained in this calendar that belong to the specified collection.
71  * @see incidences()
72  * @since 4.12
73  */
74  Q_REQUIRED_RESULT Akonadi::Item::List items(Akonadi::Collection::Id = -1) const;
75 
76  /**
77  * Returns the item list that corresponds to the @p incidenceList.
78  */
79  Q_REQUIRED_RESULT Akonadi::Item::List itemList(const KCalendarCore::Incidence::List &incidenceList) const;
80 
81  /**
82  * Returns the child incidences of the parent identified by @p parentUid.
83  * Only the direct childs are returned
84  * @param parentUid identifier of the parent incidence
85  *///TODO: unit-test
86  Q_REQUIRED_RESULT KCalendarCore::Incidence::List childIncidences(const QString &parentUid) const;
87 
88  /**
89  * Returns the child incidences of the parent identified by @p parentId.
90  * Only the direct childs are returned
91  * @param parentId identifier of the parent item
92  */
93  Q_REQUIRED_RESULT KCalendarCore::Incidence::List childIncidences(Item::Id parentId) const;
94 
95  /**
96  * Returns the child items of the parent identified by @p parentUid.
97  * Only the direct childs are returned
98  * @param parentUid identifier of the parent incidence
99  */
100  Q_REQUIRED_RESULT Akonadi::Item::List childItems(const QString &parentUid) const;
101 
102  /**
103  * Returns the child items of the parent identified by @p parentId.
104  * Only the direct childs are returned
105  * @param parentId identifier of the parent item
106  */
107  Q_REQUIRED_RESULT Akonadi::Item::List childItems(Item::Id parentId) const;
108 
109  /**
110  * Adds an Event to the calendar.
111  * It's added to akonadi in the background @see createFinished().
112  * @param event the event to be added
113  */
114  bool addEvent(const KCalendarCore::Event::Ptr &event) override;
115 
116  /**
117  * Deletes an Event from the calendar.
118  * It's removed from akonadi in the background @see deleteFinished().
119  * @param event the event to be deleted
120  */
121  bool deleteEvent(const KCalendarCore::Event::Ptr &event) override;
122 
123  /**
124  * Adds a Todo to the calendar.
125  * It's added to akonadi in the background @see createFinished().
126  * @param todo the todo to add
127  */
128  bool addTodo(const KCalendarCore::Todo::Ptr &todo) override;
129 
130  /**
131  * Deletes a Todo from the calendar.
132  * It's removed from akonadi in the background @see deleteFinished().
133  * @param todo the todo to delete
134  */
135  bool deleteTodo(const KCalendarCore::Todo::Ptr &todo) override;
136 
137  /**
138  * Adds a Journal to the calendar.
139  * It's added to akonadi in the background @see createFinished().
140  * @param journal the journal to add
141  */
142  bool addJournal(const KCalendarCore::Journal::Ptr &journal) override;
143 
144  /**
145  * Deletes a Journal from the calendar.
146  * It's removed from akonadi in the background @see deleteFinished().
147  * @param journal the journal to delete
148  */
149  bool deleteJournal(const KCalendarCore::Journal::Ptr &journal) override;
150 
151  /**
152  * Adds an incidence to the calendar.
153  * It's added to akonadi in the background @see createFinished().
154  * @param incidence the incidence to add
155  */
156  bool addIncidence(const KCalendarCore::Incidence::Ptr &incidence) override;
157 
158  /**
159  * Deletes an incidence from the calendar.
160  * It's removed from akonadi in the background @see deleteFinished().
161  * @param incidence the incidence to delete
162  */
163  bool deleteIncidence(const KCalendarCore::Incidence::Ptr &incidence) override;
164 
165  /**
166  Call this to tell the calendar that you're adding a batch of incidences.
167  So it doesn't, for example, ask the destination for each incidence.
168 
169  @see endBatchAdding()
170  */
171  void startBatchAdding() override;
172 
173  /**
174  * Tells the Calendar that you stoped adding a batch of incidences.
175  * @see startBatchAdding()
176  */
177  void endBatchAdding() override;
178 
179  /**
180  * Returns the IncidenceChanger used by this calendar to make changes in akonadi.
181  * Use this if you need the defaults used by CalendarBase.
182  */
183  Q_REQUIRED_RESULT Akonadi::IncidenceChanger *incidenceChanger() const;
184 
185  /**
186  * Modifies an incidence.
187  * The incidence with the same uid as @p newIncidence will be updated with the contents of
188  * @param newIncidence the incidence to modify
189  */
190  bool modifyIncidence(const KCalendarCore::Incidence::Ptr &newIncidence);
191 
192  /**
193  * Returns if the calendar already finished loading.
194  * Base class returns true.
195  */
196  virtual bool isLoaded() const;
197 
198 Q_SIGNALS:
199  /**
200  * This signal is emitted when an incidence is created in akonadi through
201  * add{Incidence,Event,Todo,Journal}
202  * @param success the success of the operation
203  * @param errorMessage if @p success is false, contains the error message
204  */
205  void createFinished(bool success, const QString &errorMessage);
206 
207  /**
208  * This signal is emitted when an incidence is deleted in akonadi through
209  * delete{Incidence,Event,Todo,Journal}
210  * @param success the success of the operation
211  * @param errorMessage if @p success is false, contains the error message
212  */
213  void deleteFinished(bool success, const QString &errorMessage);
214 
215  /**
216  * This signal is emitted when an incidence is modified in akonadi through
217  * modifyIncidence().
218  * @param success the success of the operation
219  * @param errorMessage if @p success is false, contains the error message
220  */
221  void modifyFinished(bool success, const QString &errorMessage);
222 
223 protected:
224  Q_DECLARE_PRIVATE(CalendarBase)
226  CalendarBase(CalendarBasePrivate *const d, QObject *parent);
227 
228  friend class Scheduler;
229 };
230 }
231 
KCALUTILS_EXPORT QString errorMessage(const KCalendarCore::Exception &exception)
FreeBusyManager::Singleton.
The base class for all akonadi aware calendars.
Definition: calendarbase.h:35
This file is part of the KDE documentation.
Documentation copyright © 1996-2021 The KDE developers.
Generated on Fri Jun 18 2021 23:11:35 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.