File indexing completed on 2024-05-12 05:15:03
0001 /* 0002 This file is part of the kcal library. 0003 0004 SPDX-FileCopyrightText: 2010 Klarälvdalens Datakonsult AB, a KDAB Group company <info@kdab.net> 0005 SPDX-FileContributor: Kevin Krammer <krake@kdab.com> 0006 0007 SPDX-License-Identifier: LGPL-2.0-or-later 0008 */ 0009 0010 #pragma once 0011 0012 #include "kcalutils_export.h" 0013 0014 #include <KCalendarCore/Incidence> 0015 0016 class QDateTime; 0017 class KGuiItem; 0018 class QWidget; 0019 0020 namespace KCalUtils 0021 { 0022 /** 0023 @short Utility functions for dealing with recurrences 0024 0025 Incidences with recurrencies need to be treated differently than single independent ones. 0026 For example the user might be given the choice to not only modify a selected occurrence 0027 of an incidence but also all that follow that one, etc. 0028 0029 @author Kevin Krammer, krake@kdab.com 0030 @since 4.6 0031 */ 0032 namespace RecurrenceActions 0033 { 0034 /** 0035 @short Flags for indicating on which occurrences to work on 0036 0037 Flags can be OR'ed together to get a combined scope. 0038 */ 0039 enum Scope { 0040 /** 0041 Scope does not apply to any occurrence 0042 */ 0043 NoOccurrence = 0, 0044 0045 /** 0046 Scope does include the given/selected occurrence 0047 */ 0048 SelectedOccurrence = 1, 0049 0050 /** 0051 Scope does include occurrences before the given/selected occurrence 0052 */ 0053 PastOccurrences = 2, 0054 0055 /** 0056 Scope does include occurrences after the given/selected occurrence 0057 */ 0058 FutureOccurrences = 4, 0059 0060 /** 0061 Scope does include all occurrences (past, present and future) 0062 */ 0063 AllOccurrences = PastOccurrences | SelectedOccurrence | FutureOccurrences 0064 }; 0065 0066 /** 0067 @short Checks what scope an action could be applied on for a given incidence 0068 0069 Checks whether the incidence is occurring on the given date and whether there 0070 are occurrences in the past and future. 0071 0072 @param incidence the incidence of which to check recurrences. 0073 @param selectedOccurrence the date (including timespec) to use as the base occurrence, 0074 i.e., from which to check for past and future occurrences. 0075 0076 @return the #Scope to which actions on the given @incidence can be applied to 0077 */ 0078 [[nodiscard]] KCALUTILS_EXPORT int availableOccurrences(const KCalendarCore::Incidence::Ptr &incidence, const QDateTime &selectedOccurrence); 0079 0080 /** 0081 @short Presents a multiple choice scope selection dialog to the user 0082 0083 Shows a message box style question dialog with checkboxes for occurrence scope flags 0084 so the user can be asked specifically which occurrences to apply actions to. 0085 0086 @param selectedOccurrence the date to use for telling the user which occurrence 0087 is the selected one. 0088 @param message the message which explains the change and selection options. 0089 @param caption the dialog's caption. 0090 @param action the GUI item to use for the "OK" button. 0091 @param availableChoices combined #Scope values to select which options should be present. 0092 @param preselectedChoices combined #Scope values to optionally preselect some of the options 0093 specified with @p availableChoices. 0094 @param parent QWidget parent for the dialog. 0095 0096 @return the chosen #Scope options, OR'ed together 0097 */ 0098 [[nodiscard]] KCALUTILS_EXPORT int questionMultipleChoice(const QDateTime &selectedOccurrence, 0099 const QString &message, 0100 const QString &caption, 0101 const KGuiItem &action, 0102 int availableChoices, 0103 int preselectedChoices, 0104 QWidget *parent); 0105 0106 /** 0107 @short Presents a message box with two action choices and cancel to the user 0108 0109 Shows a message box style question dialog with two action scope buttons and cancel. 0110 This is for quick decisions like whether to only modify a single occurrence or all occurrences. 0111 0112 @param message the message which explains the change and available options. 0113 @param caption the dialog's caption. 0114 @param actionSelected the GUI item to use for the button representing the 0115 #SelectedOccurrence scope. 0116 @param actionAll the GUI item to use for the button representing the #AllOccurrences scope. 0117 @param parent QWidget parent for the dialog. 0118 0119 @param #NoOccurrence on cancel, #SelectedOccurrence or #AllOccurrences on the respective action. 0120 */ 0121 [[nodiscard]] KCALUTILS_EXPORT int 0122 questionSelectedAllCancel(const QString &message, const QString &caption, const KGuiItem &actionSelected, const KGuiItem &actionAll, QWidget *parent); 0123 0124 /** 0125 @short Presents a message box with three action choices and cancel to the user 0126 0127 Shows a message box style question dialog with three action scope buttons and cancel. 0128 This is for quick decisions like whether to only modify a single occurrence, to include 0129 future or all occurrences. 0130 0131 @note The calling application code can of course decide to word the future action text 0132 in a way that it includes the selected occurrence, e.g. "Also Future Items". 0133 The returned value will still just be #FutureOccurrences so the calling code 0134 has to include #SelectedOccurrence itself if it passes the value further on 0135 0136 @param message the message which explains the change and available options. 0137 @param caption the dialog's caption. 0138 @param actionSelected the GUI item to use for the button representing the 0139 #SelectedOccurrence scope. 0140 @param actionSelected the GUI item to use for the button representing the 0141 #FutureOccurrences scope. 0142 @param actionAll the GUI item to use for the button representing the #AllOccurrences scope. 0143 @param parent QWidget parent for the dialog. 0144 0145 @param #NoOccurrence on cancel, #SelectedOccurrence, #FutureOccurrences or #AllOccurrences 0146 on the respective action. 0147 */ 0148 [[nodiscard]] KCALUTILS_EXPORT int questionSelectedFutureAllCancel(const QString &message, 0149 const QString &caption, 0150 const KGuiItem &actionSelected, 0151 const KGuiItem &actionFuture, 0152 const KGuiItem &actionAll, 0153 QWidget *parent); 0154 } 0155 }