1/*
2 This file is part of the kcal library.
3
4 Copyright (c) 1998 Preston Brown <pbrown@kde.org>
5 Copyright (c) 2001,2003 Cornelius Schumacher <schumacher@kde.org>
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 CalendarLocal class.
26
27 @author Preston Brown \<pbrown@kde.org\>
28 @author Cornelius Schumacher \<schumacher@kde.org\>
29 */
30#ifndef KCAL_CALENDARLOCAL_H
31#define KCAL_CALENDARLOCAL_H
32
33#include "calendar.h"
34
35namespace KCal {
36
37class CalFormat;
38
39/**
40 @brief
41 This class provides a calendar stored as a local file.
42*/
43class KCAL_DEPRECATED_EXPORT CalendarLocal : public Calendar
44{
45 public:
46 /**
47 @copydoc
48 Calendar::Calendar(const KDateTime::Spec &)
49 */
50 explicit CalendarLocal( const KDateTime::Spec &timeSpec );
51
52 /**
53 @copydoc
54 Calendar::Calendar(const QString &)
55 */
56 explicit CalendarLocal( const QString &timeZoneId );
57
58 /**
59 @copydoc
60 Calendar::~Calendar()
61 */
62 ~CalendarLocal();
63
64 /**
65 Loads a calendar on disk in vCalendar or iCalendar format into the
66 current calendar. Incidences already present are preserved. If an
67 incidence of the file to be loaded has the same unique id as an
68 incidence already present the new incidence is ignored.
69
70 To load a CalendarLocal object from a file without preserving existing
71 incidences call close() before load().
72
73 @param fileName the name of the calendar on disk.
74 @param format the format to use. If 0, an attempt is made to load
75 iCalendar format, and if that fails tries vCalendar format.
76 @return true, if successful, false on error.
77
78 @see save( const QString &, CalFormat *)
79 */
80 bool load( const QString &fileName, CalFormat *format = 0 );
81
82 /**
83 Reloads the contents of the storage into memory. The associated file name
84 must be known, in other words a previous load() must have been executed.
85 @return true if the reload was successful; false otherwise.
86 */
87 bool reload();
88
89 /**
90 Writes the calendar to disk. The associated file name and format must
91 be known, in other words a previous load() must have been executed.
92
93 @return true if the save was successful; false otherwise.
94 @see save(const QString &, CalFormat *)
95 */
96 bool save();
97
98 /**
99 Writes the calendar to disk in the specified @p format.
100 CalendarLocal takes ownership of the CalFormat object.
101
102 @param fileName the name of the file
103 @param format the format to use. If 0, iCalendar will be used.
104 @return true if the save was successful; false otherwise.
105
106 @see save(), load( const QString &, CalFormat *)
107 */
108 bool save( const QString &fileName, CalFormat *format = 0 );
109
110 /**
111 Clears out the current calendar, freeing all used memory etc. etc.
112 */
113 void close();
114
115 // Event Specific Methods //
116
117 /**
118 @copydoc
119 Calendar::addEvent()
120 */
121 bool addEvent( Event *event );
122
123 /**
124 @copydoc
125 Calendar::deleteEvent()
126 */
127 bool deleteEvent( Event *event );
128
129 /**
130 @copydoc
131 Calendar::deleteAllEvents()
132 */
133 void deleteAllEvents();
134
135 /**
136 @copydoc
137 Calendar::rawEvents(EventSortField, SortDirection)
138 */
139 Event::List rawEvents(
140 EventSortField sortField = EventSortUnsorted,
141 SortDirection sortDirection = SortDirectionAscending );
142
143 /**
144 @copydoc
145 Calendar::rawEvents(const QDate &, const QDate &, const KDateTime::Spec &, bool)
146 */
147 Event::List rawEvents( const QDate &start, const QDate &end,
148 const KDateTime::Spec &timeSpec = KDateTime::Spec(),
149 bool inclusive = false );
150
151 /**
152 Returns an unfiltered list of all Events which occur on the given date.
153
154 @param date request unfiltered Event list for this QDate only.
155 @param timeSpec time zone etc. to interpret @p date, or the calendar's
156 default time spec if none is specified
157 @param sortField specifies the EventSortField.
158 @param sortDirection specifies the SortDirection.
159
160 @return the list of unfiltered Events occurring on the specified QDate.
161 */
162 Event::List rawEventsForDate(
163 const QDate &date, const KDateTime::Spec &timeSpec = KDateTime::Spec(),
164 EventSortField sortField = EventSortUnsorted,
165 SortDirection sortDirection = SortDirectionAscending );
166
167 /**
168 @copydoc
169 Calendar::rawEventsForDate(const KDateTime &)
170 */
171 Event::List rawEventsForDate( const KDateTime &dt );
172
173 /**
174 @copydoc
175 Calendar::event()
176 */
177 Event *event( const QString &uid );
178
179 // To-do Specific Methods //
180
181 /**
182 @copydoc
183 Calendar::addTodo()
184 */
185 bool addTodo( Todo *todo );
186
187 /**
188 @copydoc
189 Calendar::deleteTodo()
190 */
191 bool deleteTodo( Todo *todo );
192
193 /**
194 @copydoc
195 Calendar::deleteAllTodos()
196 */
197 void deleteAllTodos();
198
199 /**
200 @copydoc
201 Calendar::rawTodos()
202 */
203 Todo::List rawTodos(
204 TodoSortField sortField = TodoSortUnsorted,
205 SortDirection sortDirection = SortDirectionAscending );
206
207 /**
208 @copydoc
209 Calendar::rawTodosForDate()
210 */
211 Todo::List rawTodosForDate( const QDate &date );
212
213 /**
214 @copydoc
215 Calendar::todo()
216 */
217 Todo *todo( const QString &uid );
218
219 // Journal Specific Methods //
220
221 /**
222 @copydoc
223 Calendar::addJournal()
224 */
225 bool addJournal( Journal *journal );
226
227 /**
228 @copydoc
229 Calendar::deleteJournal()
230 */
231 bool deleteJournal( Journal *journal );
232
233 /**
234 @copydoc
235 Calendar::deleteAllJournals()
236 */
237 void deleteAllJournals();
238
239 /**
240 @copydoc
241 Calendar::rawJournals()
242 */
243 Journal::List rawJournals(
244 JournalSortField sortField = JournalSortUnsorted,
245 SortDirection sortDirection = SortDirectionAscending );
246
247 /**
248 @copydoc
249 Calendar::rawJournalsForDate()
250 */
251 Journal::List rawJournalsForDate( const QDate &date );
252
253 /**
254 @copydoc
255 Calendar::journal()
256 */
257 Journal *journal( const QString &uid );
258
259 // Alarm Specific Methods //
260
261 /**
262 @copydoc
263 Calendar::alarms()
264 */
265 Alarm::List alarms( const KDateTime &from, const KDateTime &to );
266
267 /**
268 Return a list of Alarms that occur before the specified timestamp.
269
270 @param to is the ending timestamp.
271 @return the list of Alarms occurring before the specified KDateTime.
272 */
273 Alarm::List alarmsTo( const KDateTime &to );
274
275 /**
276 Notify the IncidenceBase::Observer that the incidence has been updated.
277
278 @param incidenceBase is a pointer to the updated IncidenceBase.
279 */
280 void incidenceUpdated( IncidenceBase *incidenceBase );
281
282 using QObject::event; // prevent warning about hidden virtual method
283
284 private:
285 //@cond PRIVATE
286 Q_DISABLE_COPY( CalendarLocal )
287 class Private;
288 Private *const d;
289 //@endcond
290};
291
292}
293
294#endif
295