1/*
2 SPDX-FileCopyrightText: 2015 Martin Klapetek <mklapetek@kde.org>
3
4 SPDX-License-Identifier: LGPL-2.0-or-later
5*/
6
7#ifndef CALENDAREVENTSPLUGIN_H
8#define CALENDAREVENTSPLUGIN_H
9
10#include <QCalendar>
11#include <QDateTime>
12#include <QMultiHash>
13#include <QObject>
14#include <QSharedDataPointer>
15
16#include "calendarevents_export.h"
17
18/*!
19 * \namespace CalendarEvents
20 * \brief The CalendarEvents namespace.
21 */
22namespace CalendarEvents
23{
24
25/*!
26 * \class CalendarEvents::EventData
27 * \inheaderfile CalendarEvents/CalendarEventsPlugin
28 * \inmodule CalendarEvents
29 *
30 * \brief Data about an event.
31 */
32class CALENDAREVENTS_EXPORT EventData
33{
34public:
35 /*!
36 * \value Holiday Any holiday
37 * \value Event General Event
38 * \value Todo A Todo item
39 */
40 enum EventType {
41 Holiday,
42 Event,
43 Todo,
44 };
45
46 /*!
47 *
48 */
49 EventData();
50 EventData(const EventData &other);
51 ~EventData();
52
53 EventData &operator=(const EventData &other);
54
55 /*!
56 * The start date and time of this event
57 */
58 QDateTime startDateTime() const;
59
60 /*!
61 * Set the start date-time of this event
62 *
63 * \a startDateTime the date-time of when the event is starting
64 */
65 void setStartDateTime(const QDateTime &startDateTime);
66
67 /*!
68 * The end date and time of this event
69 */
70 QDateTime endDateTime() const;
71
72 /*!
73 * Set the end date-time of this event
74 *
75 * \a endDateTime the date-time of when the event is ending
76 */
77 void setEndDateTime(const QDateTime &endDateTime);
78
79 /*!
80 * If true, this event goes on the whole day (eg. a holiday)
81 */
82 bool isAllDay() const;
83
84 /*!
85 * If set to true, it will be displayed in the Calendar agenda
86 * without any time besides it, marked as "going on all day"
87 *
88 * This is useful for single-day events only, for multiple-day
89 * events, leave to false (default)
90 *
91 * \a isAllDay set to true if the event takes all day, false otherwise
92 * (defaults to false)
93 */
94 void setIsAllDay(bool isAllDay);
95
96 /*!
97 * If true, this event won't mark the day in the calendar grid
98 * The main purpose for this flag is to support
99 * namedays, where in some countries the calendars have
100 * different name in them every day. This is just a minor holiday
101 * and as such should not mark the calendar grid, otherwise
102 * the whole grid would be in a different color.
103 */
104 bool isMinor() const;
105
106 /*!
107 * If set to true, it won't be marked in the calendar grid
108 *
109 * \a isMinor true if it's a minor event (like a nameday holiday),
110 * false otherwise (defaults to false)
111 */
112 void setIsMinor(bool isMinor);
113
114 /*!
115 * Event title
116 */
117 QString title() const;
118
119 /*!
120 * Sets the title of the event
121 *
122 * \a title The event title
123 */
124 void setTitle(const QString &title);
125
126 /*!
127 * Event description, can provide more details about the event
128 */
129 QString description() const;
130
131 /*!
132 * Sets the event description, which allows to add more details
133 * about this event
134 *
135 * \a description The description
136 */
137 void setDescription(const QString &description);
138
139 /*!
140 * Type of the current event, eg. a holiday, an event or a todo item
141 */
142 EventType type() const;
143
144 /*!
145 * Sets the event type, eg. a holiday, an event or a todo item
146 *
147 * \a type The event type,
148 */
149 void setEventType(EventType type);
150
151 /*!
152 * The color that should be used to mark this event with
153 * It comes in the HTML hex format, eg. #AARRGGBB or #RRGGBB
154 */
155 QString eventColor() const;
156
157 /*!
158 * This is to support various calendar colors the user might
159 * have configured elsewhere
160 *
161 * \a color The color for this event in the HTML hex format
162 * eg. #AARRGGBB or #RRGGBB (this is passed directly
163 * to QML)
164 */
165 void setEventColor(const QString &color);
166
167 /*!
168 * Unique ID of the event
169 */
170 QString uid() const;
171
172 /*!
173 * Sets the uid of the event
174 *
175 * This is a mandatory field only if you want to use
176 * the eventModified/eventRemoved signals, otherwise
177 * setting it is optional
178 *
179 * \a uid A unique id, recommended is to use the plugin name as prefix (to keep it unique)
180 */
181 void setUid(const QString &uid);
182
183private:
184 class Private;
185 QSharedDataPointer<Private> d;
186};
187
188/*!
189 * \class CalendarEvents::CalendarEventsPlugin
190 * \inheaderfile CalendarEvents/CalendarEventsPlugin
191 * \inmodule CalendarEvents
192 *
193 * \brief Plugin for feeding events to a calendar instance.
194 */
195class CALENDAREVENTS_EXPORT CalendarEventsPlugin : public QObject
196{
197 Q_OBJECT
198
199public:
200 /*!
201 * \value Low Usually used in alternate calendars
202 * \value Default For holidays or normal events
203 * \value High For flagged or marked events
204 * \value Urgent
205 */
206 enum class SubLabelPriority {
207 Low,
208 Default,
209 High,
210 Urgent,
211 };
212 Q_ENUM(SubLabelPriority)
213
214 /*!
215 *
216 */
217 explicit CalendarEventsPlugin(QObject *parent = nullptr);
218 ~CalendarEventsPlugin() override;
219
220 /*!
221 * When this is called, the plugin should load all events data
222 * between those two date ranges. Once the data are ready, it should
223 * just emit the dataReady() signal. The range is usually one month
224 *
225 * \a startDate the start of the range
226 *
227 * \a endDate the end of the range
228 */
229 virtual void loadEventsForDateRange(const QDate &startDate, const QDate &endDate) = 0;
230
231 /*!
232 *
233 */
234 struct SubLabel {
235 /*! The label will be displayed in the tooltip or beside the full date */
236 QString label;
237 /*! The label will be displayed under the year number */
238 QString yearLabel;
239 /*! The label will be displayed under the month number */
240 QString monthLabel;
241 /*! The label will be displayed under the day number */
242 QString dayLabel;
243 /*! The display priority of the sublabel */
244 SubLabelPriority priority = SubLabelPriority::Default;
245 };
246
247Q_SIGNALS:
248 /*!
249 * Emitted when the plugin has loaded the events data
250 *
251 * \a data A hash containing a QDate key for the event
252 * in the value, CalendarEvents::EventData, which holds all
253 * the details for the given event
254 * It's a multihash as there can be multiple events
255 * in the same day
256 * For multi-day events, insert just one with the key
257 * being the startdate of the event
258 */
259 void dataReady(const QMultiHash<QDate, CalendarEvents::EventData> &data);
260
261 /*!
262 * Should be emitted when there is a modification of an event
263 * that was previously returned via the dataReady() signal
264 *
265 * \a event The modified event data
266 */
267 void eventModified(const CalendarEvents::EventData &modifiedEvent);
268
269 /*!
270 * Should be emitted when the plugin removes some event
271 * from its collection
272 *
273 * \a uid The uid of the event that was removed
274 */
275 void eventRemoved(const QString &uid);
276
277 /*!
278 * Emitted when the plugin has loaded the alternate dates
279 *
280 * \a data A hash containing a QDate key from Gregorian calendar
281 * for the alternate date in the value, QDate.
282 * \since 6.0
283 */
284 void alternateCalendarDateReady(const QHash<QDate, QCalendar::YearMonthDay> &data);
285
286 /*!
287 * Emitted when the plugin has loaded the sublabels
288 *
289 * \a data A hash containing a QDate key for the sublabels
290 * in the value, SubLabel.
291 * \since 5.95
292 */
293 void subLabelReady(const QHash<QDate, SubLabel> &data);
294};
295
296/*!
297 * \class CalendarEvents::ShowEventInterface
298 * \inheaderfile CalendarEvents/CalendarEventsPlugin
299 * \inmodule CalendarEvents
300 *
301 * \brief Interface for displaying event details.
302 *
303 * ShowEventInterface is an additional interface the CalendarEventsPlugin
304 * implementations can implement if they support displaying details about
305 * events (e.g. opening the event in KOrganizer).
306 *
307 * \since 5.61
308 */
309class CALENDAREVENTS_EXPORT ShowEventInterface
310{
311public:
312 virtual ~ShowEventInterface();
313
314 /*!
315 * When this is called, the plugin should show a window displaying the
316 * full preview of the event.
317 *
318 * The plugin should return true if the event details can be displayed, false
319 * otherwise.
320 */
321 virtual bool showEvent(const QString &uid) = 0;
322};
323
324}
325
326Q_DECLARE_INTERFACE(CalendarEvents::CalendarEventsPlugin, "org.kde.CalendarEventsPlugin")
327Q_DECLARE_INTERFACE(CalendarEvents::ShowEventInterface, "org.kde.CalendarEventsPlugin.ShowEventInterface")
328
329#endif
330

source code of kdeclarative/src/calendarevents/calendareventsplugin.h