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

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