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 <schumacher@kde.org>
5 SPDX-FileCopyrightText: 2004 Reinhold Kainhofer <reinhold@kainhofer.com>
6 SPDX-FileCopyrightText: 2009-2010 Klarälvdalens Datakonsult AB, a KDAB Group company <info@kdab.net>
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 <schumacher@kde.org>
16 @author Reinhold Kainhofer <reinhold@kainhofer.com>
17 @author Allen Winter <allen@kdab.com>
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
30namespace KCalUtils
31{
32class InvitationFormatterHelperPrivate;
33
34/**
35 * @brief The InvitationFormatterHelper class
36 */
37class KCALUTILS_EXPORT InvitationFormatterHelper
38{
39public:
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
46private:
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*/
62namespace 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*/
75KCALUTILS_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*/
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*/
99KCALUTILS_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*/
107KCALUTILS_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*/
120KCALUTILS_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*/
136KCALUTILS_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*/
146KCALUTILS_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*/
156KCALUTILS_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*/
164KCALUTILS_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*/
173KCALUTILS_EXPORT QString dateToString(QDate date, bool shortfmt = true);
174
175KCALUTILS_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*/
185KCALUTILS_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*/
192KCALUTILS_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*/
199KCALUTILS_EXPORT QString durationString(const KCalendarCore::Incidence::Ptr &incidence);
200
201class EventViewerVisitor;
202template<typename T>
203class ScheduleMessageVisitor;
204class InvitationHeaderVisitor;
205class InvitationBodyVisitor;
206class ToolTipVisitor;
207class MailBodyVisitor;
208}
209}
The InvitationFormatterHelper class.
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 formatICalInvitationNoHtml(const QString &invitation, const KCalendarCore::Calendar::Ptr &calendar, InvitationFormatterHelper *helper, const QString &sender)
Deliver an HTML formatted string displaying an invitation.
KCALUTILS_EXPORT QStringList reminderStringList(const KCalendarCore::Incidence::Ptr &incidence, bool shortfmt=true)
Returns a reminder string computed for the specified Incidence.
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 dateToString(QDate date, bool shortfmt=true)
Build a QString date representation of a QDate object.
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 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 durationString(const KCalendarCore::Incidence::Ptr &incidence)
Returns a duration string computed for the specified Incidence.
KCALUTILS_EXPORT QString dateTimeToString(const QDateTime &date, bool dateOnly=false, bool shortfmt=true)
Build a QString date/time representation of a QDateTime object.
KCALUTILS_EXPORT QString recurrenceString(const KCalendarCore::Incidence::Ptr &incidence)
Build a pretty QString representation of an Incidence's recurrence info.
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 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.
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Fri May 17 2024 11:51:06 by doxygen 1.10.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.