KIdentityManagement

signature.h
1/*
2 SPDX-FileCopyrightText: 2002-2004 Marc Mutz <mutz@kde.org>
3 SPDX-FileCopyrightText: 2007 Tom Albers <tomalbers@kde.nl>
4 SPDX-FileCopyrightText: 2009 Thomas McGuire <mcguire@kde.org>
5 Author: Stefan Taferner <taferner@kde.org>
6
7 SPDX-License-Identifier: LGPL-2.0-or-later
8*/
9
10#pragma once
11
12#include "kidentitymanagementcore_export.h"
13
14#include <QImage>
15#include <QSharedPointer>
16#include <QString>
17#include <memory>
18
19class KConfigGroup;
20namespace KIdentityManagementCore
21{
22class Signature;
23class Identity;
24class SignaturePrivate;
25KIDENTITYMANAGEMENTCORE_EXPORT QDataStream &operator<<(QDataStream &stream, const KIdentityManagementCore::Signature &sig);
26KIDENTITYMANAGEMENTCORE_EXPORT QDataStream &operator>>(QDataStream &stream, KIdentityManagementCore::Signature &sig);
27
28/**
29 * @short Abstraction of a signature (aka "footer").
30 *
31 * The signature can either be plain text, HTML text, text returned from a command or text stored
32 * in a file.
33 *
34 * In case of HTML text, the signature can contain images.
35 * Since you set the HTML source with setText(), there also needs to be a way to add the images
36 * to the signature, as the HTML source contains only the img tags that reference those images.
37 * To add the image to the signature, call addImage(). The name given there must match the name
38 * of the img tag in the HTML source.
39 *
40 * The images need to be stored somewhere. The Signature class handles that by storing all images
41 * in a directory. You must set that directory with setImageLocation(), before calling addImage().
42 * The images added with addImage() are then saved to that directory when calling writeConfig().
43 * When loading a signature, readConfig() automatically loads the images as well.
44 * To actually add the images to a text edit, call insertIntoTextEdit().
45 *
46 * Example of creating a HTML signature and then inserting it into a text edit:
47 * @code
48 * Signature htmlSig;
49 * htmlSig.setText( "<img src=\"hello.png\"> World" );
50 * htmlSig.setInlinedHtml( true );
51 * htmlSig.setImageLocation( KStandardDirs::locateLocal( "data", "emailidentities/example/" );
52 * QImage image = ...;
53 * htmlSig.addImage( image, "hello.png" );
54 * ...
55 * KTextEdit edit;
56 * htmlSig.insertIntoTextEdit( KIdentityManagementCore::Signature::End,
57 * KIdentityManagementCore::Signature::AddSeparator, &edit );
58 * @endcode
59 */
60class KIDENTITYMANAGEMENTCORE_EXPORT Signature
61{
62 friend class Identity;
63
64 friend KIDENTITYMANAGEMENTCORE_EXPORT QDataStream &operator<<(QDataStream &stream, const Signature &sig);
65 friend KIDENTITYMANAGEMENTCORE_EXPORT QDataStream &operator>>(QDataStream &stream, Signature &sig);
66
67public:
68 /** Type of signature (ie. way to obtain the signature text) */
69 enum Type {
70 Disabled = 0,
71 Inlined = 1,
72 FromFile = 2,
73 FromCommand = 3,
74 };
75
76 /**
77 * Describes the placement of the signature text when it is to be inserted into a
78 * text edit
79 */
80 enum Placement {
81 Start, ///< The signature is placed at the start of the textedit
82 End, ///< The signature is placed at the end of the textedit
83 AtCursor ///< The signature is placed at the current cursor position
84 };
85
86 struct EmbeddedImage {
87 QImage image;
88 QString name;
89 };
90 using EmbeddedImagePtr = QSharedPointer<EmbeddedImage>;
91
92 /** Used for comparison */
93 bool operator==(const Signature &other) const;
94
95 /** Constructor for disabled signature */
96 Signature();
97 /** Constructor for inline text */
98 Signature(const QString &text);
99 /** Constructor for text from a file or from output of a command */
100 Signature(const QString &path, bool isExecutable);
101 /** Copy constructor */
102 Signature(const Signature &that);
103 /** Assignment operator */
104 Signature &operator=(const Signature &that);
105 /** Destructor */
107
108 /** @return the raw signature text as entered resp. read from file.
109 @param ok set to @c true if reading succeeded
110 @param errorMessage If available, contains a human readable explanation for @p ok being @c false.
111 */
112 [[nodiscard]] QString rawText(bool *ok = nullptr, QString *errorMessage = nullptr) const;
113
114 /** @return the signature text with a "-- \n" separator added, if
115 necessary. A newline will not be appended or prepended.
116 @param ok set to @c true if reading succeeded
117 @param errorMessage If available, contains a human readable explanation for @p ok being @c false.
118 */
119 [[nodiscard]] QString withSeparator(bool *ok = nullptr, QString *errorMessage = nullptr) const;
120
121 /** Set the signature text and mark this signature as being of
122 "inline text" type. */
123 void setText(const QString &text);
124 [[nodiscard]] QString text() const;
125
126 /**
127 * Returns the text of the signature. If the signature is HTML, the HTML
128 * tags will be stripped.
129 * @since 4.4
130 */
131 [[nodiscard]] QString toPlainText() const;
132
133 /** Set the signature URL and mark this signature as being of
134 "from file" resp. "from output of command" type. */
135 void setPath(const QString &path, bool isExecutable = false);
136 [[nodiscard]] QString path() const;
137
138 /// @return the type of signature (ie. way to obtain the signature text)
139 [[nodiscard]] Type type() const;
140 void setType(Type type);
141
142 /**
143 * Sets the inlined signature to text or html
144 * @param isHtml sets the inlined signature to html
145 * @since 4.1
146 */
147 void setInlinedHtml(bool isHtml);
148
149 /**
150 * @return boolean whether the inlined signature is html
151 * @since 4.1
152 */
153 [[nodiscard]] bool isInlinedHtml() const;
154
155 /**
156 * Sets the location where the copies of the signature images will be stored.
157 * The images will be stored there when calling writeConfig(). The image location
158 * is stored in the config, so the next readConfig() call knows where to look for
159 * images.
160 * It is recommended to use KStandardDirs::locateLocal( "data", "emailidentities/%1" )
161 * for the location, where %1 is the unique identifier of the identity.
162 *
163 * @warning readConfig will delete all other PNG files in this directory, as they could
164 * be stale inline image files
165 *
166 * Like with addImage(), the SignatureConfigurator will handle this for you.
167 * @param path the path to set as image location
168 * @since 4.4
169 */
170 void setImageLocation(const QString &path);
171 [[nodiscard]] QString imageLocation() const;
172
173 /**
174 * Adds the given image to the signature.
175 * This is needed if you use setText() to set some HTML source that references images. Those
176 * referenced images needed to be added by calling this function. The @imageName has to match
177 * the src attribute of the img tag.
178 *
179 * If you use SignatureConfigurator, you don't need to call this function, as the configurator
180 * will handle this for you.
181 * setImageLocation() needs to be called once before.
182 * @since 4.4
183 */
184 void addImage(const QImage &image, const QString &imageName);
185
186 /**
187 * @brief setEnabledSignature
188 * @param enabled enables signature if set as @c true
189 * @since 4.9
190 */
191 void setEnabledSignature(bool enabled);
192 [[nodiscard]] bool isEnabledSignature() const;
193
195 AddNothing = 0, ///< Don't add any text to the signature
196 AddSeparator = 1 << 0, ///< The separator '-- \n' will be added in front
197 /// of the signature
198 AddNewLines = 1 << 1 ///< Add a newline character in front or after the signature,
199 /// depending on the placement
200 };
201
202 /// Describes which additional parts should be added to the signature
204
205 [[nodiscard]] QList<Signature::EmbeddedImagePtr> embeddedImages() const;
206 void setEmbeddedImages(const QList<EmbeddedImagePtr> &embedded);
207
208protected:
209 // TODO: KDE5: BIC: Move all to private class
210 void writeConfig(KConfigGroup &config) const;
211 void readConfig(const KConfigGroup &config);
212
213private:
214 //@cond PRIVATE
215 std::unique_ptr<SignaturePrivate> const d;
216 //@endcond
217};
218
219Q_DECLARE_OPERATORS_FOR_FLAGS(Signature::AddedText)
220}
User identity information.
Definition identity.h:73
Abstraction of a signature (aka "footer").
Definition signature.h:61
Placement
Describes the placement of the signature text when it is to be inserted into a text edit.
Definition signature.h:80
@ Start
The signature is placed at the start of the textedit.
Definition signature.h:81
@ End
The signature is placed at the end of the textedit.
Definition signature.h:82
Type
Type of signature (ie.
Definition signature.h:69
KCALENDARCORE_EXPORT QDataStream & operator>>(QDataStream &in, const KCalendarCore::Alarm::Ptr &)
KTEXTEDITOR_EXPORT QDebug operator<<(QDebug s, const MovingCursor &cursor)
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Fri Jun 14 2024 11:53:40 by doxygen 1.10.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.