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 | |
41 | namespace 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 | */ |
57 | class 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 | |