1 | /* |
2 | This file is part of the kcal library. |
3 | |
4 | Copyright (c) 2001-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 Attendee class. |
25 | |
26 | @author Cornelius Schumacher \<schumacher@kde.org\> |
27 | */ |
28 | |
29 | #ifndef KCAL_ATTENDEE_H |
30 | #define KCAL_ATTENDEE_H |
31 | |
32 | #include <QtCore/QString> |
33 | #include <QtCore/QStringList> |
34 | |
35 | #include "listbase.h" |
36 | #include "person.h" |
37 | #include "customproperties.h" |
38 | |
39 | namespace KCal { |
40 | |
41 | /** |
42 | @brief |
43 | Represents information related to an attendee of an Calendar Incidence, |
44 | typically a meeting or task (to-do). |
45 | |
46 | Attendees are people with a name and (optional) email address who are |
47 | invited to participate in some way in a meeting or task. This class |
48 | also tracks that status of the invitation: accepted; tentatively accepted; |
49 | declined; delegated to another person; in-progress; completed. |
50 | |
51 | Attendees may optionally be asked to @acronym RSVP ("Respond Please") to |
52 | the invitation. |
53 | |
54 | Note that each attendee be can optionally associated with a @acronym UID |
55 | (unique identifier) derived from a Calendar Incidence, Email Message, |
56 | or any other thing you want. |
57 | */ |
58 | class KCAL_DEPRECATED_EXPORT Attendee : private Person |
59 | { |
60 | public: |
61 | using Person::setEmail; |
62 | using Person::email; |
63 | using Person::setName; |
64 | using Person::name; |
65 | using Person::fullName; |
66 | |
67 | /** |
68 | The different types of participant status. |
69 | The meaning is specific to the incidence type in context. |
70 | */ |
71 | enum PartStat { |
72 | NeedsAction, /**< Event, to-do or journal needs action (default) */ |
73 | Accepted, /**< Event, to-do or journal accepted */ |
74 | Declined, /**< Event, to-do or journal declined */ |
75 | Tentative, /**< Event or to-do tentatively accepted */ |
76 | Delegated, /**< Event or to-do delegated */ |
77 | Completed, /**< To-do completed */ |
78 | InProcess, /**< To-do in process of being completed */ |
79 | None |
80 | }; |
81 | |
82 | /** |
83 | The different types of participation roles. |
84 | */ |
85 | enum Role { |
86 | ReqParticipant, /**< Participation is required (default) */ |
87 | OptParticipant, /**< Participation is optional */ |
88 | NonParticipant, /**< Non-Participant; copied for information purposes */ |
89 | Chair /**< Chairperson */ |
90 | }; |
91 | |
92 | /** |
93 | List of attendees. |
94 | */ |
95 | typedef ListBase<Attendee> List; |
96 | |
97 | /** |
98 | Constructs an attendee consisting of a Person name (@p name) and |
99 | email address (@p email); invitation status and #Role; |
100 | an optional @acronym RSVP flag and @acronym UID. |
101 | |
102 | @param name is person name of the attendee. |
103 | @param email is person email address of the attendee. |
104 | @param rsvp if true, the attendee is requested to reply to invitations. |
105 | @param status is the #PartStat status of the attendee. |
106 | @param role is the #Role of the attendee. |
107 | @param uid is the @acronym UID of the attendee. |
108 | */ |
109 | Attendee( const QString &name, const QString &email, |
110 | bool rsvp = false, PartStat status = None, |
111 | Role role = ReqParticipant, const QString &uid = QString() ); |
112 | |
113 | /** |
114 | Constructs an attendee by copying another attendee. |
115 | |
116 | @param attendee is the attendee to be copied. |
117 | */ |
118 | Attendee( const Attendee &attendee ); |
119 | |
120 | /** |
121 | Destroys the attendee. |
122 | */ |
123 | ~Attendee(); |
124 | |
125 | /** |
126 | Sets the Role of the attendee to @p role. |
127 | |
128 | @param role is the Role to use for the attendee. |
129 | |
130 | @see role() |
131 | */ |
132 | void setRole( Role role ); |
133 | |
134 | /** |
135 | Returns the Role of the attendee. |
136 | |
137 | @see setRole() |
138 | */ |
139 | Role role() const; |
140 | |
141 | /** |
142 | Returns the attendee Role as a text string. |
143 | |
144 | @see role(), roleName() |
145 | */ |
146 | QString roleStr() const; |
147 | |
148 | /** |
149 | Returns the specified #Role @p role as a text string. |
150 | |
151 | @param role is a #Role value. |
152 | |
153 | @see role(), roleStr() |
154 | */ |
155 | static QString roleName( Role role ); |
156 | |
157 | /** |
158 | Returns a list of strings representing each #Role. |
159 | */ |
160 | static QStringList roleList(); |
161 | |
162 | /** |
163 | Sets the @acronym UID of the attendee to @p uid. |
164 | |
165 | @param uid is the @acronym UID to use for the attendee. |
166 | |
167 | @see uid() |
168 | */ |
169 | void setUid ( const QString &uid ); |
170 | |
171 | /** |
172 | Returns the @acronym UID of the attendee. |
173 | |
174 | @see setUid() |
175 | */ |
176 | QString uid() const; |
177 | |
178 | /** |
179 | Sets the #PartStat of the attendee to @p status. |
180 | |
181 | @param status is the #PartStat to use for the attendee. |
182 | |
183 | @see status() |
184 | */ |
185 | void setStatus( PartStat status ); |
186 | |
187 | /** |
188 | Returns the #PartStat of the attendee. |
189 | |
190 | @see setStatus() |
191 | */ |
192 | PartStat status() const; |
193 | |
194 | /** |
195 | Returns the attendee #PartStat as a text string. |
196 | |
197 | @see status(), statusName() |
198 | */ |
199 | QString statusStr() const; |
200 | |
201 | /** |
202 | Returns the specified #PartStat @p status as a text string. |
203 | |
204 | @param status is a #PartStat value. |
205 | |
206 | @see status(), statusStr() |
207 | */ |
208 | static QString statusName( PartStat status ); |
209 | |
210 | /** |
211 | Returns a list of strings representing each #PartStat. |
212 | */ |
213 | static QStringList statusList(); |
214 | |
215 | /** |
216 | Sets the @acronym RSVP flag of the attendee to @p rsvp. |
217 | |
218 | @param rsvp if set (true), the attendee is requested to reply to |
219 | invitations. |
220 | |
221 | @see RSVP() |
222 | */ |
223 | void setRSVP( bool rsvp ); |
224 | |
225 | /** |
226 | Returns the attendee @acronym RSVP flag. |
227 | |
228 | @see setRSVP() |
229 | */ |
230 | bool RSVP() const; |
231 | |
232 | /** |
233 | Compares this with @p attendee for equality. |
234 | |
235 | @param attendee the attendee to compare. |
236 | */ |
237 | //KDE5: make const |
238 | bool operator==( const Attendee &attendee ); //krazy:exclude=operators |
239 | |
240 | /** |
241 | Sets the delegate. |
242 | @param delegate is a string containing a MAILTO URI of those delegated |
243 | to attend the meeting. |
244 | @see delegate(), setDelegator(). |
245 | */ |
246 | void setDelegate( const QString &delegate ); |
247 | |
248 | /** |
249 | Returns the delegate. |
250 | @see setDelegate(). |
251 | */ |
252 | QString delegate() const; |
253 | |
254 | /** |
255 | Sets the delegator. |
256 | @param delegator is a string containing a MAILTO URI of those who |
257 | have delegated their meeting attendance. |
258 | @see delegator(), setDelegate(). |
259 | */ |
260 | void setDelegator( const QString &delegator ); |
261 | |
262 | /** |
263 | Returns the delegator. |
264 | @see setDelegator(). |
265 | */ |
266 | QString delegator() const; |
267 | |
268 | /** |
269 | Adds a custom property. If the property already exists it will be overwritten. |
270 | @param xname is the name of the property. |
271 | @param xvalue is its value. |
272 | @since 4.4 |
273 | */ |
274 | void setCustomProperty( const QByteArray &xname, const QString &xvalue ); |
275 | |
276 | /** |
277 | Returns a reference to the CustomProperties object |
278 | @since 4.4 |
279 | */ |
280 | CustomProperties &customProperties(); |
281 | |
282 | /** |
283 | Returns a const reference to the CustomProperties object |
284 | @since 4.4 |
285 | */ |
286 | const CustomProperties &customProperties() const; |
287 | |
288 | /** |
289 | Sets this attendee equal to @p attendee. |
290 | |
291 | @param attendee is the attendee to copy. |
292 | */ |
293 | Attendee &operator=( const Attendee &attendee ); |
294 | |
295 | private: |
296 | //@cond PRIVATE |
297 | class Private; |
298 | Private *const d; |
299 | //@endcond |
300 | }; |
301 | |
302 | } |
303 | |
304 | #endif |
305 | |