KAlarmCal

alarmtext.h
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  * SPDX-FileCopyrightText: 2004-2020 David Jarvie <[email protected]>
6  *
7  * SPDX-License-Identifier: LGPL-2.0-or-later
8  */
9 
10 #pragma once
11 
12 #include "kalarmcal_export.h"
13 
14 #include <Akonadi/Item>
15 #include <KCalendarCore/Todo>
16 #include <QString>
17 
18 namespace KAlarmCal
19 {
20 
21 class KAEvent;
22 
23 /**
24  * @short Parses email, todo and script alarm texts.
25  *
26  * This class parses email, todo and script texts, enabling drag and drop of
27  * these items to be recognised and interpreted. It also holds plain alarm
28  * texts.
29  *
30  * - Email texts must contain headers (To, From, etc.) in normal RFC format.
31  * - Todos should be in iCalendar format.
32  * - Scripts are assumed if the alarm text starts with '#!'.
33  *
34  * @author David Jarvie <[email protected]>
35  */
36 
37 class KALARMCAL_EXPORT AlarmText
38 {
39 public:
40  /** Constructor which sets the alarm text.
41  * If @p text starts with '#!', it is flagged as a script, else plain text.
42  * @param text alarm text to set
43  */
44  explicit AlarmText(const QString &text = QString());
45 
46  AlarmText(const AlarmText &other);
47  ~AlarmText();
48  AlarmText &operator=(const AlarmText &other);
49 
50  /** Initialise the instance to an empty state. */
51  void clear();
52 
53  /** Set the alarm text.
54  * If @p text starts with '#!', it is flagged as a script, else plain text.
55  * @param text alarm text to set
56  */
57  void setText(const QString &text);
58 
59  /** Set the instance contents to be a script.
60  * @param text text of script to set
61  */
62  void setScript(const QString &text);
63 
64  /** Set the instance contents to be an email.
65  * @param to 'To' header parameter
66  * @param from 'From' header parameter
67  * @param cc 'Cc' header parameter
68  * @param time 'Date' header parameter
69  * @param subject 'Subject' header parameter
70  * @param body email body text
71  * @param itemId Akonadi item ID of the email.
72  */
73  void setEmail(const QString &to, const QString &from, const QString &cc, const QString &time,
74  const QString &subject, const QString &body, Akonadi::Item::Id itemId = -1);
75 
76  /** Set the instance contents to be a todo.
77  * @param todo Todo instance to set as the text
78  */
79  void setTodo(const KCalendarCore::Todo::Ptr &todo);
80 
81  /** Return the text for a text message alarm, in display format.
82  * - An email is returned as a sequence of headers followed by the message body.
83  * - A todo is returned as a subject, location and due date followed by any text.
84  * - A script or plain text is returned without interpretation.
85  */
86  QString displayText() const;
87 
88  /** Return the 'To' header parameter for an email alarm.
89  * @return 'from' value, or empty if not an email text.
90  */
91  QString to() const;
92 
93  /** Return the 'From' header parameter for an email alarm.
94  * @return 'from' value, or empty if not an email text.
95  */
96  QString from() const;
97 
98  /** Return the 'Cc' header parameter for an email alarm.
99  * @return 'cc' value, or empty if not an email text.
100  */
101  QString cc() const;
102 
103  /** Return the 'Date' header parameter for an email alarm.
104  * @return 'date' value, or empty if not an email text.
105  */
106  QString time() const;
107 
108  /** Return the 'Subject' header parameter for an email alarm.
109  * @return 'subject' value, or empty if not an email text.
110  */
111  QString subject() const;
112 
113  /** Return the email message body.
114  * @return message body, or empty if not an email text.
115  */
116  QString body() const;
117 
118  /** Return the summary text for a todo.
119  * @return summary text, or empty if not a todo.
120  */
121  QString summary() const;
122 
123  /** Return the location text for a todo.
124  * @return location text, or empty if not a todo.
125  */
126  QString location() const;
127 
128  /** Return the due date text for a todo.
129  * @return due date text, or empty if not a todo.
130  */
131  QString due() const;
132 
133  /** Return the description text for a todo.
134  * @return description text, or empty if not a todo.
135  */
136  QString description() const;
137 
138  /** Return whether the instance has any contents. */
139  bool isEmpty() const;
140 
141  /** Return whether the instance contains the text of an email. */
142  bool isEmail() const;
143 
144  /** Return whether the instance contains the text of a script. */
145  bool isScript() const;
146 
147  /** Return whether the instance contains the text of a todo. */
148  bool isTodo() const;
149 
150  /** Return the Akonadi item ID of an email.
151  * @return Item ID, or -1 if none.
152  */
153  Akonadi::Item::Id akonadiItemId() const;
154 
155  /** Return the alarm summary text for either single line or tooltip display.
156  * @param event event whose summary text is to be returned
157  * @param maxLines the maximum number of lines returned
158  * @param truncated if non-null, points to a variable which will be set true
159  * if the text returned has been truncated, other than to
160  * strip a trailing newline, or false otherwise
161  */
162  static QString summary(const KAEvent &event, int maxLines = 1, bool *truncated = nullptr);
163 
164  /** Return whether a text is an email, with at least To and From headers.
165  * @param text text to check
166  */
167  static bool checkIfEmail(const QString &text);
168 
169  /** Check whether a text is an email (with at least To and From headers),
170  * and if so return its headers or optionally only its subject line.
171  * @param text text to check
172  * @param subjectOnly true to only return the subject line,
173  * false to return all headers
174  * @return headers/subject line, or QString() if not the text of an email.
175  */
176  static QString emailHeaders(const QString &text, bool subjectOnly);
177 
178  /** Translate an alarm calendar text to a display text.
179  * Translation is needed for email texts, since the alarm calendar stores
180  * untranslated email prefixes.
181  * @param text text to translate
182  * @param email updated to indicate whether it is an email text
183  */
184  static QString fromCalendarText(const QString &text, bool &email);
185 
186  /** Return the text for an alarm message text, in alarm calendar format.
187  * (The prefix strings are untranslated in the calendar.)
188  * @param text alarm message text
189  */
190  static QString toCalendarText(const QString &text);
191 
192 private:
193  //@cond PRIVATE
194  class Private;
195  Private *const d;
196  //@endcond
197 };
198 
199 } // namespace KAlarmCal
200 
201 
202 // vim: et sw=4:
Parses email, todo and script alarm texts.
Definition: alarmtext.h:37
KAEvent represents a KAlarm event.
Definition: kaevent.h:184
This file is part of the KDE documentation.
Documentation copyright © 1996-2021 The KDE developers.
Generated on Fri Nov 26 2021 23:13:11 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.