Akonadi Calendar

etmcalendar.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 #include "calendarbase.h"
12 
13 #include <collection.h>
14 
15 class QAbstractItemModel;
17 
18 namespace Akonadi
19 {
20 class Monitor;
21 class ETMCalendarPrivate;
22 class EntityTreeModel;
23 
24 /**
25  * @short A KCalendarCore::Calendar that uses an EntityTreeModel to populate itself.
26  *
27  * All non-idempotent KCalendarCore::Calendar methods interact with Akonadi.
28  * If you need a need a non-persistent calendar use FetchJobCalendar.
29  *
30  * ETMCalendar allows to be populated with only a subset of your calendar items,
31  * by using a KCheckableProxyModel to specify which collections to be used
32  * and/or by setting a KCalendarCore::CalFilter.
33  *
34  * @see FetchJobCalendar
35  * @see CalendarBase
36  *
37  * @author Sérgio Martins <[email protected]>
38  * @since 4.11
39  */
40 class AKONADI_CALENDAR_EXPORT ETMCalendar : public CalendarBase
41 {
42  Q_OBJECT
43 public:
44  enum CollectionColumn { CollectionTitle = 0, CollectionColumnCount };
45 
47 
48  /**
49  * Constructs a new ETMCalendar. Loading begins immediately, asynchronously.
50  */
51  explicit ETMCalendar(QObject *parent = nullptr);
52 
53  /**
54  * Constructs a new ETMCalendar that will only load the specified mime types.
55  * Use this ctor to ignore journals or to-dos for example.
56  * If no mime types are specified, all mime types will be used.
57  */
58  explicit ETMCalendar(const QStringList &mimeTypes, QObject *parent = nullptr);
59 
60  /**
61  * Constructs a new ETMCalendar.
62  *
63  * This overload exists for optimization reasons, it allows to share an EntityTreeModel across
64  * several ETMCalendars to save memory.
65  *
66  * Usually when having many ETMCalendars, the only bit that's different is the collection
67  * selection. The memory hungry EntityTreeModel is the same, so should be shared.
68  *
69  * @param calendar an existing ETMCalendar who's EntityTreeModel is to be used.
70  *
71  * @since 4.13
72  */
73  explicit ETMCalendar(ETMCalendar *calendar, QObject *parent = nullptr);
74 
75  explicit ETMCalendar(Monitor *monitor, QObject *parent = nullptr);
76  /**
77  * Destroys this ETMCalendar.
78  */
79  ~ETMCalendar() override;
80 
81  /**
82  * Returns the collection having @p id.
83  * Use this instead of creating a new collection, the returned collection will have
84  * the correct right, name, display name, etc all set.
85  */
86  Q_REQUIRED_RESULT Akonadi::Collection collection(Akonadi::Collection::Id) const;
87 
88  /**
89  * Returns true if the collection owning incidence @p has righ @p right
90  */
91  Q_REQUIRED_RESULT bool hasRight(const Akonadi::Item &item, Akonadi::Collection::Right right) const;
92 
93  /**
94  * This is an overloaded function.
95  * @param uid the identifier for the incidence to check for rights
96  * @param right the access right to check for
97  * @see hasRight()
98  */
99  Q_REQUIRED_RESULT bool hasRight(const QString &uid, Akonadi::Collection::Right right) const;
100 
101  /**
102  * Returns the KCheckableProxyModel used to select from which collections should
103  * the calendar be populated from.
104  */
105  KCheckableProxyModel *checkableProxyModel() const;
106 
107  /**
108  * Convenience method to access the contents of this KCalendarCore::Calendar through
109  * a QAIM interface.
110  *
111  * Like through calendar interface, the model only items of selected collections.
112  * To select or unselect collections, see checkableProxyModel().
113  *
114  * @see checkableProxyModel()
115  * @see entityTreeModel()
116  */
117  QAbstractItemModel *model() const;
118 
119  /**
120  * Returns the underlying EntityTreeModel.
121  *
122  * For most uses, you'll want model() or the KCalendarCore::Calendar interface instead.
123  *
124  * It contains every item and collection with calendar mime type, doesn't have
125  * KCalendarCore filtering and doesn't honour any collection selection.
126  *
127  * This method is exposed for performance reasons only, so you can reuse it,
128  * since it's resource savy.
129  *
130  * @see model()
131  */
132  Akonadi::EntityTreeModel *entityTreeModel() const;
133 
134  /**
135  * Returns all alarms occurring in a specified time interval.
136  * @param from start date of interval
137  * @param to end data of interval
138  * @param excludeBlockedAlarms if true, alarms belonging to blocked collections aren't returned.
139  */
140  KCalendarCore::Alarm::List alarms(const QDateTime &from, const QDateTime &to, bool excludeBlockedAlarms = false) const override;
141 
142  /**
143  * Enable or disable collection filtering.
144  * If true, the calendar will only contain items of selected collections.
145  * @param enable enables collection filtering if set as @c true
146  * @see checkableProxyModel()
147  * @see collectionFilteringEnabled()
148  */
149  void setCollectionFilteringEnabled(bool enable);
150 
151  /**
152  * Returns whether collection filtering is enabled. Default is true.
153  * @see setCollectionFilteringEnabled()
154  */
155  Q_REQUIRED_RESULT bool collectionFilteringEnabled() const;
156 
157  /**
158  * Returns if the calendar already finished loading.
159  */
160  Q_REQUIRED_RESULT bool isLoaded() const override;
161 
162 Q_SIGNALS:
163  /**
164  * This signal is emitted if a collection has been changed (properties or attributes).
165  *
166  * @param collection The changed collection.
167  * @param attributeNames The names of the collection attributes that have been changed.
168  */
169  void collectionChanged(const Akonadi::Collection &collection, const QSet<QByteArray> &attributeNames);
170 
171  /**
172  * This signal is emitted when one or more collections are added to the ETM.
173  *
174  * @param collection non empty list of collections
175  */
176  void collectionsAdded(const Akonadi::Collection::List &collection);
177 
178  /**
179  * This signal is emitted when one or more collections are deleted from the ETM.
180  *
181  * @param collection non empty list of collections
182  */
183  void collectionsRemoved(const Akonadi::Collection::List &collection);
184 
185  /**
186  * Emitted whenever an Item is inserted, removed or modified.
187  */
188  void calendarChanged();
189 
190 private:
191  Q_DECLARE_PRIVATE(ETMCalendar)
192 };
193 }
194 
FreeBusyManager::Singleton.
The base class for all akonadi aware calendars.
Definition: calendarbase.h:35
A KCalendarCore::Calendar that uses an EntityTreeModel to populate itself.
Definition: etmcalendar.h:40
This file is part of the KDE documentation.
Documentation copyright © 1996-2021 The KDE developers.
Generated on Thu Jun 17 2021 23:11:39 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.