KCalUtils

incidenceformatter.h
Go to the documentation of this file.
1 /*
2  This file is part of the kcalutils library.
3 
4  SPDX-FileCopyrightText: 2001-2003 Cornelius Schumacher <[email protected]>
5  SPDX-FileCopyrightText: 2004 Reinhold Kainhofer <[email protected]>
6  SPDX-FileCopyrightText: 2009-2010 Klarälvdalens Datakonsult AB, a KDAB Group company <[email protected]>
7 
8  SPDX-License-Identifier: LGPL-2.0-or-later
9 */
10 /**
11  @file
12  This file is part of the API for handling calendar data and provides
13  static functions for formatting Incidences for various purposes.
14 
15  @author Cornelius Schumacher <[email protected]>
16  @author Reinhold Kainhofer <[email protected]>
17  @author Allen Winter <[email protected]>
18 */
19 #pragma once
20 
21 #include "kcalutils_export.h"
22 
23 #include <KCalendarCore/Calendar>
24 #include <KCalendarCore/Incidence>
25 
26 #include <QDate>
27 
28 #include <memory>
29 
30 namespace KCalUtils
31 {
32 class InvitationFormatterHelperPrivate;
33 
34 /**
35  * @brief The InvitationFormatterHelper class
36  */
37 class KCALUTILS_EXPORT InvitationFormatterHelper
38 {
39 public:
41  virtual ~InvitationFormatterHelper();
42  [[nodiscard]] virtual QString generateLinkURL(const QString &id);
43  [[nodiscard]] virtual QString makeLink(const QString &id, const QString &text);
44  [[nodiscard]] virtual KCalendarCore::Calendar::Ptr calendar() const;
45 
46 private:
47  //@cond PRIVATE
48  Q_DISABLE_COPY(InvitationFormatterHelper)
49  std::unique_ptr<InvitationFormatterHelperPrivate> const d;
50  //@endcond
51 };
52 
53 /**
54  @brief
55  Provides methods to format Incidences in various ways for display purposes.
56 
57  Helpers that provides several static methods to format an Incidence in
58  different ways: like an HTML representation for KMail, a representation
59  for tool tips, or a representation for a viewer widget.
60 
61 */
62 namespace IncidenceFormatter
63 {
64 /**
65  Create a QString representation of an Incidence in a nice format
66  suitable for using in a tooltip.
67  All dates and times are converted to local time for display.
68  @param sourceName where the incidence is from (e.g. resource name)
69  @param incidence is a pointer to the Incidence to be formatted.
70  @param date is the QDate for which the toolTip should be computed; used
71  mainly for recurring incidences. Note: For to-dos, this a date between the
72  start date and the due date (inclusive) of the occurrence.
73  @param richText if yes, the QString will be created as RichText.
74 */
75 KCALUTILS_EXPORT QString toolTipStr(const QString &sourceName, const KCalendarCore::IncidenceBase::Ptr &incidence, QDate date = QDate(), bool richText = true);
76 
77 /**
78  Create a RichText QString representation of an Incidence in a nice format
79  suitable for using in a viewer widget.
80  All dates and times are converted to local time for display.
81  @param calendar is a pointer to the Calendar that owns the specified Incidence.
82  @param incidence is a pointer to the Incidence to be formatted.
83  @param date is the QDate for which the string representation should be computed;
84  used mainly for recurring incidences.
85 */
86 KCALUTILS_EXPORT QString extensiveDisplayStr(const KCalendarCore::Calendar::Ptr &calendar,
87  const KCalendarCore::IncidenceBase::Ptr &incidence,
88  QDate date = QDate());
89 
90 /**
91  Create a RichText QString representation of an Incidence in a nice format
92  suitable for using in a viewer widget.
93  All dates and times are converted to local time for display.
94  @param sourceName where the incidence is from (e.g. resource name)
95  @param incidence is a pointer to the Incidence to be formatted.
96  @param date is the QDate for which the string representation should be computed;
97  used mainly for recurring incidences.
98 */
99 KCALUTILS_EXPORT QString extensiveDisplayStr(const QString &sourceName, const KCalendarCore::IncidenceBase::Ptr &incidence, QDate date = QDate());
100 
101 /**
102  Create a QString representation of an Incidence in format suitable for
103  including inside a mail message.
104  All dates and times are converted to local time for display.
105  @param incidence is a pointer to the Incidence to be formatted.
106 */
107 KCALUTILS_EXPORT QString mailBodyStr(const KCalendarCore::IncidenceBase::Ptr &incidence);
108 
109 /**
110  Deliver an HTML formatted string displaying an invitation.
111  Use the time zone from mCalendar.
112 
113  @param invitation a QString containing a string representation of a calendar Incidence
114  which will be interpreted as an invitation.
115  @param calendar is a pointer to the Calendar that owns the invitation.
116  @param helper is a pointer to an InvitationFormatterHelper.
117 
118  @since 5.23.0
119 */
120 KCALUTILS_EXPORT QString formatICalInvitation(const QString &invitation, const KCalendarCore::Calendar::Ptr &calendar, InvitationFormatterHelper *helper);
121 
122 /**
123  Deliver an HTML formatted string displaying an invitation.
124  Differs from formatICalInvitation() in that invitation details (summary, location, etc)
125  have HTML formatting cleaned.
126  Use the time zone from calendar.
127 
128  @param invitation a QString containing a string representation of a calendar Incidence
129  which will be interpreted as an invitation.
130  @param calendar is a pointer to the Calendar that owns the invitation.
131  @param helper is a pointer to an InvitationFormatterHelper.
132  @param sender is a QString containing the email address of the person sending the invitation.
133 
134  @since 5.23.0
135 */
136 KCALUTILS_EXPORT QString formatICalInvitationNoHtml(const QString &invitation,
137  const KCalendarCore::Calendar::Ptr &calendar,
139  const QString &sender);
140 
141 /**
142  Build a pretty QString representation of an Incidence's recurrence info.
143  @param incidence is a pointer to the Incidence whose recurrence info
144  is to be formatted.
145 */
146 KCALUTILS_EXPORT QString recurrenceString(const KCalendarCore::Incidence::Ptr &incidence);
147 
148 /**
149  Returns a reminder string computed for the specified Incidence.
150  Each item of the returning QStringList corresponds to a string
151  representation of an reminder belonging to this incidence.
152  @param incidence is a pointer to the Incidence.
153  @param shortfmt if false, a short version of each reminder is printed;
154  else a longer version of each reminder is printed.
155 */
156 KCALUTILS_EXPORT QStringList reminderStringList(const KCalendarCore::Incidence::Ptr &incidence, bool shortfmt = true);
157 
158 /**
159  Build a QString time representation of a QTime object.
160  @param time The time to be formatted.
161  @param shortfmt If true, display info in short format.
162  @see dateToString(), dateTimeToString().
163 */
164 KCALUTILS_EXPORT QString timeToString(QTime time, bool shortfmt = true);
165 
166 /**
167  Build a QString date representation of a QDate object.
168  All dates and times are converted to local time for display.
169  @param date The date to be formatted.
170  @param shortfmt If true, display info in short format.
171  @see dateToString(), dateTimeToString().
172 */
173 KCALUTILS_EXPORT QString dateToString(QDate date, bool shortfmt = true);
174 
175 KCALUTILS_EXPORT QString formatStartEnd(const QDateTime &start, const QDateTime &end, bool isAllDay);
176 
177 /**
178  Build a QString date/time representation of a QDateTime object.
179  All dates and times are converted to local time for display.
180  @param date The date to be formatted.
181  @param dateOnly If true, don't print the time fields; print the date fields only.
182  @param shortfmt If true, display info in short format.
183  @see dateToString(), timeToString().
184 */
185 KCALUTILS_EXPORT QString dateTimeToString(const QDateTime &date, bool dateOnly = false, bool shortfmt = true);
186 
187 /**
188  Returns a Calendar Resource label name for the specified Incidence.
189  @param calendar is a pointer to the Calendar.
190  @param incidence is a pointer to the Incidence.
191 */
192 KCALUTILS_EXPORT QString resourceString(const KCalendarCore::Calendar::Ptr &calendar, const KCalendarCore::Incidence::Ptr &incidence);
193 
194 /**
195  Returns a duration string computed for the specified Incidence.
196  Only makes sense for Events and Todos.
197  @param incidence is a pointer to the Incidence.
198 */
199 KCALUTILS_EXPORT QString durationString(const KCalendarCore::Incidence::Ptr &incidence);
200 
201 class EventViewerVisitor;
202 template<typename T>
203 class ScheduleMessageVisitor;
204 class InvitationHeaderVisitor;
205 class InvitationBodyVisitor;
206 class ToolTipVisitor;
207 class MailBodyVisitor;
208 }
209 }
Q_SCRIPTABLE Q_NOREPLY void start()
KCALUTILS_EXPORT QString timeToString(QTime time, bool shortfmt=true)
Build a QString time representation of a QTime object.
KCALUTILS_EXPORT QString recurrenceString(const KCalendarCore::Incidence::Ptr &incidence)
Build a pretty QString representation of an Incidence's recurrence info.
KCALUTILS_EXPORT QString dateToString(QDate date, bool shortfmt=true)
Build a QString date representation of a QDate object.
KCALUTILS_EXPORT QString extensiveDisplayStr(const KCalendarCore::Calendar::Ptr &calendar, const KCalendarCore::IncidenceBase::Ptr &incidence, QDate date=QDate())
Create a RichText QString representation of an Incidence in a nice format suitable for using in a vie...
KCALUTILS_EXPORT QString dateTimeToString(const QDateTime &date, bool dateOnly=false, bool shortfmt=true)
Build a QString date/time representation of a QDateTime object.
The InvitationFormatterHelper class.
KCALUTILS_EXPORT QString formatICalInvitation(const QString &invitation, const KCalendarCore::Calendar::Ptr &calendar, InvitationFormatterHelper *helper)
Deliver an HTML formatted string displaying an invitation.
KCALUTILS_EXPORT QString resourceString(const KCalendarCore::Calendar::Ptr &calendar, const KCalendarCore::Incidence::Ptr &incidence)
Returns a Calendar Resource label name for the specified Incidence.
KCALUTILS_EXPORT QString toolTipStr(const QString &sourceName, const KCalendarCore::IncidenceBase::Ptr &incidence, QDate date=QDate(), bool richText=true)
Create a QString representation of an Incidence in a nice format suitable for using in a tooltip.
KCALUTILS_EXPORT QString mailBodyStr(const KCalendarCore::IncidenceBase::Ptr &incidence)
Create a QString representation of an Incidence in format suitable for including inside a mail messag...
KCALUTILS_EXPORT QString formatICalInvitationNoHtml(const QString &invitation, const KCalendarCore::Calendar::Ptr &calendar, InvitationFormatterHelper *helper, const QString &sender)
Deliver an HTML formatted string displaying an invitation.
KCALUTILS_EXPORT QString durationString(const KCalendarCore::Incidence::Ptr &incidence)
Returns a duration string computed for the specified Incidence.
KCALUTILS_EXPORT QStringList reminderStringList(const KCalendarCore::Incidence::Ptr &incidence, bool shortfmt=true)
Returns a reminder string computed for the specified Incidence.
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Mon Dec 4 2023 04:12:58 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.