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
This file is part of the API for handling calendar data and defines the Todo class.
This file is part of the API for handling calendar data and defines the Journal class.
This file is part of the API for handling calendar data and defines the Event class.
Criteria
Filtering Criteria.
Definition: calfilter.h:48
Provides a filter for calendars.
Definition: calfilter.h:42
Namespace for all KCalendarCore types.
Definition: alarm.h:36
This file is part of the KDE documentation.
Documentation copyright © 1996-2021 The KDE developers.
Generated on Sun Sep 26 2021 22:51:52 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.