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 |
31 | namespace KCal { class Todo; } |
32 | #endif |
33 | #include <QtCore/QString> |
34 | |
35 | |
36 | namespace KAlarmCal |
37 | { |
38 | |
39 | class 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 | |
55 | class 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 (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 | |