alarmtext.h 7.36 KB
Newer Older
1
2
/*
 *  alarmtext.h  -  text/email alarm text conversion
David Jarvie's avatar
David Jarvie committed
3
4
 *  This file is part of kalarmcal library, which provides access to KAlarm
 *  calendar data.
David Jarvie's avatar
David Jarvie committed
5
 *  Copyright © 2004-2020 David Jarvie <djarvie@kde.org>
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
 *
 *  This library is free software; you can redistribute it and/or modify
 *  it under the terms of the GNU Library General Public License as published
 *  by the Free Software Foundation; either version 2 of the License, or (at
 *  your option) any later version.
 *
 *  This library is distributed in the hope that it will be useful, but WITHOUT
 *  ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 *  FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Library General Public
 *  License for more details.
 *
 *  You should have received a copy of the GNU Library General Public License
 *  along with this library; see the file COPYING.LIB.  If not, write to the
 *  Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
 *  MA 02110-1301, USA.
 */

David Jarvie's avatar
David Jarvie committed
23
24
#ifndef KALARM_ALARMTEXT_H
#define KALARM_ALARMTEXT_H
25

David Jarvie's avatar
David Jarvie committed
26
#include "kalarmcal_export.h"
27

Laurent Montel's avatar
Laurent Montel committed
28
#include <KCalendarCore/Todo>
David Jarvie's avatar
David Jarvie committed
29
#include <AkonadiCore/Item>
Laurent Montel's avatar
Laurent Montel committed
30
#include <QString>
31

