1/*
2 This file is part of the kcalcore library.
3
4 Copyright (c) 2001,2003,2004 Cornelius Schumacher <schumacher@kde.org>
5 Copyright (C) 2003-2004 Reinhold Kainhofer <reinhold@kainhofer.com>
6
7 This library is free software; you can redistribute it and/or
8 modify it under the terms of the GNU Library General Public
9 License as published by the Free Software Foundation; either
10 version 2 of the License, or (at your option) any later version.
11
12 This library is distributed in the hope that it will be useful,
13 but WITHOUT ANY WARRANTY; without even the implied warranty of
14 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15 Library General Public License for more details.
16
17 You should have received a copy of the GNU Library General Public License
18 along with this library; see the file COPYING.LIB. If not, write to
19 the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
20 Boston, MA 02110-1301, USA.
21*/
22/**
23 @file
24 This file is part of the API for handling calendar data and
25 defines the CalFilter class.
26
27 @author Cornelius Schumacher \<schumacher@kde.org\>
28 @author Reinhold Kainhofer \<reinhold@kainhofer.com\>
29*/
30
31#ifndef KCALCORE_CALFILTER_H
32#define KCALCORE_CALFILTER_H
33
34#include "kcalcore_export.h"
35#include "event.h"
36#include "journal.h"
37#include "todo.h"
38
39namespace KCalCore {
40
41/**
42 @brief
43 Provides a filter for calendars.
44
45 This class provides a means for filtering calendar incidences by
46 a list of email addresses, a list of categories, or other #Criteria.
47
48 The following #Criteria are available:
49 - remove recurring Incidences
50 - keep Incidences with a matching category (see setCategoryList())
51 - remove completed To-dos (see setCompletedTimeSpan())
52 - remove inactive To-dos
53 - remove To-dos without a matching attendee (see setEmailList())
54*/
55class KCALCORE_EXPORT CalFilter
56{
57public:
58 /**
59 Filtering Criteria.
60 */
61 enum Criteria {
62 HideRecurring = 1, /**< Remove incidences that recur */
63 HideCompletedTodos = 2,/**< Remove completed to-dos */
64 ShowCategories = 4, /**< Show incidences with at least one matching category */
65 HideInactiveTodos = 8, /**< Remove to-dos that haven't started yet */
66 HideNoMatchingAttendeeTodos = 16 /**< Remove to-dos without a matching attendee */
67 };
68
69 /**
70 Constructs an empty filter -- a filter without a name or criteria.
71 */
72 CalFilter();
73
74 /**
75 Constructs a filter with @p name.
76
77 @param name is the name of this filter.
78 */
79 explicit CalFilter(const QString &name);
80
81 /**
82 Destroys this filter.
83 */
84 ~CalFilter();
85
86 /**
87 Sets the filter name.
88
89 @param name is the name of this filter.
90 @see name().
91 */
92 void setName(const QString &name);
93
94 /**
95 Returns the filter name.
96 @see setName().
97 */
98 QString name() const;
99
100 /**
101 Sets the criteria which must be fulfilled for an Incidence to pass
102 the filter.
103
104 @param criteria is a combination of #Criteria.
105 @see criteria().
106 */
107 void setCriteria(int criteria);
108
109 /**
110 Returns the inclusive filter criteria.
111 @see setCriteria().
112 */
113 int criteria() const;
114
115 /**
116 Applies the filter to a list of Events. All events not matching the
117 filter criteria are removed from the list.
118
119 @param eventList is a list of Events to filter.
120 */
121 void apply(Event::List *eventList) const;
122
123 /**
124 Applies the filter to a list of To-dos. All to-dos not matching the
125 filter criterias are removed from the list.
126
127 @param todoList is a list of To-dos to filter.
128 */
129 void apply(Todo::List *todoList) const;
130
131 /**
132 Applies the filter to a list of Journals. All journals not matching the
133 filter criterias are removed from the list.
134
135 @param journalList is a list of Journals to filter.
136 */
137 void apply(Journal::List *journalList) const;
138
139 /**
140 Applies the filter criteria to the specified Incidence.
141
142 @param incidence is the Incidence to filter.
143 @return true if the Incidence passes the criteria; false otherwise.
144 */
145 bool filterIncidence(Incidence::Ptr incidence) const;
146
147 /**
148 Enables or disables the filter.
149
150 @param enabled is true if the filter is to be enabled; false otherwise.
151 @see isEnabled().
152 */
153 void setEnabled(bool enabled);
154
155 /**
156 Returns whether the filter is enabled or not.
157 @see setEnabled().
158 */
159 bool isEnabled() const;
160
161 /**
162 Sets the list of categories to be considered when filtering incidences
163 according to the #ShowCategories criteria.
164
165 @param categoryList is a QStringList of categories.
166 @see categoryList().
167 */
168 void setCategoryList(const QStringList &categoryList);
169
170 /**
171 Returns the category list for this filter.
172 @see setCategoryList().
173 */
174 QStringList categoryList() const;
175
176 /**
177 Sets the list of email addresses to be considered when filtering
178 incidences according ot the #HideNoMatchingAttendeeTodos criteria.
179
180 @param emailList is a QStringList of email addresses.
181 @see emailList().
182 */
183 void setEmailList(const QStringList &emailList);
184
185 /**
186 Returns the email list for this filter.
187 @see setEmailList().
188 */
189 QStringList emailList() const;
190
191 /**
192 Sets the number of days for the #HideCompletedTodos criteria.
193 If a to-do has been completed within the recent @p timespan days,
194 then that to-do will be removed during filtering. If a time span is
195 not specified in the filter, then all completed to-dos will be removed
196 if the #HideCompletedTodos criteria is set.
197
198 @param timespan is an integer representing a time span in days.
199 @see completedTimeSpan().
200 */
201 void setCompletedTimeSpan(int timespan);
202
203 /**
204 Returns the completed time span for this filter.
205 @see setCompletedTimeSpan()
206 */
207 int completedTimeSpan() const;
208
209 /**
210 Compares this with @p filter for equality.
211
212 @param filter the CalFilter to compare.
213 */
214 bool operator==(const CalFilter &filter) const;
215
216private:
217 //@cond PRIVATE
218 Q_DISABLE_COPY(CalFilter)
219 class Private;
220 Private *const d;
221 //@endcond
222};
223
224}
225
226#endif
227