Warning: That file was not part of the compilation database. It may have many parsing errors.

1/*
2 This file is part of the kcal library.
3
4 Copyright (c) 2001-2003 Cornelius Schumacher <schumacher@kde.org>
5 Copyright (c) 2003-2004 Reinhold Kainhofer <reinhold@kainhofer.com>
6 Copyright (c) 2005 Rafal Rzepecki <divide@users.sourceforge.net>
7
8 This library is free software; you can redistribute it and/or
9 modify it under the terms of the GNU Library General Public
10 License as published by the Free Software Foundation; either
11 version 2 of the License, or (at your option) any later version.
12
13 This library is distributed in the hope that it will be useful,
14 but WITHOUT ANY WARRANTY; without even the implied warranty of
15 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
16 Library General Public License for more details.
17
18 You should have received a copy of the GNU Library General Public License
19 along with this library; see the file COPYING.LIB. If not, write to
20 the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
21 Boston, MA 02110-1301, USA.
22*/
23/**
24 @file
25 This file is part of the API for handling calendar data and
26 defines the IncidenceBase class.
27
28 @author Cornelius Schumacher \<schumacher@kde.org\>
29 @author Reinhold Kainhofer \<reinhold@kainhofer.com\>
30 @author Rafal Rzepecki \<divide@users.sourceforge.net\>
31
32 @glossary @anchor incidence @b incidence:
33 General term for a calendar component.
34 Examples are events, to-dos, and journals.
35
36 @glossary @anchor event @b event:
37 An @ref incidence that has a start and end time, typically representing some
38 occurrence of social or personal importance. May be recurring.
39 Examples are appointments, meetings, or holidays.
40
41 @glossary @anchor to-do @b to-do:
42 An @ref incidence that has an optional start time and an optional due time
43 typically representing some undertaking to be performed. May be recurring.
44 Examples are "fix the bug" or "pay the bills".
45
46 @glossary @anchor todo @b todo:
47 See @ref to-do.
48
49 @glossary @anchor journal @b journal:
50 An @ref incidence with a start date that represents a diary or daily record
51 of one's activities. May @b not be recurring.
52*/
53
54#ifndef KCAL_INCIDENCEBASE_H
55#define KCAL_INCIDENCEBASE_H
56
57#include "attendee.h"
58#include "customproperties.h"
59#include "duration.h"
60#include "sortablelist.h"
61
62#include <kdatetime.h>
63
64#include <QtCore/QStringList>
65#include <QtCore/QByteArray>
66
67class KUrl;
68
69namespace KCal {
70
71/** List of dates */
72typedef SortableList<QDate> DateList;
73/** List of times */
74typedef SortableList<KDateTime> DateTimeList;
75class Event;
76class Todo;
77class Journal;
78class FreeBusy;
79
80/**
81 @brief
82 An abstract class that provides a common base for all calendar incidence
83 classes.
84
85 define: organizer (person)
86 define: uid (same as the attendee uid?)
87
88 Several properties are not allowed for VFREEBUSY objects (see rfc:2445),
89 so they are not in IncidenceBase. The hierarchy is:
90
91 IncidenceBase
92 + FreeBusy
93 + Incidence
94 + Event
95 + Todo
96 + Journal
97
98 So IncidenceBase contains all properties that are common to all classes,
99 and Incidence contains all additional properties that are common to
100 Events, Todos and Journals, but are not allowed for FreeBusy entries.
101*/
102class KCAL_DEPRECATED_EXPORT IncidenceBase : public CustomProperties
103{
104 public:
105 /**
106 This class provides the interface for a visitor of calendar components.
107 It serves as base class for concrete visitors, which implement certain
108 actions on calendar components. It allows to add functions, which operate
109 on the concrete types of calendar components, without changing the
110 calendar component classes.
111 */
112 class KCAL_DEPRECATED_EXPORT Visitor //krazy:exclude=dpointer
113 {
114 public:
115 /** Destruct Incidence::Visitor */
116 virtual ~Visitor() {}
117
118 /**
119 Reimplement this function in your concrete subclass of
120 IncidenceBase::Visitor to perform actions on an Event object.
121 @param event is a pointer to a valid Event object.
122 */
123 virtual bool visit( Event *event );
124
125 /**
126 Reimplement this function in your concrete subclass of
127 IncidenceBase::Visitor to perform actions on a Todo object.
128 @param todo is a pointer to a valid Todo object.
129 */
130 virtual bool visit( Todo *todo );
131
132 /**
133 Reimplement this function in your concrete subclass of
134 IncidenceBase::Visitor to perform actions on an Journal object.
135 @param journal is a pointer to a valid Journal object.
136 */
137 virtual bool visit( Journal *journal );
138
139 /**
140 Reimplement this function in your concrete subclass of
141 IncidenceBase::Visitor to perform actions on a FreeBusy object.
142 @param freebusy is a pointer to a valid FreeBusy object.
143 */
144 virtual bool visit( FreeBusy *freebusy );
145
146 protected:
147 /**
148 Constructor is protected to prevent direct creation of visitor
149 base class.
150 */
151 Visitor() {}
152 };
153
154 /**
155 The IncidenceObserver class.
156 */
157 class IncidenceObserver
158 {
159 public:
160
161 /**
162 Destroys the IncidenceObserver.
163 */
164 virtual ~IncidenceObserver() {}
165
166 /**
167 The IncidenceObserver interface.
168
169 @param incidenceBase is a pointer to an IncidenceBase object.
170 */
171 virtual void incidenceUpdated( IncidenceBase *incidenceBase ) = 0;
172 };
173
174 /**
175 Constructs an empty IncidenceBase.
176 */
177 IncidenceBase();
178
179 /**
180 Constructs an IncidenceBase as a copy of another IncidenceBase object.
181
182 @param ib is the IncidenceBase to copy.
183 */
184
185 IncidenceBase( const IncidenceBase &ib );
186
187 /**
188 Destroys the IncidenceBase.
189 */
190 virtual ~IncidenceBase();
191
192 /**
193 Assignment operator.
194
195 @warning Not polymorphic. Use AssignmentVisitor for correct
196 assignment of an instance of type IncidenceBase to another
197 instance of type IncidenceBase.
198
199 @param other is the IncidenceBase to assign.
200
201 @see AssignmentVisitor
202 */
203 // KDE5: make protected to prevent accidental usage
204 IncidenceBase &operator=( const IncidenceBase &other );
205
206 /**
207 Compares this with IncidenceBase @p ib for equality.
208
209 @warning Not polymorphic. Use ComparisonVisitor for correct
210 comparison of two instances of type IncidenceBase.
211
212 @param ib is the IncidenceBase to compare.
213
214 @see ComparisonVisitor
215 */
216 // KDE5: make protected to prevent accidental usage
217 bool operator==( const IncidenceBase &ib ) const;
218
219 /**
220 Accept IncidenceVisitor. A class taking part in the visitor mechanism
221 has to provide this implementation:
222 <pre>
223 bool accept(Visitor &v) { return v.visit(this); }
224 </pre>
225
226 @param v is a reference to a Visitor object.
227 */
228 virtual bool accept( Visitor &v )
229 {
230 Q_UNUSED( v );
231 return false;
232 }
233
234 /**
235 Prints the type of Incidence as a string.
236 */
237 virtual QByteArray type() const = 0;
238
239 /**
240 Returns the type of Incidence as a translated string.
241 */
242 //KDE5: virtual QString typeStr() const = 0;
243
244 /**
245 Sets the unique id for the incidence to @p uid.
246
247 @param uid is the string containing the incidence @ref uid.
248
249 @see uid()
250 */
251 void setUid( const QString &uid );
252
253 /**
254 Returns the unique id (@ref uid) for the incidence.
255
256 @see setUid()
257 */
258 QString uid() const;
259
260 /**
261 Returns the uri for the incidence, of form urn:x-ical:\<uid\>
262 */
263 KUrl uri() const;
264
265 /**
266 Sets the time the incidence was last modified to @p lm.
267 It is stored as a UTC date/time.
268
269 @param lm is the KDateTime when the incidence was last modified.
270
271 @see lastModified()
272 */
273 void setLastModified( const KDateTime &lm );
274
275 /**
276 Returns the time the incidence was last modified.
277
278 @see setLastModified()
279 */
280 KDateTime lastModified() const;
281
282 /**
283 Sets the organizer for the incidence.
284
285 @param organizer is a Person to use as the incidence @ref organizer.
286 @see organizer(), setOrganizer(const QString &)
287 */
288 void setOrganizer( const Person &organizer );
289
290 /**
291 Sets the incidence organizer to any string @p organizer.
292
293 @param organizer is a string to use as the incidence @ref organizer.
294 @see organizer(), setOrganizer(const Person &)
295 */
296 void setOrganizer( const QString &organizer );
297
298 /**
299 Returns the Person associated with this incidence.
300
301 @see setOrganizer(const QString &), setOrganizer(const Person &)
302 */
303 Person organizer() const;
304
305 /**
306 Sets readonly status.
307
308 @param readOnly if set, the incidence is read-only; else the incidence
309 can be modified.
310 @see isReadOnly().
311 */
312 virtual void setReadOnly( bool readOnly );
313
314 /**
315 Returns true the object is read-only; false otherwise.
316 @see setReadOnly()
317 */
318 bool isReadOnly() const { return mReadOnly; }
319
320 /**
321 Sets the incidence's starting date/time with a KDateTime.
322 The incidence's all-day status is set according to whether @p dtStart
323 is a date/time (not all-day) or date-only (all-day).
324
325 @param dtStart is the incidence start date/time.
326 @see dtStart().
327 */
328 virtual void setDtStart( const KDateTime &dtStart );
329
330 /**
331 Returns an incidence's starting date/time as a KDateTime.
332 @see setDtStart().
333 */
334 virtual KDateTime dtStart() const;
335
336 /**
337 Returns an incidence's starting time as a string formatted according
338 to the user's locale settings.
339
340 @param shortfmt If set to true, use short date format, if set to false use
341 long format.
342 @param spec If set, return the time in the given spec, else use the
343 incidence's current spec.
344
345 @deprecated use IncidenceFormatter::timeToString()
346 */
347 virtual KCAL_DEPRECATED QString dtStartTimeStr(
348 bool shortfmt = true, const KDateTime::Spec &spec = KDateTime::Spec() ) const;
349
350 /**
351 Returns an incidence's starting date as a string formatted according
352 to the user's locale settings.
353
354 @param shortfmt If set to true, use short date format, if set to false use
355 long format.
356 @param spec If set, return the date in the given spec, else use the
357 incidence's current spec.
358
359 @deprecated use IncidenceFormatter::dateToString()
360 */
361 virtual KCAL_DEPRECATED QString dtStartDateStr(
362 bool shortfmt = true, const KDateTime::Spec &spec = KDateTime::Spec() ) const;
363
364 /**
365 Returns an incidence's starting date and time as a string formatted
366 according to the user's locale settings.
367
368 @param shortfmt If set to true, use short date format, if set to false use
369 long format.
370 @param spec If set, return the date and time in the given spec, else use
371 the incidence's current spec.
372
373 @deprecated use IncidenceFormatter::dateTimeToString()
374 */
375 virtual KCAL_DEPRECATED QString dtStartStr(
376 bool shortfmt = true, const KDateTime::Spec &spec = KDateTime::Spec() ) const;
377
378 /**
379 Sets the incidence duration.
380
381 @param duration the incidence duration
382
383 @see duration()
384 */
385 virtual void setDuration( const Duration &duration );
386
387 /**
388 Returns the length of the incidence duration.
389
390 @see setDuration()
391 */
392 Duration duration() const;
393
394 /**
395 Sets if the incidence has a duration.
396
397 @param hasDuration true if the incidence has a duration; false otherwise.
398
399 @see hasDuration()
400 */
401 void setHasDuration( bool hasDuration );
402
403 /**
404 Returns true if the incidence has a duration; false otherwise.
405
406 @see setHasDuration()
407 */
408 bool hasDuration() const;
409
410 /**
411 Returns true or false depending on whether the incidence is all-day.
412 i.e. has a date but no time attached to it.
413
414 @see setAllDay()
415 */
416 bool allDay() const;
417
418 /**
419 Sets whether the incidence is all-day, i.e. has a date but no time
420 attached to it.
421
422 @param allDay sets whether the incidence is all-day.
423
424 @see allDay()
425 */
426 void setAllDay( bool allDay );
427
428 /**
429 Shift the times of the incidence so that they appear at the same clock
430 time as before but in a new time zone. The shift is done from a viewing
431 time zone rather than from the actual incidence time zone.
432
433 For example, shifting an incidence whose start time is 09:00
434 America/New York, using an old viewing time zone (@p oldSpec)
435 of Europe/London, to a new time zone (@p newSpec) of Europe/Paris,
436 will result in the time being shifted from 14:00 (which is the London
437 time of the incidence start) to 14:00 Paris time.
438
439 @param oldSpec the time specification which provides the clock times
440 @param newSpec the new time specification
441 */
442 virtual void shiftTimes( const KDateTime::Spec &oldSpec,
443 const KDateTime::Spec &newSpec );
444
445 /**
446 Adds a comment to thieincidence. Does not add a linefeed character; simply
447 appends the text as specified.
448
449 @param comment is the QString containing the comment to add.
450 @see removeComment().
451 */
452 void addComment( const QString &comment );
453
454 /**
455 Removes a comment from the incidence. Removes the first comment whose
456 string is an exact match for the specified string in @p comment.
457
458 @param comment is the QString containing the comment to remove.
459 @return true if match found, false otherwise.
460 @see addComment().
461 */
462 bool removeComment( const QString &comment );
463
464 /**
465 Deletes all incidence comments.
466 */
467 void clearComments();
468
469 /**
470 Returns all incidence comments as a list of strings.
471 */
472 QStringList comments() const;
473
474 /**
475 Add Attendee to this incidence. IncidenceBase takes ownership of the
476 Attendee object.
477
478 @param attendee a pointer to the attendee to add
479 @param doUpdate If true the Observers are notified, if false they are not.
480 */
481 void addAttendee( Attendee *attendee, bool doUpdate = true );
482
483 /**
484 Removes all attendees from the incidence.
485 */
486 void clearAttendees();
487
488 /**
489 Returns a list of incidence attendees.
490 */
491 const Attendee::List &attendees() const;
492
493 /**
494 Returns the number of incidence attendees.
495 */
496 int attendeeCount() const;
497
498 /**
499 Returns the attendee with the specified email address.
500
501 @param email is a QString containing an email address of the
502 form "FirstName LastName <emailaddress>".
503 @see attendeeByMails(), attendeesByUid().
504 */
505 Attendee *attendeeByMail( const QString &email ) const;
506
507 /**
508 Returns the first incidence attendee with one of the specified
509 email addresses.
510
511 @param emails is a list of QStrings containing email addresses of the
512 form "FirstName LastName <emailaddress>".
513 @param email is a QString containing a single email address to search
514 in addition to the list specified in @p emails.
515 @see attendeeByMail(), attendeesByUid().
516 */
517 Attendee *attendeeByMails( const QStringList &emails,
518 const QString &email = QString() ) const;
519
520 /**
521 Returns the incidence attendee with the specified attendee @acronym UID.
522
523 @param uid is a QString containing an attendee @acronym UID.
524 @see attendeeByMail(), attendeeByMails().
525 */
526 Attendee *attendeeByUid( const QString &uid ) const;
527
528 /**
529 Register observer. The observer is notified when the observed object
530 changes.
531
532 @param observer is a pointer to an IncidenceObserver object that will be
533 watching this incidence.
534 @see unRegisterObserver()
535 */
536 void registerObserver( IncidenceObserver *observer );
537
538 /**
539 Unregister observer. It isn't notified anymore about changes.
540
541 @param observer is a pointer to an IncidenceObserver object that will be
542 watching this incidence.
543 @see registerObserver().
544 */
545 void unRegisterObserver( IncidenceObserver *observer );
546
547 /**
548 Call this to notify the observers after the IncidenceBase object has
549 changed.
550 */
551 void updated();
552
553 /**
554 Call this when a group of updates is going to be made. This suppresses
555 change notifications until endUpdates() is called, at which point
556 updated() will automatically be called.
557 */
558 void startUpdates();
559
560 /**
561 Call this when a group of updates is complete, to notify observers that
562 the instance has changed. This should be called in conjunction with
563 startUpdates().
564 */
565 void endUpdates();
566
567 protected:
568 /**
569 @copydoc
570 CustomProperties::customPropertyUpdated()
571 */
572 virtual void customPropertyUpdated();
573
574 /**
575 Identifies a read-only incidence.
576 */
577 bool mReadOnly;
578
579 private:
580 //@cond PRIVATE
581 class Private;
582 Private *const d;
583 //@endcond
584};
585
586}
587
588#endif
589

Warning: That file was not part of the compilation database. It may have many parsing errors.