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 { 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 [[nodiscard]] Akonadi::Collection collection(Akonadi::Collection::Id) const;
87
88 /**
89 * Returns true if the collection owning incidence @p has righ @p right
90 */
91 [[nodiscard]] 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 [[nodiscard]] 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 [[nodiscard]] 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 [[nodiscard]] 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 savvy.
129 *
130 * @see model()
131 */
132 [[nodiscard]] 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 [[nodiscard]] 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 [[nodiscard]] bool collectionFilteringEnabled() const;
156
157Q_SIGNALS:
158 /**
159 * This signal is emitted if a collection has been changed (properties or attributes).
160 *
161 * @param collection The changed collection.
162 * @param attributeNames The names of the collection attributes that have been changed.
163 */
164 void collectionChanged(const Akonadi::Collection &collection, const QSet<QByteArray> &attributeNames);
165
166 /**
167 * This signal is emitted when one or more collections are added to the ETM.
168 *
169 * @param collection non empty list of collections
170 */
172
173 /**
174 * This signal is emitted when one or more collections are deleted from the ETM.
175 *
176 * @param collection non empty list of collections
177 */
179
180 /**
181 * Emitted whenever an Item is inserted, removed or modified.
182 */
184
185 /**
186 * Emitted whenever the set selected (checked) calendars was modified by the user.
187 * Typically used to save that new selection to a config file.
188 * @since 6.1.40
189 */
191
192private:
193 Q_DECLARE_PRIVATE(ETMCalendar)
194};
195}
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 Fri Jul 12 2024 11:56:25 by doxygen 1.11.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.