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 | |
39 | namespace 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 | */ |
55 | class KCALCORE_EXPORT CalFilter |
56 | { |
57 | public: |
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 | |
216 | private: |
217 | //@cond PRIVATE |
218 | Q_DISABLE_COPY(CalFilter) |
219 | class Private; |
220 | Private *const d; |
221 | //@endcond |
222 | }; |
223 | |
224 | } |
225 | |
226 | #endif |
227 | |