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
39namespace KCal {
40class Calendar;
41class Incidence;
42class IncidenceBase;
43
44class 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*/
70namespace 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 InvitationHeaderVisitor;
332 class InvitationBodyVisitor;
333 class IncidenceCompareVisitor;
334 class ToolTipVisitor;
335 class MailBodyVisitor;
336}
337
338}
339
340#endif
341