KCalUtils

recurrenceactions.h
1/*
2 This file is part of the kcal library.
3
4 SPDX-FileCopyrightText: 2010 Klarälvdalens Datakonsult AB, a KDAB Group company <info@kdab.net>
5 SPDX-FileContributor: Kevin Krammer <krake@kdab.com>
6
7 SPDX-License-Identifier: LGPL-2.0-or-later
8*/
9
10#pragma once
11
12#include "kcalutils_export.h"
13
14#include <KCalendarCore/Incidence>
15
16class QDateTime;
17class KGuiItem;
18class QWidget;
19
20namespace KCalUtils
21{
22/**
23 @short Utility functions for dealing with recurrences
24
25 Incidences with recurrencies need to be treated differently than single independent ones.
26 For example the user might be given the choice to not only modify a selected occurrence
27 of an incidence but also all that follow that one, etc.
28
29 @author Kevin Krammer, krake@kdab.com
30 @since 4.6
31*/
32namespace RecurrenceActions
33{
34/**
35 @short Flags for indicating on which occurrences to work on
36
37 Flags can be OR'ed together to get a combined scope.
38*/
39enum Scope {
40 /**
41 Scope does not apply to any occurrence
42 */
44
45 /**
46 Scope does include the given/selected occurrence
47 */
49
50 /**
51 Scope does include occurrences before the given/selected occurrence
52 */
54
55 /**
56 Scope does include occurrences after the given/selected occurrence
57 */
59
60 /**
61 Scope does include all occurrences (past, present and future)
62 */
64};
65
66/**
67 @short Checks what scope an action could be applied on for a given incidence
68
69 Checks whether the incidence is occurring on the given date and whether there
70 are occurrences in the past and future.
71
72 @param incidence the incidence of which to check recurrences.
73 @param selectedOccurrence the date (including timespec) to use as the base occurrence,
74 i.e., from which to check for past and future occurrences.
75
76 @return the #Scope to which actions on the given @incidence can be applied to
77*/
78[[nodiscard]] KCALUTILS_EXPORT int availableOccurrences(const KCalendarCore::Incidence::Ptr &incidence, const QDateTime &selectedOccurrence);
79
80/**
81 @short Presents a multiple choice scope selection dialog to the user
82
83 Shows a message box style question dialog with checkboxes for occurrence scope flags
84 so the user can be asked specifically which occurrences to apply actions to.
85
86 @param selectedOccurrence the date to use for telling the user which occurrence
87 is the selected one.
88 @param message the message which explains the change and selection options.
89 @param caption the dialog's caption.
90 @param action the GUI item to use for the "OK" button.
91 @param availableChoices combined #Scope values to select which options should be present.
92 @param preselectedChoices combined #Scope values to optionally preselect some of the options
93 specified with @p availableChoices.
94 @param parent QWidget parent for the dialog.
95
96 @return the chosen #Scope options, OR'ed together
97*/
98[[nodiscard]] KCALUTILS_EXPORT int questionMultipleChoice(const QDateTime &selectedOccurrence,
99 const QString &message,
100 const QString &caption,
101 const KGuiItem &action,
102 int availableChoices,
103 int preselectedChoices,
104 QWidget *parent);
105
106/**
107 @short Presents a message box with two action choices and cancel to the user
108
109 Shows a message box style question dialog with two action scope buttons and cancel.
110 This is for quick decisions like whether to only modify a single occurrence or all occurrences.
111
112 @param message the message which explains the change and available options.
113 @param caption the dialog's caption.
114 @param actionSelected the GUI item to use for the button representing the
115 #SelectedOccurrence scope.
116 @param actionAll the GUI item to use for the button representing the #AllOccurrences scope.
117 @param parent QWidget parent for the dialog.
118
119 @param #NoOccurrence on cancel, #SelectedOccurrence or #AllOccurrences on the respective action.
120*/
121[[nodiscard]] KCALUTILS_EXPORT int
122questionSelectedAllCancel(const QString &message, const QString &caption, const KGuiItem &actionSelected, const KGuiItem &actionAll, QWidget *parent);
123
124/**
125 @short Presents a message box with three action choices and cancel to the user
126
127 Shows a message box style question dialog with three action scope buttons and cancel.
128 This is for quick decisions like whether to only modify a single occurrence, to include
129 future or all occurrences.
130
131 @note The calling application code can of course decide to word the future action text
132 in a way that it includes the selected occurrence, e.g. "Also Future Items".
133 The returned value will still just be #FutureOccurrences so the calling code
134 has to include #SelectedOccurrence itself if it passes the value further on
135
136 @param message the message which explains the change and available options.
137 @param caption the dialog's caption.
138 @param actionSelected the GUI item to use for the button representing the
139 #SelectedOccurrence scope.
140 @param actionSelected the GUI item to use for the button representing the
141 #FutureOccurrences scope.
142 @param actionAll the GUI item to use for the button representing the #AllOccurrences scope.
143 @param parent QWidget parent for the dialog.
144
145 @param #NoOccurrence on cancel, #SelectedOccurrence, #FutureOccurrences or #AllOccurrences
146 on the respective action.
147*/
148[[nodiscard]] KCALUTILS_EXPORT int questionSelectedFutureAllCancel(const QString &message,
149 const QString &caption,
150 const KGuiItem &actionSelected,
151 const KGuiItem &actionFuture,
152 const KGuiItem &actionAll,
153 QWidget *parent);
154}
155}
KCALUTILS_EXPORT int availableOccurrences(const KCalendarCore::Incidence::Ptr &incidence, const QDateTime &selectedOccurrence)
Checks what scope an action could be applied on for a given incidence.
KCALUTILS_EXPORT int questionSelectedFutureAllCancel(const QString &message, const QString &caption, const KGuiItem &actionSelected, const KGuiItem &actionFuture, const KGuiItem &actionAll, QWidget *parent)
Presents a message box with three action choices and cancel to the user.
KCALUTILS_EXPORT int questionMultipleChoice(const QDateTime &selectedOccurrence, const QString &message, const QString &caption, const KGuiItem &action, int availableChoices, int preselectedChoices, QWidget *parent)
Presents a multiple choice scope selection dialog to the user.
Scope
Flags for indicating on which occurrences to work on.
@ SelectedOccurrence
Scope does include the given/selected occurrence.
@ AllOccurrences
Scope does include all occurrences (past, present and future)
@ FutureOccurrences
Scope does include occurrences after the given/selected occurrence.
@ PastOccurrences
Scope does include occurrences before the given/selected occurrence.
@ NoOccurrence
Scope does not apply to any occurrence.
KCALUTILS_EXPORT int questionSelectedAllCancel(const QString &message, const QString &caption, const KGuiItem &actionSelected, const KGuiItem &actionAll, QWidget *parent)
Presents a message box with two action choices and cancel to the user.
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Tue Mar 26 2024 11:20:39 by doxygen 1.10.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.