Akonadi Calendar

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

KDE's Doxygen guidelines are available online.