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 <[email protected]>
5  SPDX-FileCopyrightText: 2003-2004 Reinhold Kainhofer <[email protected]>
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 <[email protected]>
15  @author Reinhold Kainhofer <[email protected]>
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 
26 namespace 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 */
42 class KCALENDARCORE_EXPORT CalFilter
43 {
44 public:
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 
203 private:
204  //@cond PRIVATE
205  Q_DISABLE_COPY(CalFilter)
206  class Private;
207  Private *const d;
208  //@endcond
209 };
210 
211 }
212 
213 #endif
Criteria
Filtering Criteria.
Definition: calfilter.h:48
Namespace for all KCalendarCore types.
Definition: alarm.h:36
Provides a filter for calendars.
Definition: calfilter.h:42
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Sun Oct 1 2023 03:58:00 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.