Akonadi Notes

noteutils.h
1/* This file is part of the KDE project
2 SPDX-FileCopyrightText: 2011 Christian Mollekopf <chrigi_1@fastmail.fm>
3
4 SPDX-License-Identifier: LGPL-2.0-or-later
5*/
6
7#pragma once
8
9#include "akonadi-notes_export.h"
10
11#include <QMap>
12#include <QUrl>
13
14#include <memory>
15
16class QDateTime;
17class QString;
18
19template<typename T> class QSharedPointer;
20
21namespace KMime
22{
23class Message;
24using MessagePtr = QSharedPointer<Message>;
25}
26namespace Akonadi
27{
28namespace NoteUtils
29{
30/**
31 * @return mimetype for notes
32 * @since 4.8
33 */
34AKONADI_NOTES_EXPORT QString noteMimeType();
35
36/**
37 * @return icon for notes
38 * @since 4.8
39 */
40AKONADI_NOTES_EXPORT QString noteIconName();
41
42class AttachmentPrivate;
43
44/**
45 * An attachment for a note
46 * @since 4.9
47 */
48class AKONADI_NOTES_EXPORT Attachment
49{
50public:
51 /**
52 * Create an attachment referencing a url only
53 */
54 Attachment();
55 Attachment(const QUrl &url, const QString &mimetype);
56 /**
57 * Create an attachment with the content stored inline
58 */
59 Attachment(const QByteArray &data, const QString &mimetype);
60 Attachment(const Attachment &other);
62
63 bool operator==(const Attachment &a) const;
64 void operator=(const Attachment &a);
65
66 /**
67 * Returns the url for url-only attachments
68 */
69 [[nodiscard]] QUrl url() const;
70
71 /**
72 * Returns the date for inline attachments
73 */
74 [[nodiscard]] QByteArray data() const;
75
76 /**
77 * Sets the unique identifier of the attachment
78 *
79 * It can be used to refer to attachment from the note itself
80 *
81 * @since 5.15
82 */
83 void setContentID(const QString &contentID);
84
85 /**
86 * Returns the unique identifier for inline attachment
87 *
88 * @since 5.15
89 */
90 [[nodiscard]] QString contentID() const;
91
92 /**
93 * Set this to true if inline data provided via ctor
94 * is already base64 encoded. Default value is false.
95 *
96 * @since 5.15
97 */
98 void setDataBase64Encoded(bool encoded);
99
100 /**
101 * Returns true if data is already base64-encoded
102 *
103 * @since 5.15
104 */
105 [[nodiscard]] bool dataBase64Encoded() const;
106
107 /**
108 * Returns the mimetype
109 */
110 [[nodiscard]] QString mimetype() const;
111
112 /**
113 * Sets the label to be presented to the user
114 */
115 void setLabel(const QString &label);
116
117 /**
118 * Returns the label of the attachment
119 */
120 [[nodiscard]] QString label() const;
121
122private:
123 //@cond PRIVATE
124 std::unique_ptr<AttachmentPrivate> const d_ptr;
125 Q_DECLARE_PRIVATE(Attachment)
126 //@endcond
127};
128
129class NoteMessageWrapperPrivate;
130
131/**
132 * A convenience wrapper around KMime::MessagePtr for notes
133 *
134 * This is the format used by the Akonotes Resource
135 *
136 * A note has the following properties:
137 * uid: globally unique identifier (generated if empty)
138 * creationDate: timestamp when the note was created (generated if empty)
139 * lastModified: lastModified (generated if empty)
140 * classification: one of private, confidential, public. This is only meant as an indication to the user.
141 * title: title of the note
142 * text: textual content
143 * from: author (generated if empty)
144 * attachments: inline or url only
145 * custom: key value pair for custom values
146 *
147 * Reading a note from an Akonotes akonadi item:
148 * @code
149 * if ( item.hasPayload<KMime::MessagePtr>() ) {
150 * NoteUtils::NoteMessageWrapper note(item.payload<KMime::MessagePtr>());
151 * qCDebug(AKONADINOTES_LOG) << note.text();
152 * textIsRich = messageWrapper.textFormat() == Qt::RichText;
153 * }
154 * @endcode
155 *
156 * Setting the note as payload of an akonadi Item
157 * @code
158 * item.setMimeType(NoteUtils::noteMimeType());
159 * NoteUtils::NoteMessageWrapper note;
160 * note.setTitle( "title" );
161 * note.setText( "text" );
162 * note.setFrom( QString::fromLatin1( "MyApplication@kde4" ) );
163 * item.setPayload( note.message() );
164 * @endcode
165 *
166 * @author Christian Mollekopf <chrigi_1@fastmail.fm>
167 * @since 4.8
168 */
169class AKONADI_NOTES_EXPORT NoteMessageWrapper
170{
171public:
173 explicit NoteMessageWrapper(const KMime::MessagePtr &msg);
175
176 /**
177 * Set the uid of the note
178 * @param uid should be globally unique
179 */
180 void setUid(const QString &uid);
181
182 /**
183 * Returns the uid of the note
184 */
185 [[nodiscard]] QString uid() const;
186
187 enum Classification { Public, Private, Confidential };
188
189 /**
190 * Set the classification of the note
191 */
192 void setClassification(Classification);
193
194 /**
195 * Returns the classification of the note
196 */
197 [[nodiscard]] Classification classification() const;
198
199 /**
200 * Set the title of the note
201 */
202 void setTitle(const QString &title);
203
204 /**
205 * Returns the title of the note
206 */
207 [[nodiscard]] QString title() const;
208
209 /**
210 * Set the text of the note
211 *
212 * @param format only Qt::PlainText and Qt::RichText is supported
213 */
214 void setText(const QString &text, Qt::TextFormat format = Qt::PlainText);
215
216 /**
217 * Returns the text of the note
218 */
219 [[nodiscard]] QString text() const;
220
221 /**
222 * @return Qt::PlainText or Qt::RichText
223 */
224 [[nodiscard]] Qt::TextFormat textFormat() const;
225
226 /**
227 * @return plaintext version of the text (if richtext)
228 */
229 [[nodiscard]] QString toPlainText() const;
230
231 /**
232 * Set the creation date of the note (stored in the mime header)
233 */
234 void setCreationDate(const QDateTime &creationDate);
235
236 /**
237 * Returns the creation date of the note
238 */
239 [[nodiscard]] QDateTime creationDate() const;
240
241 /**
242 * Set the lastModified-date of the note
243 */
244 void setLastModifiedDate(const QDateTime &lastModifiedDate);
245
246 /**
247 * Returns the lastModified-date of the note
248 */
249 [[nodiscard]] QDateTime lastModifiedDate() const;
250
251 /**
252 * Set the origin (creator) of the note (stored in the mime header)
253 * This is usually the application creating the note.
254 * @param from must be an address in the style of foo@kde.org.
255 */
256 void setFrom(const QString &from);
257
258 /**
259 * Returns the origin (creator) of the note
260 */
261 [[nodiscard]] QString from() const;
262
263 /**
264 * Returns a reference to the list of attachments of the note
265 */
266 [[nodiscard]] QList<Attachment> &attachments();
267
268 /**
269 * Returns a reference to the custom-value map
270 * @return key-value map containing all custom values
271 */
272 [[nodiscard]] QMap<QString, QString> &custom();
273
274 /**
275 * Assemble a KMime message with the given values
276 *
277 * The message can then i.e. be stored inside an akonadi item
278 */
279 KMime::MessagePtr message() const;
280
281private:
282 //@cond PRIVATE
283 Q_DISABLE_COPY(NoteMessageWrapper)
284 std::unique_ptr<NoteMessageWrapperPrivate> const d_ptr;
285 Q_DECLARE_PRIVATE(NoteMessageWrapper)
286 //@endcond
287};
288
289}
290}
291
292Q_DECLARE_TYPEINFO(Akonadi::NoteUtils::Attachment, Q_RELOCATABLE_TYPE);
An attachment for a note.
Definition noteutils.h:49
A convenience wrapper around KMime::MessagePtr for notes.
Definition noteutils.h:170
TextFormat
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Tue Mar 26 2024 11:12:32 by doxygen 1.10.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.