1 | /* |
2 | This file is part of the kcal library. |
3 | |
4 | Copyright (c) 2001-2003 Cornelius Schumacher <schumacher@kde.org> |
5 | Copyright (c) 2004 Reinhold Kainhofer <reinhold@kainhofer.com> |
6 | Copyright (c) 2009-2010 Klarälvdalens Datakonsult AB, a KDAB Group company <info@kdab.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 provides |
26 | static functions for formatting Incidences for various purposes. |
27 | |
28 | @author Cornelius Schumacher \<schumacher@kde.org\> |
29 | @author Reinhold Kainhofer \<reinhold@kainhofer.com\> |
30 | @author Allen Winter \<allen@kdab.com\> |
31 | */ |
32 | #ifndef KCAL_INCIDENCEFORMATTER_H |
33 | #define KCAL_INCIDENCEFORMATTER_H |
34 | |
35 | #include "kcal_export.h" |
36 | #include <KDE/KDateTime> |
37 | #include <QtCore/QString> |
38 | |
39 | namespace KCal { |
40 | class Calendar; |
41 | class Incidence; |
42 | class IncidenceBase; |
43 | |
44 | class KCAL_DEPRECATED_EXPORT InvitationFormatterHelper |
45 | { |
46 | public: |
47 | InvitationFormatterHelper() : d( 0 ) {} |
48 | virtual ~InvitationFormatterHelper(){} |
49 | virtual QString generateLinkURL( const QString &id ); |
50 | virtual QString makeLink( const QString &id, const QString &text ); |
51 | virtual Calendar *calendar() const; |
52 | |
53 | private: |
54 | //@cond PRIVATE |
55 | Q_DISABLE_COPY( InvitationFormatterHelper ) |
56 | class Private; |
57 | Private *const d; |
58 | //@endcond |
59 | }; |
60 | |
61 | /** |
62 | @brief |
63 | Provides methods to format Incidences in various ways for display purposes. |
64 | |
65 | Helpers that provides several static methods to format an Incidence in |
66 | different ways: like an HTML representation for KMail, a representation |
67 | for tool tips, or a representation for a viewer widget. |
68 | |
69 | */ |
70 | namespace IncidenceFormatter |
71 | { |
72 | /** |
73 | Create a QString representation of an Incidence in a nice format |
74 | suitable for using in a tooltip. |
75 | @param incidence is a pointer to the Incidence to be formatted. |
76 | @param date is the QDate for which the toolTip should be computed; used |
77 | mainly for recurring incidences. |
78 | @param richText if yes, the QString will be created as RichText. |
79 | @param spec is an optional time specification which, when specified, |
80 | will shift the Incidence times to different timezones. |
81 | @since 4.4 |
82 | */ |
83 | KCAL_DEPRECATED_EXPORT QString toolTipStr( Calendar *calendar, |
84 | IncidenceBase *incidence, |
85 | const QDate &date=QDate(), |
86 | bool richText=true, |
87 | KDateTime::Spec spec=KDateTime::Spec() ); |
88 | |
89 | /** |
90 | Create a QString representation of an Incidence in a nice format |
91 | suitable for using in a tooltip. |
92 | @param sourceName where the incidence is from (e.g. resource name) |
93 | @param incidence is a pointer to the Incidence to be formatted. |
94 | @param date is the QDate for which the toolTip should be computed; used |
95 | mainly for recurring incidences. |
96 | @param richText if yes, the QString will be created as RichText. |
97 | @param spec is an optional time specification which, when specified, |
98 | will shift the Incidence times to different timezones. |
99 | @since 4.5 |
100 | */ |
101 | KCAL_DEPRECATED_EXPORT QString toolTipStr( const QString &sourceName, |
102 | IncidenceBase *incidence, |
103 | const QDate &date=QDate(), |
104 | bool richText=true, |
105 | KDateTime::Spec spec=KDateTime::Spec() ); |
106 | |
107 | /** |
108 | Create a QString representation of an Incidence in a nice format |
109 | suitable for using in a tooltip. |
110 | @param incidence is a pointer to the Incidence to be formatted. |
111 | @param richText if yes, the QString will be created as RichText. |
112 | @param spec is an optional time specification which, when specified, |
113 | will shift the Incidence times to different timezones. |
114 | @since 4.2 |
115 | @deprecated use toolTipStr( Calendar *, IncidenceBase *, bool, KDateTime::Spec) |
116 | */ |
117 | KCAL_DEPRECATED_EXPORT QString toolTipStr( IncidenceBase *incidence, |
118 | bool richText=true, |
119 | KDateTime::Spec spec=KDateTime::Spec() ); |
120 | |
121 | /** |
122 | Create a QString representation of an Incidence in a nice format |
123 | suitable for using in a tooltip. |
124 | @param incidence is a pointer to the Incidence to be formatted. |
125 | @param richText if yes, the QString will be created as RichText. |
126 | @deprecated use toolTipStr( Calendar *, IncidenceBase *, bool, KDateTime::Spec) |
127 | */ |
128 | KCAL_DEPRECATED_EXPORT QString toolTipString( IncidenceBase *incidence, |
129 | bool richText=true ); |
130 | /** |
131 | Create a RichText QString representation of an Incidence in a nice format |
132 | suitable for using in a viewer widget. |
133 | @param calendar is a pointer to the Calendar that owns the specified Incidence. |
134 | @param incidence is a pointer to the Incidence to be formatted. |
135 | @param date is the QDate for which the string representation should be computed; |
136 | used mainly for recurring incidences. |
137 | @param spec is an optional time specification which, when specified, |
138 | will shift the Incidence times to different timezones. |
139 | @since 4.4 |
140 | */ |
141 | KCAL_DEPRECATED_EXPORT QString extensiveDisplayStr( Calendar *calendar, |
142 | IncidenceBase *incidence, |
143 | const QDate &date=QDate(), |
144 | KDateTime::Spec spec=KDateTime::Spec() ); |
145 | |
146 | /** |
147 | Create a RichText QString representation of an Incidence in a nice format |
148 | suitable for using in a viewer widget. |
149 | @param sourceName where the incidence is from (e.g. resource name) |
150 | @param incidence is a pointer to the Incidence to be formatted. |
151 | @param date is the QDate for which the string representation should be computed; |
152 | used mainly for recurring incidences. |
153 | @param spec is an optional time specification which, when specified, |
154 | will shift the Incidence times to different timezones. |
155 | @since 4.5 |
156 | */ |
157 | KCAL_DEPRECATED_EXPORT QString extensiveDisplayStr( const QString &sourceName, |
158 | IncidenceBase *incidence, |
159 | const QDate &date=QDate(), |
160 | KDateTime::Spec spec=KDateTime::Spec() ); |
161 | |
162 | /** |
163 | Create a RichText QString representation of an Incidence in a nice format |
164 | suitable for using in a viewer widget. |
165 | @param incidence is a pointer to the Incidence to be formatted. |
166 | @param spec is an optional time specification which, when specified, |
167 | will shift the Incidence times to different timezones. |
168 | @since 4.2 |
169 | @deprecated use extensiveDisplayStr( Calendar *, IncidenceBase *, KDateTime::Spec ) |
170 | */ |
171 | KCAL_DEPRECATED_EXPORT QString extensiveDisplayStr( IncidenceBase *incidence, |
172 | KDateTime::Spec spec=KDateTime::Spec() ); |
173 | |
174 | /** |
175 | Create a RichText QString representation of an Incidence in a nice format |
176 | suitable for using in a viewer widget. |
177 | @param incidence is a pointer to the Incidence to be formatted. |
178 | @deprecated use extensiveDisplayStr( Calendar *, IncidenceBase *, KDateTime::Spec ) |
179 | */ |
180 | KCAL_DEPRECATED_EXPORT QString extensiveDisplayString( IncidenceBase *incidence ); |
181 | |
182 | /** |
183 | Create a QString representation of an Incidence in format suitable for |
184 | including inside a mail message. |
185 | @param incidence is a pointer to the Incidence to be formatted. |
186 | @param spec is an optional time specification which, when specified, |
187 | will shift the Incidence times to different timezones. |
188 | @since 4.2 |
189 | */ |
190 | KCAL_DEPRECATED_EXPORT QString mailBodyStr( IncidenceBase *incidence, |
191 | KDateTime::Spec spec=KDateTime::Spec() ); |
192 | |
193 | /** |
194 | Create a QString representation of an Incidence in format suitable for |
195 | including inside a mail message. |
196 | @param incidence is a pointer to the Incidence to be formatted. |
197 | @deprecated use mailBodyStr( IncidenceBase *, KDateTime::Spec ) |
198 | */ |
199 | KCAL_DEPRECATED_EXPORT QString mailBodyString( IncidenceBase *incidence ); |
200 | |
201 | /** |
202 | Deliver an HTML formatted string displaying an invitation. |
203 | Use the time zone from mCalendar. |
204 | |
205 | @param invitation a QString containing a string representation of a calendar Event |
206 | which will be intrepreted as an invitation. |
207 | @param calendar is a pointer to the Calendar that owns the invitation. |
208 | @param helper is a pointer to an InvitationFormatterHelper. |
209 | */ |
210 | KCAL_DEPRECATED_EXPORT QString formatICalInvitation( QString invitation, Calendar *calendar, |
211 | InvitationFormatterHelper *helper ); |
212 | /** |
213 | Deliver an HTML formatted string displaying an invitation. |
214 | Differs from formatICalInvitation() in that invitation details (summary, location, etc) |
215 | have HTML formatting cleaned. |
216 | Use the time zone from calendar. |
217 | |
218 | @param invitation a QString containing a string representation of a calendar Event |
219 | which will be intrepreted as an invitation. |
220 | @param calendar is a pointer to the Calendar that owns the invitation. |
221 | @param helper is a pointer to an InvitationFormatterHelper. |
222 | @deprecated use formatICalInvitationNoHtml(const QString &,Calendar *, |
223 | InvitationFormatterHelper *,const QString &) instead. |
224 | */ |
225 | KCAL_DEPRECATED_EXPORT QString formatICalInvitationNoHtml( |
226 | QString invitation, Calendar *calendar, InvitationFormatterHelper *helper ); |
227 | |
228 | /** |
229 | Deliver an HTML formatted string displaying an invitation. |
230 | Differs from formatICalInvitation() in that invitation details (summary, location, etc) |
231 | have HTML formatting cleaned. |
232 | Use the time zone from calendar. |
233 | |
234 | @param invitation a QString containing a string representation of a calendar Event |
235 | which will be intrepreted as an invitation. |
236 | @param calendar is a pointer to the Calendar that owns the invitation. |
237 | @param helper is a pointer to an InvitationFormatterHelper. |
238 | @param sender is a QString containing the email address of the person sending the invitation. |
239 | @since 4.5 |
240 | */ |
241 | KCAL_DEPRECATED_EXPORT QString formatICalInvitationNoHtml( const QString &invitation, |
242 | Calendar *calendar, |
243 | InvitationFormatterHelper *helper, |
244 | const QString &sender ); |
245 | |
246 | /** |
247 | Format a TNEF attachment to an HTML mail |
248 | @since 4.1 |
249 | */ |
250 | KCAL_DEPRECATED_EXPORT QString formatTNEFInvitation( const QByteArray &tnef, Calendar *mCalendar, |
251 | InvitationFormatterHelper *helper ); |
252 | /** |
253 | Transform a TNEF attachment to an iCal or vCard |
254 | @since 4.1 |
255 | */ |
256 | KCAL_DEPRECATED_EXPORT QString msTNEFToVPart( const QByteArray &tnef ); |
257 | |
258 | /** |
259 | Build a pretty QString representation of an Incidence's recurrence info. |
260 | @param incidence is a pointer to the Incidence whose recurrence info |
261 | is to be formatted. |
262 | @since 4.1 |
263 | */ |
264 | KCAL_DEPRECATED_EXPORT QString recurrenceString( Incidence *incidence ); |
265 | |
266 | /** |
267 | Returns a reminder string computed for the specified Incidence. |
268 | Each item of the returning QStringList corresponds to a string |
269 | representation of an reminder belonging to this incidence. |
270 | @param incidence is a pointer to the Incidence. |
271 | @param shortfmt if false, a short version of each reminder is printed; |
272 | else a longer version of each reminder is printed. |
273 | @since 4.5 |
274 | */ |
275 | KCAL_DEPRECATED_EXPORT QStringList reminderStringList( Incidence *incidence, bool shortfmt = true ); |
276 | |
277 | /** |
278 | Build a QString time representation of a KDateTime object. |
279 | @param date The date to be formatted. |
280 | @param shortfmt If true, display info in short format. |
281 | @param spec Time spec to use. |
282 | @see dateToString(), dateTimeToString(). |
283 | @since 4.3 |
284 | */ |
285 | KCAL_DEPRECATED_EXPORT QString timeToString( const KDateTime &date, bool shortfmt = true, |
286 | const KDateTime::Spec &spec = KDateTime::Spec() ); |
287 | |
288 | /** |
289 | Build a QString date representation of a KDateTime object. |
290 | @param date The date to be formatted. |
291 | @param shortfmt If true, display info in short format. |
292 | @param spec Time spec to use. |
293 | @see dateToString(), dateTimeToString(). |
294 | @since 4.3 |
295 | */ |
296 | KCAL_DEPRECATED_EXPORT QString dateToString( const KDateTime &date, bool shortfmt = true, |
297 | const KDateTime::Spec &spec = KDateTime::Spec() ); |
298 | |
299 | /** |
300 | Build a QString date/time representation of a KDateTime object. |
301 | @param date The date to be formatted. |
302 | @param dateOnly If true, don't print the time fields; print the date fields only. |
303 | @param shortfmt If true, display info in short format. |
304 | @param spec Time spec to use. |
305 | @see dateToString(), timeToString(). |
306 | @since 4.3 |
307 | */ |
308 | KCAL_DEPRECATED_EXPORT QString dateTimeToString( const KDateTime &date, |
309 | bool dateOnly = false, |
310 | bool shortfmt = true, |
311 | const KDateTime::Spec &spec = KDateTime::Spec() ); |
312 | |
313 | /** |
314 | Returns a Calendar Resource label name for the specified Incidence. |
315 | @param calendar is a pointer to the Calendar. |
316 | @param incidence is a pointer to the Incidence. |
317 | @since 4.4 |
318 | */ |
319 | KCAL_DEPRECATED_EXPORT QString resourceString( Calendar *calendar, Incidence *incidence ); |
320 | |
321 | /** |
322 | Returns a duration string computed for the specified Incidence. |
323 | Only makes sense for Events and Todos. |
324 | @param incidence is a pointer to the Incidence. |
325 | @since 4.5 |
326 | */ |
327 | KCAL_DEPRECATED_EXPORT QString durationString( Incidence *incidence ); |
328 | |
329 | class EventViewerVisitor; |
330 | class ScheduleMessageVisitor; |
331 | class ; |
332 | class InvitationBodyVisitor; |
333 | class IncidenceCompareVisitor; |
334 | class ToolTipVisitor; |
335 | class MailBodyVisitor; |
336 | } |
337 | |
338 | } |
339 | |
340 | #endif |
341 | |