1/*
2 * alarmtext.h - text/email alarm text conversion
3 * This file is part of kalarmcal library, which provides access to KAlarm
4 * calendar data.
5 * Copyright © 2004,2005,2008-2012 by David Jarvie <djarvie@kde.org>
6 *
7 * This library is free software; you can redistribute it and/or modify
8 * it under the terms of the GNU Library General Public License as published
9 * by the Free Software Foundation; either version 2 of the License, or (at
10 * your option) any later version.
11 *
12 * This library is distributed in the hope that it will be useful, but WITHOUT
13 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
14 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public
15 * License for more details.
16 *
17 * You should have received a copy of the GNU Library General Public License
18 * along with this library; see the file COPYING.LIB. If not, write to the
19 * Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
20 * MA 02110-1301, USA.
21 */
22
23#ifndef ALARMTEXT_H
24#define ALARMTEXT_H
25
26#include "kalarmcal_export.h"
27
28#ifndef KALARMCAL_USE_KRESOURCES
29#include <kcalcore/todo.h>
30#else
31namespace KCal { class Todo; }
32#endif
33#include <QtCore/QString>
34
35
36namespace KAlarmCal
37{
38
39class KAEvent;
40
41/**
42 * @short Parses email, todo and script alarm texts.
43 *
44 * This class parses email, todo and script texts, enabling drag and drop of
45 * these items to be recognised and interpreted. It also holds plain alarm
46 * texts.
47 *
48 * - Email texts must contain headers (To, From, etc.) in normal RFC format.
49 * - Todos should be in iCalendar format.
50 * - Scripts are assumed if the alarm text starts with '#!'.
51 *
52 * @author David Jarvie <djarvie@kde.org>
53 */
54
55class KALARMCAL_EXPORT AlarmText
56{
57 public:
58 /** Constructor which sets the alarm text.
59 * If @p text starts with '#!', it is flagged as a script, else plain text.
60 * @param text alarm text to set
61 */
62 explicit AlarmText(const QString& text = QString());
63
64 AlarmText(const AlarmText& other);
65 ~AlarmText();
66 AlarmText& operator=(const AlarmText& other);
67
68 /** Set the alarm text.
69 * If @p text starts with '#!', it is flagged as a script, else plain text.
70 * @param text alarm text to set
71 */
72 void setText(const QString& text);
73
74 /** Set the instance contents to be a script.
75 * @param text text of script to set
76 */
77 void setScript(const QString& text);
78
79 /** Set the instance contents to be an email.
80 * @param to 'To' header parameter
81 * @param from 'From' header parameter
82 * @param cc 'Cc' header parameter
83 * @param time 'Date' header parameter
84 * @param subject 'Subject' header parameter
85 * @param body email body text
86 */
87 void setEmail(const QString& to, const QString& from, const QString& cc, const QString& time,
88 const QString& subject, const QString& body, unsigned long kmailSerialNumber = 0);
89
90#ifndef KALARMCAL_USE_KRESOURCES
91 /** Set the instance contents to be a todo.
92 * @param todo Todo instance to set as the text
93 */
94 void setTodo(const KCalCore::Todo::Ptr& todo);
95#else
96 /** Set the instance contents to be a todo.
97 * @param todo Todo instance to set as the text
98 */
99 void setTodo(const KCal::Todo* todo);
100#endif
101
102 /** Return the text for a text message alarm, in display format.
103 * - An email is returned as a sequence of headers followed by the message body.
104 * - A todo is returned as a subject, location and due date followed by any text.
105 * - A script or plain text is returned without interpretation.
106 */
107 QString displayText() const;
108 /** Return the 'To' header parameter for an email alarm.
109 * @return 'from' value, or empty if not an email text.
110 */
111 QString to() const;
112 /** Return the 'From' header parameter for an email alarm.
113 * @return 'from' value, or empty if not an email text.
114 */
115 QString from() const;
116 /** Return the 'Cc' header parameter for an email alarm.
117 * @return 'cc' value, or empty if not an email text.
118 */
119 QString cc() const;
120 /** Return the 'Date' header parameter for an email alarm.
121 * @return 'date' value, or empty if not an email text.
122 */
123 QString time() const;
124 /** Return the 'Subject' header parameter for an email alarm.
125 * @return 'subject' value, or empty if not an email text.
126 */
127 QString subject() const;
128 /** Return the email message body.
129 * @return message body, or empty if not an email text.
130 */
131 QString body() const;
132
133 /** Return the summary text for a todo.
134 * @return summary text, or empty if not a todo.
135 */
136 QString summary() const;
137 /** Return the location text for a todo.
138 * @return location text, or empty if not a todo.
139 */
140 QString location() const;
141 /** Return the due date text for a todo.
142 * @return due date text, or empty if not a todo.
143 */
144 QString due() const;
145 /** Return the description text for a todo.
146 * @return description text, or empty if not a todo.
147 */
148 QString description() const;
149
150 /** Return whether there is any text. */
151 bool isEmpty() const;
152 /** Return whether the instance contains the text of an email. */
153 bool isEmail() const;
154 /** Return whether the instance contains the text of a script. */
155 bool isScript() const;
156 /** Return whether the instance contains the text of a todo. */
157 bool isTodo() const;
158
159 /** Return the kmail serial number of an email.
160 * @return serial number, or 0 if none.
161 */
162 unsigned long kmailSerialNumber() const;
163
164 /** Return the alarm summary text for either single line or tooltip display.
165 * @param event event whose summary text is to be returned
166 * @param maxLines the maximum number of lines returned
167 * @param truncated if non-null, points to a variable which will be set true
168 * if the text returned has been truncated, other than to
169 * strip a trailing newline, or false otherwise
170 */
171 static QString summary(const KAEvent& event, int maxLines = 1, bool* truncated = 0);
172
173 /** Return whether a text is an email, with at least To and From headers.
174 * @param text text to check
175 */
176 static bool checkIfEmail(const QString& text);
177
178 /** Check whether a text is an email (with at least To and From headers),
179 * and if so return its headers or optionally only its subject line.
180 * @param text text to check
181 * @param subjectOnly true to only return the subject line,
182 * false to return all headers
183 * @return headers/subject line, or QString() if not the text of an email.
184 */
185 static QString emailHeaders(const QString& text, bool subjectOnly);
186
187 /** Translate an alarm calendar text to a display text.
188 * Translation is needed for email texts, since the alarm calendar stores
189 * untranslated email prefixes.
190 * @param text text to translate
191 * @param email updated to indicate whether it is an email text
192 */
193 static QString fromCalendarText(const QString& text, bool& email);
194
195 /** Return the text for an alarm message text, in alarm calendar format.
196 * (The prefix strings are untranslated in the calendar.)
197 * @param text alarm message text
198 */
199 static QString toCalendarText(const QString& text);
200
201 private:
202 //@cond PRIVATE
203 class Private;
204 Private* const d;
205 //@endcond
206};
207
208} // namespace KAlarmCal
209
210#endif // ALARMTEXT_H
211
212// vim: et sw=4:
213