32
namespace KAlarmCal
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
{

class KAEvent;

/**
 * @short Parses email, todo and script alarm texts.
 *
 * This class parses email, todo and script texts, enabling drag and drop of
 * these items to be recognised and interpreted. It also holds plain alarm
 * texts.
 *
 * - Email texts must contain headers (To, From, etc.) in normal RFC format.
 * - Todos should be in iCalendar format.
 * - Scripts are assumed if the alarm text starts with '#!'.
 *
 * @author David Jarvie <djarvie@kde.org>
 */

David Jarvie's avatar
David Jarvie committed
51
class KALARMCAL_EXPORT AlarmText
52
{
Laurent Montel's avatar
Laurent Montel committed
53
54
55
56
57
58
59
60
61
62
63
public:
    /** Constructor which sets the alarm text.
     *  If @p text starts with '#!', it is flagged as a script, else plain text.
     *  @param text alarm text to set
     */
    explicit AlarmText(const QString &text = QString());

    AlarmText(const AlarmText &other);
    ~AlarmText();
    AlarmText &operator=(const AlarmText &other);

David Jarvie's avatar
David Jarvie committed
64
65
66
    /** Initialise the instance to an empty state. */
    void clear();

Laurent Montel's avatar
Laurent Montel committed
67
68
69
70
71
72
73
74
75
76
77
78
    /** Set the alarm text.
     *  If @p text starts with '#!', it is flagged as a script, else plain text.
     *  @param text alarm text to set
     */
    void setText(const QString &text);

    /** Set the instance contents to be a script.
     *  @param text text of script to set
     */
    void setScript(const QString &text);

    /** Set the instance contents to be an email.
79
80
81
82
83
84
85
     *  @param to       'To' header parameter
     *  @param from     'From' header parameter
     *  @param cc       'Cc' header parameter
     *  @param time     'Date' header parameter
     *  @param subject  'Subject' header parameter
     *  @param body     email body text
     *  @param itemId   Akonadi item ID of the email.
Laurent Montel's avatar
Laurent Montel committed
86
87
     */
    void setEmail(const QString &to, const QString &from, const QString &cc, const QString &time,
88
                  const QString &subject, const QString &body, Akonadi::Item::Id itemId = -1);
Laurent Montel's avatar
Laurent Montel committed
89
90
91
92

    /** Set the instance contents to be a todo.
     *  @param todo Todo instance to set as the text
     */
93
    void setTodo(const KCalendarCore::Todo::Ptr &todo);
Laurent Montel's avatar
Laurent Montel committed
94
95
96
97
98
99
100

    /** Return the text for a text message alarm, in display format.
     *  - An email is returned as a sequence of headers followed by the message body.
     *  - A todo is returned as a subject, location and due date followed by any text.
     *  - A script or plain text is returned without interpretation.
     */
    QString displayText() const;
101

Laurent Montel's avatar
Laurent Montel committed
102
103
104
105
    /** Return the 'To' header parameter for an email alarm.
     *  @return 'from' value, or empty if not an email text.
     */
    QString to() const;
106

Laurent Montel's avatar
Laurent Montel committed
107
108
109
110
    /** Return the 'From' header parameter for an email alarm.
     *  @return 'from' value, or empty if not an email text.
     */
    QString from() const;
111

Laurent Montel's avatar
Laurent Montel committed
112
113
114
115
    /** Return the 'Cc' header parameter for an email alarm.
     *  @return 'cc' value, or empty if not an email text.
     */
    QString cc() const;
116

Laurent Montel's avatar
Laurent Montel committed
117
118
119
120
    /** Return the 'Date' header parameter for an email alarm.
     *  @return 'date' value, or empty if not an email text.
     */
    QString time() const;
121

Laurent Montel's avatar
Laurent Montel committed
122
123
124
125
    /** Return the 'Subject' header parameter for an email alarm.
     *  @return 'subject' value, or empty if not an email text.
     */
    QString subject() const;
126

Laurent Montel's avatar
Laurent Montel committed
127
128
129
130
131
132
133
134
135
    /** Return the email message body.
     *  @return message body, or empty if not an email text.
     */
    QString body() const;

    /** Return the summary text for a todo.
     *  @return summary text, or empty if not a todo.
     */
    QString summary() const;
136

Laurent Montel's avatar
Laurent Montel committed
137
138
139
140
    /** Return the location text for a todo.
     *  @return location text, or empty if not a todo.
     */
    QString location() const;
141

Laurent Montel's avatar
Laurent Montel committed
142
143
144
145
    /** Return the due date text for a todo.
     *  @return due date text, or empty if not a todo.
     */
    QString due() const;
146

Laurent Montel's avatar
Laurent Montel committed
147
148
149
150
151
    /** Return the description text for a todo.
     *  @return description text, or empty if not a todo.
     */
    QString description() const;

152
    /** Return whether the instance has any contents. */
Laurent Montel's avatar
Laurent Montel committed
153
    bool isEmpty() const;
154

Laurent Montel's avatar
Laurent Montel committed
155
156
    /** Return whether the instance contains the text of an email. */
    bool isEmail() const;
157

Laurent Montel's avatar
Laurent Montel committed
158
159
    /** Return whether the instance contains the text of a script. */
    bool isScript() const;
160

Laurent Montel's avatar
Laurent Montel committed
161
162
163
    /** Return whether the instance contains the text of a todo. */
    bool isTodo() const;

164
    /** Return the Akonadi item ID of an email.
165
     *  @return Item ID, or -1 if none.
166
167
     */
    Akonadi::Item::Id akonadiItemId() const;
Laurent Montel's avatar
Laurent Montel committed
168
169
170
171
172
173
174
175

    /** Return the alarm summary text for either single line or tooltip display.
     *  @param event      event whose summary text is to be returned
     *  @param maxLines   the maximum number of lines returned
     *  @param truncated  if non-null, points to a variable which will be set true
     *                    if the text returned has been truncated, other than to
     *                    strip a trailing newline, or false otherwise
     */
Laurent Montel's avatar
Laurent Montel committed
176
    static QString summary(const KAEvent &event, int maxLines = 1, bool *truncated = nullptr);
Laurent Montel's avatar
Laurent Montel committed
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210

    /** Return whether a text is an email, with at least To and From headers.
     *  @param text  text to check
     */
    static bool checkIfEmail(const QString &text);

    /** Check whether a text is an email (with at least To and From headers),
     *  and if so return its headers or optionally only its subject line.
     *  @param text         text to check
     *  @param subjectOnly  true to only return the subject line,
     *                      false to return all headers
     *  @return headers/subject line, or QString() if not the text of an email.
     */
    static QString emailHeaders(const QString &text, bool subjectOnly);

    /** Translate an alarm calendar text to a display text.
     *  Translation is needed for email texts, since the alarm calendar stores
     *  untranslated email prefixes.
     *  @param text   text to translate
     *  @param email  updated to indicate whether it is an email text
     */
    static QString fromCalendarText(const QString &text, bool &email);

    /** Return the text for an alarm message text, in alarm calendar format.
     *  (The prefix strings are untranslated in the calendar.)
     *  @param text  alarm message text
     */
    static QString toCalendarText(const QString &text);

private:
    //@cond PRIVATE
    class Private;
    Private *const d;
    //@endcond
211
212
};

213
} // namespace KAlarmCal
214

David Jarvie's avatar
David Jarvie committed
215
#endif // KALARM_ALARMTEXT_H
216

David Jarvie's avatar
David Jarvie committed
217
// vim: et sw=4: