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

KDE's Doxygen guidelines are available online.