1/*
2 This file is part of the kcal library.
3
4 Copyright (c) 2003 Cornelius Schumacher <schumacher@kde.org>
5
6 This library is free software; you can redistribute it and/or
7 modify it under the terms of the GNU Library General Public
8 License as published by the Free Software Foundation; either
9 version 2 of the License, or (at your option) any later version.
10
11 This library is distributed in the hope that it will be useful,
12 but WITHOUT ANY WARRANTY; without even the implied warranty of
13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14 Library General Public License for more details.
15
16 You should have received a copy of the GNU Library General Public License
17 along with this library; see the file COPYING.LIB. If not, write to
18 the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
19 Boston, MA 02110-1301, USA.
20*/
21/**
22 @file
23 This file is part of the API for handling calendar data and
24 defines the CalendarNull class.
25
26 @author Cornelius Schumacher \<schumacher@kde.org\>
27*/
28#ifndef KCAL_CALENDARNULL_H
29#define KCAL_CALENDARNULL_H
30
31#include "calendar.h"
32#include "kcal_export.h"
33
34namespace KCal {
35
36/**
37 @brief
38 Represents a null calendar class; that is, a calendar which contains
39 no information and provides no capabilities.
40
41 The null calendar can be passed to functions which need a calendar object
42 when there is no real calendar available yet.
43
44 CalendarNull can be used to implement the null object design pattern:
45 pass a CalendarNull object instead of passing a 0 pointer and checking
46 for 0 with each access.
47*/
48class KCAL_DEPRECATED_EXPORT CalendarNull : public Calendar
49{
50 public:
51 /**
52 Construct Calendar object using a time specification (time zone, etc.).
53 The time specification is used for creating or modifying incidences
54 in the Calendar. It is also used for viewing incidences (see
55 setViewTimeSpec()). The time specification does not alter existing
56 incidences.
57
58 @param timeSpec time specification
59 */
60 explicit CalendarNull( const KDateTime::Spec &timeSpec );
61
62 /**
63 Constructs a null calendar with a specified time zone @p timeZoneId.
64
65 @param timeZoneId is a string containing a time zone ID, which is
66 assumed to be valid. If no time zone is found, the viewing time
67 specification is set to local clock time.
68 @e Example: "Europe/Berlin"
69 */
70 explicit CalendarNull( const QString &timeZoneId );
71
72 /**
73 Destroys the null calendar.
74 */
75 ~CalendarNull();
76
77 /**
78 Returns a pointer to the CalendarNull object, of which there can
79 be only one. The object is constructed if necessary.
80 */
81 static CalendarNull *self();
82
83 /**
84 @copydoc
85 Calendar::close()
86 */
87 void close();
88
89 /**
90 @copydoc
91 Calendar::save()
92 */
93 bool save();
94
95 /**
96 @copydoc
97 Calendar::reload()
98 */
99 bool reload();
100
101 // Event Specific Methods //
102
103 /**
104 @copydoc
105 Calendar::addEvent()
106 */
107 bool addEvent( Event *event );
108
109 /**
110 @copydoc
111 Calendar::deleteEvent()
112 */
113 bool deleteEvent( Event *event );
114
115 /**
116 @copydoc
117 Calendar::deleteAllEvents()
118 */
119 void deleteAllEvents();
120
121 /**
122 @copydoc
123 Calendar::rawEvents(EventSortField, SortDirection)
124 */
125 Event::List rawEvents( EventSortField sortField,
126 SortDirection sortDirection );
127
128 /**
129 @copydoc
130 Calendar::rawEvents(const QDate &, const QDate &, const KDateTime::Spec &, bool)
131 */
132 Event::List rawEvents( const QDate &start, const QDate &end,
133 const KDateTime::Spec &timeSpec = KDateTime::Spec(),
134 bool inclusive = false );
135
136 /**
137 Returns an unfiltered list of all Events which occur on the given date.
138
139 @param date request unfiltered Event list for this QDate only.
140 @param timeSpec time zone etc. to interpret @p date, or the calendar's
141 default time spec if none is specified
142 @param sortField specifies the EventSortField.
143 @param sortDirection specifies the SortDirection.
144
145 @return the list of unfiltered Events occurring on the specified QDate.
146 */
147 Event::List rawEventsForDate( const QDate &date,
148 const KDateTime::Spec &timeSpec = KDateTime::Spec(),
149 EventSortField sortField = EventSortUnsorted,
150 SortDirection sortDirection = SortDirectionAscending );
151
152 /**
153 @copydoc
154 Calendar::rawEventsForDate(const KDateTime &)
155 */
156 Event::List rawEventsForDate( const KDateTime &dt );
157
158 /**
159 @copydoc
160 Calendar::event()
161 */
162 Event *event( const QString &uid );
163
164 // To-do Specific Methods //
165
166 /**
167 @copydoc
168 Calendar::addTodo()
169 */
170 bool addTodo( Todo *todo );
171
172 /**
173 @copydoc
174 Calendar::deleteTodo()
175 */
176 bool deleteTodo( Todo *todo );
177
178 /**
179 @copydoc
180 Calendar::deleteAllTodos()
181 */
182 void deleteAllTodos();
183
184 /**
185 @copydoc
186 Calendar::rawTodos()
187 */
188 Todo::List rawTodos( TodoSortField sortField,
189 SortDirection sortDirection );
190
191 /**
192 @copydoc
193 Calendar::rawTodosForDate()
194 */
195 Todo::List rawTodosForDate( const QDate &date );
196
197 /**
198 @copydoc
199 Calendar::todo()
200 */
201 Todo *todo( const QString &uid );
202
203 // Journal Specific Methods //
204
205 /**
206 @copydoc
207 Calendar::addJournal()
208 */
209 bool addJournal( Journal *journal );
210
211 /**
212 @copydoc
213 Calendar::deleteJournal()
214 */
215 bool deleteJournal( Journal *journal );
216
217 /**
218 @copydoc
219 Calendar::deleteAllJournals()
220 */
221 void deleteAllJournals();
222
223 /**
224 @copydoc
225 Calendar::rawJournals()
226 */
227 Journal::List rawJournals( JournalSortField sortField,
228 SortDirection sortDirection );
229
230 /**
231 @copydoc
232 Calendar::rawJournalsForDate()
233 */
234 Journal::List rawJournalsForDate( const QDate &date );
235
236 /**
237 @copydoc
238 Calendar::journal()
239 */
240 Journal *journal( const QString &uid );
241
242 // Alarm Specific Methods //
243
244 /**
245 @copydoc
246 Calendar::alarms()
247 */
248 Alarm::List alarms( const KDateTime &from, const KDateTime &to );
249
250 // Observer Specific Methods //
251
252 /**
253 @copydoc
254 Calendar::incidenceUpdated()
255 */
256 void incidenceUpdated( IncidenceBase *incidenceBase );
257
258 using QObject::event; // prevent warning about hidden virtual method
259
260 private:
261 //@cond PRIVATE
262 Q_DISABLE_COPY( CalendarNull )
263 class Private;
264 Private *const d;
265 //@endcond
266};
267
268}
269
270#endif
271