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 | |
67 | class KUrl; |
68 | |
69 | namespace KCal { |
70 | |
71 | /** List of dates */ |
72 | typedef SortableList<QDate> DateList; |
73 | /** List of times */ |
74 | typedef SortableList<KDateTime> DateTimeList; |
75 | class Event; |
76 | class Todo; |
77 | class Journal; |
78 | class 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 | */ |
102 | class 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.