KDeclarative

calendareventsplugin.h
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 */
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 */
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 */
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 */
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;
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 */
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 */
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 */
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
Plugin for feeding events to a calendar instance.
void eventModified(const CalendarEvents::EventData &modifiedEvent)
Should be emitted when there is a modification of an event that was previously returned via the dataR...
void alternateCalendarDateReady(const QHash< QDate, QCalendar::YearMonthDay > &data)
Emitted when the plugin has loaded the alternate dates.
virtual void loadEventsForDateRange(const QDate &startDate, const QDate &endDate)=0
When this is called, the plugin should load all events data between those two date ranges.
void dataReady(const QMultiHash< QDate, CalendarEvents::EventData > &data)
Emitted when the plugin has loaded the events data.
void eventRemoved(const QString &uid)
Should be emitted when the plugin removes some event from its collection.
void subLabelReady(const QHash< QDate, SubLabel > &data)
Emitted when the plugin has loaded the sublabels.
QString uid() const
Unique ID of the event.
void setStartDateTime(const QDateTime &startDateTime)
Set the start date-time of this event.
QString description() const
Event description, can provide more details about the event.
void setEventType(EventType type)
Sets the event type, eg.
void setEventColor(const QString &color)
This is to support various calendar colors the user might have configured elsewhere.
QDateTime startDateTime() const
The start date and time of this event.
void setTitle(const QString &title)
Sets the title of the event.
bool isMinor() const
If true, this event won't mark the day in the calendar grid The main purpose for this flag is to supp...
void setDescription(const QString &description)
Sets the event description, which allows to add more details about this event.
void setIsAllDay(bool isAllDay)
If set to true, it will be displayed in the Calendar agenda without any time besides it,...
void setEndDateTime(const QDateTime &endDateTime)
Set the end date-time of this event.
bool isAllDay() const
If true, this event goes on the whole day (eg.
void setIsMinor(bool isMinor)
If set to true, it won't be marked in the calendar grid.
void setUid(const QString &uid)
Sets the uid of the event.
QString title() const
Event title.
QString eventColor() const
The color that should be used to mark this event with It comes in the HTML hex format,...
EventType type() const
Type of the current event, eg.
QDateTime endDateTime() const
The end date and time of this event.
Interface for displaying event details.
virtual bool showEvent(const QString &uid)=0
When this is called, the plugin should show a window displaying the full preview of the event.
The CalendarEvents namespace.
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Tue Mar 26 2024 11:16:59 by doxygen 1.10.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.