1/*
2 This file is part of the kcal 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 KCAL_CALFILTER_H
32#define KCAL_CALFILTER_H
33
34#include <QtCore/QString>
35
36#include "kcal_export.h"
37#include "event.h"
38#include "todo.h"
39#include "journal.h"
40
41namespace KCal {
42
43/**
44 @brief
45 Provides a filter for calendars.
46
47 This class provides a means for filtering calendar incidences by
48 a list of email addresses, a list of categories, or other #Criteria.
49
50 The following #Criteria are available:
51 - remove recurring Incidences
52 - keep Incidences with a matching category (see setCategoryList())
53 - remove completed To-dos (see setCompletedTimeSpan())
54 - remove inactive To-dos
55 - remove To-dos without a matching attendee (see setEmailList())
56*/
57class KCAL_DEPRECATED_EXPORT CalFilter
58{
59 public:
60 /**
61 Filtering Criteria.
62 */
63 enum Criteria {
64 HideRecurring = 1, /**< Remove incidences that recur */
65 HideCompletedTodos = 2,/**< Remove completed to-dos */
66 ShowCategories = 4, /**< Show incidences with at least one matching category */
67 HideInactiveTodos = 8, /**< Remove to-dos that haven't started yet */
68 HideNoMatchingAttendeeTodos = 16 /**< Remove to-dos without a matching attendee */
69 };
70
71 /**
72 Constructs an empty filter -- a filter without a name or criteria.
73 */
74 CalFilter();
75
76 /**
77 Constructs a filter with @p name.
78
79 @param name is the name of this filter.
80 */
81 explicit CalFilter( const QString &name );
82
83 /**
84 Destroys this filter.
85 */
86 ~CalFilter();
87
88 /**
89 Sets the filter name.
90
91 @param name is the name of this filter.
92 @see name().
93 */
94 void setName( const QString &name );
95
96 /**
97 Returns the filter name.
98 @see setName().
99 */
100 QString name() const;
101
102 /**
103 Sets the criteria which must be fulfilled for an Incidence to pass
104 the filter.
105
106 @param criteria is a combination of #Criteria.
107 @see criteria().
108 */
109 void setCriteria( int criteria );
110
111 /**
112 Returns the inclusive filter criteria.
113 @see setCriteria().
114 */
115 int criteria() const;
116
117 /**
118 Applies the filter to a list of Events. All events not matching the
119 filter criteria are removed from the list.
120
121 @param eventList is a list of Events to filter.
122 */
123 void apply( Event::List *eventList ) const;
124
125 /**
126 Applies the filter to a list of To-dos. All to-dos not matching the
127 filter criterias are removed from the list.
128
129 @param todoList is a list of To-dos to filter.
130 */
131 void apply( Todo::List *todoList ) const;
132
133 /**
134 Applies the filter to a list of Journals. All journals not matching the
135 filter criterias are removed from the list.
136
137 @param journalList is a list of Journals to filter.
138 */
139 void apply( Journal::List *journalList ) const;
140
141 /**
142 Applies the filter criteria to the specified Incidence.
143
144 @param incidence is the Incidence to filter.
145 @return true if the Incidence passes the criteria; false otherwise.
146 */
147 bool filterIncidence( Incidence *incidence ) const;
148
149 /**
150 Enables or disables the filter.
151
152 @param enabled is true if the filter is to be enabled; false otherwise.
153 @see isEnabled().
154 */
155 void setEnabled( bool enabled );
156
157 /**
158 Returns whether the filter is enabled or not.
159 @see setEnabled().
160 */
161 bool isEnabled() const;
162
163 /**
164 Sets the list of categories to be considered when filtering incidences
165 according to the #ShowCategories criteria.
166
167 @param categoryList is a QStringList of categories.
168 @see categoryList().
169 */
170 void setCategoryList( const QStringList &categoryList );
171
172 /**
173 Returns the category list for this filter.
174 @see setCategoryList().
175 */
176 QStringList categoryList() const;
177
178 /**
179 Sets the list of email addresses to be considered when filtering
180 incidences according ot the #HideNoMatchingAttendeeTodos criteria.
181
182 @param emailList is a QStringList of email addresses.
183 @see emailList().
184 */
185 void setEmailList( const QStringList &emailList );
186
187 /**
188 Returns the email list for this filter.
189 @see setEmailList().
190 */
191 QStringList emailList() const;
192
193 /**
194 Sets the number of days for the #HideCompletedTodos criteria.
195 If a to-do has been completed within the recent @p timespan days,
196 then that to-do will be removed during filtering. If a time span is
197 not specified in the filter, then all completed to-dos will be removed
198 if the #HideCompletedTodos criteria is set.
199
200 @param timespan is an integer representing a time span in days.
201 @see completedTimeSpan().
202 */
203 void setCompletedTimeSpan( int timespan );
204
205 /**
206 Returns the completed time span for this filter.
207 @see setCompletedTimeSpan()
208 */
209 int completedTimeSpan() const;
210
211 /**
212 Compares this with @p filter for equality.
213
214 @param filter the CalFilter to compare.
215 */
216 //KDE5: make const
217 bool operator==( const CalFilter &filter ); //krazy:exclude=operators
218
219 private:
220 //@cond PRIVATE
221 Q_DISABLE_COPY( CalFilter )
222 class Private;
223 Private *const d;
224 //@endcond
225};
226
227}
228
229#endif
230