KCalendarCore

calfilter.h
Go to the documentation of this file.
1/*
2 This file is part of the kcalcore library.
3
4 SPDX-FileCopyrightText: 2001, 2003, 2004 Cornelius Schumacher <schumacher@kde.org>
5 SPDX-FileCopyrightText: 2003-2004 Reinhold Kainhofer <reinhold@kainhofer.com>
6
7 SPDX-License-Identifier: LGPL-2.0-or-later
8*/
9/**
10 @file
11 This file is part of the API for handling calendar data and
12 defines the CalFilter class.
13
14 @author Cornelius Schumacher <schumacher@kde.org>
15 @author Reinhold Kainhofer <reinhold@kainhofer.com>
16*/
17
18#ifndef KCALCORE_CALFILTER_H
19#define KCALCORE_CALFILTER_H
20
21#include "event.h"
22#include "journal.h"
23#include "kcalendarcore_export.h"
24#include "todo.h"
25
26namespace KCalendarCore
27{
28/**
29 @brief
30 Provides a filter for calendars.
31
32 This class provides a means for filtering calendar incidences by
33 a list of email addresses, a list of categories, or other #Criteria.
34
35 The following #Criteria are available:
36 - remove recurring Incidences
37 - keep Incidences with a matching category (see setCategoryList())
38 - remove completed To-dos (see setCompletedTimeSpan())
39 - remove inactive To-dos
40 - remove To-dos without a matching attendee (see setEmailList())
41*/
42class KCALENDARCORE_EXPORT CalFilter
43{
44public:
45 /**
46 Filtering Criteria.
47 */
48 enum Criteria {
49 HideRecurring = 1, /**< Remove incidences that recur */
50 HideCompletedTodos = 2, /**< Remove completed to-dos */
51 ShowCategories = 4, /**< Show incidences with at least one matching category */
52 HideInactiveTodos = 8, /**< Remove to-dos that haven't started yet */
53 HideNoMatchingAttendeeTodos = 16, /**< Remove to-dos without a matching attendee */
54 };
55
56 /**
57 Constructs an empty filter -- a filter without a name or criteria.
58 */
59 CalFilter();
60
61 /**
62 Constructs a filter with @p name.
63
64 @param name is the name of this filter.
65 */
66 explicit CalFilter(const QString &name);
67
68 /**
69 Destroys this filter.
70 */
71 ~CalFilter();
72
73 /**
74 Sets the filter name.
75
76 @param name is the name of this filter.
77 @see name().
78 */
79 void setName(const QString &name);
80
81 /**
82 Returns the filter name.
83 @see setName().
84 */
85 Q_REQUIRED_RESULT QString name() const;
86
87 /**
88 Sets the criteria which must be fulfilled for an Incidence to pass
89 the filter.
90
91 @param criteria is a combination of #Criteria.
92 @see criteria().
93 */
94 void setCriteria(int criteria);
95
96 /**
97 Returns the inclusive filter criteria.
98 @see setCriteria().
99 */
100 Q_REQUIRED_RESULT int criteria() const;
101
102 /**
103 Applies the filter to a list of Events. All events not matching the
104 filter criteria are removed from the list.
105
106 @param eventList is a list of Events to filter.
107 */
108 void apply(Event::List *eventList) const;
109
110 /**
111 Applies the filter to a list of To-dos. All to-dos not matching the
112 filter criteria are removed from the list.
113
114 @param todoList is a list of To-dos to filter.
115 */
116 void apply(Todo::List *todoList) const;
117
118 /**
119 Applies the filter to a list of Journals. All journals not matching the
120 filter criteria are removed from the list.
121
122 @param journalList is a list of Journals to filter.
123 */
124 void apply(Journal::List *journalList) const;
125
126 /**
127 Applies the filter criteria to the specified Incidence.
128
129 @param incidence is the Incidence to filter.
130 @return true if the Incidence passes the criteria; false otherwise.
131 */
132 Q_REQUIRED_RESULT bool filterIncidence(const Incidence::Ptr &incidence) const;
133
134 /**
135 Enables or disables the filter.
136
137 @param enabled is true if the filter is to be enabled; false otherwise.
138 @see isEnabled().
139 */
140 void setEnabled(bool enabled);
141
142 /**
143 Returns whether the filter is enabled or not.
144 @see setEnabled().
145 */
146 Q_REQUIRED_RESULT bool isEnabled() const;
147
148 /**
149 Sets the list of categories to be considered when filtering incidences
150 according to the #ShowCategories criteria.
151
152 @param categoryList is a QStringList of categories.
153 @see categoryList().
154 */
155 void setCategoryList(const QStringList &categoryList);
156
157 /**
158 Returns the category list for this filter.
159 @see setCategoryList().
160 */
161 Q_REQUIRED_RESULT QStringList categoryList() const;
162
163 /**
164 Sets the list of email addresses to be considered when filtering
165 incidences according to the #HideNoMatchingAttendeeTodos criteria.
166
167 @param emailList is a QStringList of email addresses.
168 @see emailList().
169 */
170 void setEmailList(const QStringList &emailList);
171
172 /**
173 Returns the email list for this filter.
174 @see setEmailList().
175 */
176 Q_REQUIRED_RESULT QStringList emailList() const;
177
178 /**
179 Sets the number of days for the #HideCompletedTodos criteria.
180 If a to-do has been completed within the recent @p timespan days,
181 then that to-do will be removed during filtering. If a time span is
182 not specified in the filter, then all completed to-dos will be removed
183 if the #HideCompletedTodos criteria is set.
184
185 @param timespan is an integer representing a time span in days.
186 @see completedTimeSpan().
187 */
188 void setCompletedTimeSpan(int timespan);
189
190 /**
191 Returns the completed time span for this filter.
192 @see setCompletedTimeSpan()
193 */
194 Q_REQUIRED_RESULT int completedTimeSpan() const;
195
196 /**
197 Compares this with @p filter for equality.
198
199 @param filter the CalFilter to compare.
200 */
201 bool operator==(const CalFilter &filter) const;
202
203private:
204 //@cond PRIVATE
205 Q_DISABLE_COPY(CalFilter)
206 class Private;
207 Private *const d;
208 //@endcond
209};
210
211}
212
213#endif
Provides a filter for calendars.
Definition calfilter.h:43
void apply(Todo::List *todoList) const
Applies the filter to a list of To-dos.
void apply(Journal::List *journalList) const
Applies the filter to a list of Journals.
Criteria
Filtering Criteria.
Definition calfilter.h:48
This file is part of the API for handling calendar data and defines the Event class.
This file is part of the API for handling calendar data and defines the Journal class.
Namespace for all KCalendarCore types.
Definition alarm.h:37
This file is part of the API for handling calendar data and defines the Todo class.
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Fri Dec 6 2024 12:01:23 by doxygen 1.12.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.