Akonadi Calendar

itiphandler.h
1/*
2 SPDX-FileCopyrightText: 2002-2004 Klarälvdalens Datakonsult AB,
3 <info@klaralvdalens-datakonsult.se>
4
5 SPDX-FileCopyrightText: 2010 Bertjan Broeksema <broeksema@kde.org>
6 SPDX-FileCopyrightText: 2010 Klaralvdalens Datakonsult AB, a KDAB Group company <info@kdab.net>
7
8 SPDX-FileCopyrightText: 2012 SĂ©rgio Martins <iamsergio@gmail.com>
9
10 SPDX-License-Identifier: LGPL-2.0-or-later
11*/
12
13#pragma once
14
15#include "akonadi-calendar_export.h"
16#include "etmcalendar.h"
17
18#include <KCalendarCore/Incidence>
19#include <KCalendarCore/ScheduleMessage>
20
21#include <KGuiItem>
22#include <KLocalizedString>
23#include <KStandardGuiItem>
24
25#include <QObject>
26#include <QString>
27#include <QWidget>
28
29#include <memory>
30
31namespace Akonadi
32{
33class MessageQueueJob;
34}
35
36namespace KIdentityManagementCore
37{
38class Identity;
39}
40
41namespace Akonadi
42{
43class ITIPHandlerPrivate;
44
45/**
46 * @short Ui delegate for editing counter proposals.
47 * @since 4.11
48 */
49class AKONADI_CALENDAR_EXPORT GroupwareUiDelegate : public QObject
50{
51 Q_OBJECT
52public:
53 explicit GroupwareUiDelegate(QObject *parent = nullptr);
54 ~GroupwareUiDelegate() override;
55
56 virtual void requestIncidenceEditor(const Akonadi::Item &item) = 0;
57 virtual void setCalendar(const Akonadi::ETMCalendar::Ptr &calendar) = 0;
58 virtual void createCalendar() = 0;
59};
60
61/**
62 * @short Ui delegate for dialogs raised by the ITIPHandler and IncidenceChanger.
63 * @since 4.15
64 */
65class AKONADI_CALENDAR_EXPORT ITIPHandlerDialogDelegate : public QObject
66{
67 Q_OBJECT
68public:
69 // Possible default actions
70 enum Action {
71 ActionAsk, /**< Ask the user for a decision */
72 ActionSendMessage, /**< Answer with Yes */
73 ActionDontSendMessage /**< Answer with No */
74 };
75
76 // How will receive the mail afterwards
77 enum Recipient {
78 Organizer, /**< the organizer of the incidence */
79 Attendees /**< the attendees of the incidence */
80 };
81
82 enum DialogAction { OkAction = 1, CancelAction = 2, PrimaryAction = 3, SecondaryAction = 4, ContinueAction = 5 };
83
84 /**
85 * Creates a new AskDelegator
86 */
88
89 /*
90 * Opens a Dialog, when an incidence is created
91 * The function must emit a dialogClosed signal with the user's answer
92 *
93 * @param recipient: to who the mail will be sent afterwards
94 * @param question: dialog's question
95 * @param action: Should the dialog been shown or should a default answer be returned
96 * @param buttonYes: dialog's yes answer
97 * @param buttonNo: dialog's no answer
98 */
99 virtual void openDialogIncidenceCreated(Recipient recipient,
100 const QString &question,
101 Action action = ActionAsk,
102 const KGuiItem &buttonYes = KGuiItem(i18nc("@action:button dialog positive answer", "Send Email")),
103 const KGuiItem &buttonNo = KGuiItem(i18nc("@action:button dialog negative answer", "Do Not Send")));
104
105 /*
106 * Opens a Dialog, when an incidence is modified
107 * The function must emit a dialogClosed signal with the user's answer
108 *
109 * @param attendeeStatusChanged: Only the status of the own attendeeStatus is changed
110 * @param recipient: to who the mail will be sent afterwards
111 * @param question: dialog's question
112 * @param action: Should the dialog been shown or should a default answer be returned
113 * @param buttonYes: dialog's yes answer
114 * @param buttonNo: dialog's no answer
115 */
116 virtual void openDialogIncidenceModified(bool attendeeStatusChanged,
117 Recipient recipient,
118 const QString &question,
119 Action action = ActionAsk,
120 const KGuiItem &buttonYes = KGuiItem(i18nc("@action:button dialog positive answer", "Send Email")),
121 const KGuiItem &buttonNo = KGuiItem(i18nc("@action:button dialog negative answer", "Do Not Send")));
122
123 /*
124 * Opens a Dialog, when an incidence is deleted
125 * The function must emit a dialogClosed signal with the user's answer
126 *
127 * @param recipient: to who the mail will be sent afterwards
128 * @param question: dialog's question
129 * @param action: Should the dialog been shown or should a default answer be returned
130 * @param buttonYes: dialog's yes answer
131 * @param buttonNo: dialog's no answer
132 */
133 virtual void openDialogIncidenceDeleted(Recipient recipient,
134 const QString &question,
135 Action action = ActionAsk,
136 const KGuiItem &buttonYes = KGuiItem(i18nc("@action:button dialog positive answer", "Send Email")),
137 const KGuiItem &buttonNo = KGuiItem(i18nc("@action:button dialog negative answer", "Do Not Send")));
138 /*
139 * Opens a Dialog, when mail was sended
140 * The function must emit a dialogClosed signal with the user's answer
141 *
142 * @param question: dialog's question
143 * @param action: Should the dialog been shown or should a default answer be returned
144 * @param buttonYes: dialog's yes answer
145 * @param buttonNo: dialog's no answer
146 */
147 virtual void openDialogSchedulerFinished(const QString &question,
148 Action action = ActionAsk,
149 const KGuiItem &buttonYes = KGuiItem(i18nc("@action:button dialog positive answer", "Send Email")),
150 const KGuiItem &buttonNo = KGuiItem(i18nc("@action:button dialog negative answer", "Do Not Send")));
151
152 /**
153 * Opens a warning message box with two accept actions and cancel action.
154 * @param text: dialog's text
155 * @param title: dialog's title
156 * @param primaryAction: dialog's primary action
157 * @param secondaryAction: dialog's secondary action
158 * @param cancelAction: dialog's cancel action
159 * @returns The button clicked by the user (KMessageBox::ButtonCode)
160 */
161 virtual int warningTwoActionsCancel(const QString &text,
162 const QString &title,
163 const KGuiItem &primaryAction,
164 const KGuiItem &secondaryAction,
165 const KGuiItem &cancelAction = KStandardGuiItem::cancel());
166 /**
167 * Opens a warning message box with a Continue and Cancel actions
168 * @param text: dialog's text
169 * @param title: dialog's title
170 * @param buttonContinue: dialog's continue answer
171 * @param buttonCancel: dialog's cancel answer.
172 * @returns The button clicked by the user (KMessageBox::ButtonCode)
173 */
174 [[nodiscard]] virtual int warningContinueCancel(const QString &text,
175 const QString &title,
176 const KGuiItem &buttonContinue = KStandardGuiItem::cont(),
177 const KGuiItem &buttonCancel = KStandardGuiItem::cancel());
178
179Q_SIGNALS:
180 /*
181 * Signal is emitted, when the user has answered the dialog or the defaultAction is used
182 * @param answer: answer should be part of KMessageBox:ButtonCode, keep in mind that it is a YesNoDialog so normally it should be KMessageBox::Yes or
183 * KMessageBox::No
184 * @param method: itip method
185 * @param incidence: purpose of the dialog
186 */
187 void dialogClosed(int answer, KCalendarCore::iTIPMethod method, const KCalendarCore::Incidence::Ptr &incidence);
188
189protected:
190 /*
191 * Opens a KMessageBox::questionYesNo with the question
192 *
193 * @return KMessageBox::Yes or KMessageBox::No
194 *
195 * @param question: dialog's question
196 * @param action: Should the dialog been shown or should a default answer be returned
197 * @param buttonYes: dialog's yes answer
198 * @param buttonNo: dialog's no answer
199 */
200 int askUserIfNeeded(const QString &question, Action action, const KGuiItem &buttonYes, const KGuiItem &buttonNo) const;
201
202 // parent of the dialog
203 QWidget *mParent = nullptr;
204
205 // Incidence related to the dialog
207
208 // ITIPMethod related to the dialog
210};
211
212/**
213 * @short Factory to create Akonadi::MessageQueueJob jobs or ITIPHandlerDialogDelegate objects.
214 * @since 4.15
215 */
216class AKONADI_CALENDAR_EXPORT ITIPHandlerComponentFactory : public QObject
217{
218 Q_OBJECT
219public:
220 /*
221 * Created a new ITIPHandlerComponentFactory object.
222 */
223 explicit ITIPHandlerComponentFactory(QObject *parent = nullptr);
224
225 /*
226 * deletes the object.
227 */
229
230 /*
231 * @return A new Akonadi::MessageQueueJob object
232 * @param incidence related to the mail
233 * @param identity that is the mail sender
234 * @param parent of the Akonadi::MessageQueueJob object
235 */
237 createMessageQueueJob(const KCalendarCore::IncidenceBase::Ptr &incidence, const KIdentityManagementCore::Identity &identity, QObject *parent = nullptr);
238
239 /*
240 * @return A new ITIPHandlerDialogDelegate object
241 * @param incidence the purpose of the dialogs
242 * @param method the ITIPMethod
243 * @parent parent of the AskDelegator
244 *
245 */
247 createITIPHanderDialogDelegate(const KCalendarCore::Incidence::Ptr &incidence, KCalendarCore::iTIPMethod method, QWidget *parent = nullptr);
248};
249
250/**
251 * @short Handles sending of iTip messages as well as processing incoming ones.
252 * @since 4.11
253 */
254class AKONADI_CALENDAR_EXPORT ITIPHandler : public QObject
255{
256 Q_OBJECT
257public:
258 enum Result {
259 ResultError, /**< An unexpected error occurred */
260 ResultSuccess, /**< The invitation was successfully handled. */
261 ResultCancelled /**< User cancelled the operation. @since 4.12 */
262 };
263
264 /**
265 * Creates a new ITIPHandler instance.
266 * creates a default ITIPHandlerComponentFactory object.
267 */
268 explicit ITIPHandler(QObject *parent = nullptr);
269
270 /**
271 * Create a new ITIPHandler instance.
272 * @param factory is set to 0 a new factory is created.
273 * @since 4.15
274 */
275 explicit ITIPHandler(ITIPHandlerComponentFactory *factory, QObject *parent);
276 /**
277 * Destroys this instance.
278 */
279 ~ITIPHandler() override;
280
281 /**
282 * Processes a received iTip message.
283 *
284 * @param receiver
285 * @param iCal
286 * @param type
287 *
288 * @see iTipMessageProcessed()
289 */
290 void processiTIPMessage(const QString &receiver, const QString &iCal, const QString &type);
291
292 /**
293 * Sends an iTip message.
294 *
295 * @param method iTip method
296 * @param incidence Incidence for which we're sending the iTip message.
297 * Should contain a list of attendees.
298 * @param parentWidget
299 */
300 void sendiTIPMessage(KCalendarCore::iTIPMethod method, const KCalendarCore::Incidence::Ptr &incidence, QWidget *parentWidget = nullptr);
301
302 /**
303 * Publishes incidence @p incidence.
304 * A publish dialog will prompt the user to input recipients.
305 * @see rfc2446 3.2.1
306 */
307 void publishInformation(const KCalendarCore::Incidence::Ptr &incidence, QWidget *parentWidget = nullptr);
308
309 /**
310 * Sends an e-mail with the incidence attached as iCalendar source.
311 * A dialog will prompt the user to input recipients.
312 */
313 void sendAsICalendar(const KCalendarCore::Incidence::Ptr &incidence, QWidget *parentWidget = nullptr);
314
315 /**
316 * Sets the UI delegate to edit counter proposals.
317 */
318 void setGroupwareUiDelegate(GroupwareUiDelegate *delegate);
319
320 /**
321 * Sets the calendar that the itip handler should use.
322 * The calendar should already be loaded.
323 *
324 * If none is set, a FetchJobCalendar will be created internally.
325 */
326 void setCalendar(const Akonadi::CalendarBase::Ptr &calendar);
327
328 /**
329 * Sets if the ITIP handler should show dialogs on error.
330 * Default is true, for compatibility reasons, but this will change in KDE5.
331 * TODO_KDE5: use message delegates
332 *
333 * @since 4.12
334 */
335 void setShowDialogsOnError(bool enable);
336
337 /**
338 * Returns the calendar used by this itip handler.
339 */
340 Akonadi::CalendarBase::Ptr calendar() const;
341
342Q_SIGNALS:
343 /**
344 * Sent after processing an incoming iTip message.
345 *
346 * @param result success of the operation.
347 * @param errorMessage translated error message suitable for user dialogs.
348 * Empty if the operation was successful
349 */
351
352 /**
353 * Signal emitted after an iTip message was sent through sendiTIPMessage()
354 */
356
357 /**
358 * Signal emitted after an incidence was published with publishInformation()
359 */
361
362 /**
363 * Signal emitted after an incidence was sent with sendAsICalendar()
364 */
366
367private:
368 Q_DISABLE_COPY(ITIPHandler)
369 std::unique_ptr<ITIPHandlerPrivate> const d;
370};
371}
Ui delegate for editing counter proposals.
Definition itiphandler.h:50
Factory to create Akonadi::MessageQueueJob jobs or ITIPHandlerDialogDelegate objects.
Ui delegate for dialogs raised by the ITIPHandler and IncidenceChanger.
Definition itiphandler.h:66
ITIPHandlerDialogDelegate(const KCalendarCore::Incidence::Ptr &incidence, KCalendarCore::iTIPMethod method, QWidget *parent=nullptr)
Creates a new AskDelegator.
virtual int warningTwoActionsCancel(const QString &text, const QString &title, const KGuiItem &primaryAction, const KGuiItem &secondaryAction, const KGuiItem &cancelAction=KStandardGuiItem::cancel())
Opens a warning message box with two accept actions and cancel action.
@ ActionAsk
Ask the user for a decision.
Definition itiphandler.h:71
@ ActionSendMessage
Answer with Yes.
Definition itiphandler.h:72
@ Organizer
the organizer of the incidence
Definition itiphandler.h:78
virtual int warningContinueCancel(const QString &text, const QString &title, const KGuiItem &buttonContinue=KStandardGuiItem::cont(), const KGuiItem &buttonCancel=KStandardGuiItem::cancel())
Opens a warning message box with a Continue and Cancel actions.
Handles sending of iTip messages as well as processing incoming ones.
~ITIPHandler() override
Destroys this instance.
@ ResultSuccess
The invitation was successfully handled.
@ ResultError
An unexpected error occurred.
void iTipMessageProcessed(Akonadi::ITIPHandler::Result result, const QString &errorMessage)
Sent after processing an incoming iTip message.
void iTipMessageSent(Akonadi::ITIPHandler::Result, const QString &errorMessage)
Signal emitted after an iTip message was sent through sendiTIPMessage()
void sentAsICalendar(Akonadi::ITIPHandler::Result, const QString &errorMessage)
Signal emitted after an incidence was sent with sendAsICalendar()
void informationPublished(Akonadi::ITIPHandler::Result, const QString &errorMessage)
Signal emitted after an incidence was published with publishInformation()
QString i18nc(const char *context, const char *text, const TYPE &arg...)
FreeBusyManager::Singleton.
KGuiItem cont()
KGuiItem cancel()
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Fri Jul 19 2024 11:52:11 by doxygen 1.11.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.