signature.h 9.14 KB
Newer Older
1
/*
2 3 4
    SPDX-FileCopyrightText: 2002-2004 Marc Mutz <mutz@kde.org>
    SPDX-FileCopyrightText: 2007 Tom Albers <tomalbers@kde.nl>
    SPDX-FileCopyrightText: 2009 Thomas McGuire <mcguire@kde.org>
5 6
    Author: Stefan Taferner <taferner@kde.org>

7
    SPDX-License-Identifier: LGPL-2.0-or-later
8 9
*/

Laurent Montel's avatar
Laurent Montel committed
10 11
#ifndef KIDENTITYMANAGER_SIGNATURE_H
#define KIDENTITYMANAGER_SIGNATURE_H
12

Laurent Montel's avatar
Laurent Montel committed
13
#include "kidentitymanagement_export.h"
14

Laurent Montel's avatar
Laurent Montel committed
15 16 17
#include <QString>
#include <QList>
#include <QHash>
Laurent Montel's avatar
Laurent Montel committed
18
#include <QImage>
19

Laurent Montel's avatar
Laurent Montel committed
20
namespace KIdentityManagement {
Laurent Montel's avatar
Laurent Montel committed
21 22
class Signature;
class Identity;
23 24 25
}
class KConfigGroup;

Laurent Montel's avatar
Laurent Montel committed
26
namespace KPIMTextEdit {
Laurent Montel's avatar
Laurent Montel committed
27
class RichTextComposer;
28 29
}

Laurent Montel's avatar
Laurent Montel committed
30
namespace KIdentityManagement {
31
class SignaturePrivate;
Laurent Montel's avatar
Laurent Montel committed
32 33
KIDENTITYMANAGEMENT_EXPORT QDataStream &operator<<(QDataStream &stream, const KIdentityManagement::Signature &sig);
KIDENTITYMANAGEMENT_EXPORT QDataStream &operator>>(QDataStream &stream, KIdentityManagement::Signature &sig);
Laurent Montel's avatar
Laurent Montel committed
34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62

/**
 * @short Abstraction of a signature (aka "footer").
 *
 * The signature can either be plain text, HTML text, text returned from a command or text stored
 * in a file.
 *
 * In case of HTML text, the signature can contain images.
 * Since you set the HTML source with setText(), there also needs to be a way to add the images
 * to the signature, as the HTML source contains only the img tags that reference those images.
 * To add the image to the signature, call addImage(). The name given there must match the name
 * of the img tag in the HTML source.
 *
 * The images need to be stored somewhere. The Signature class handles that by storing all images
 * in a directory. You must set that directory with setImageLocation(), before calling addImage().
 * The images added with addImage() are then saved to that directory when calling writeConfig().
 * When loading a signature, readConfig() automatically loads the images as well.
 * To actually add the images to a text edit, call insertIntoTextEdit().
 *
 * Example of creating a HTML signature and then inserting it into a text edit:
 * @code
 * Signature htmlSig;
 * htmlSig.setText( "<img src=\"hello.png\"> World" );
 * htmlSig.setInlinedHtml( true );
 * htmlSig.setImageLocation( KStandardDirs::locateLocal( "data", "emailidentities/example/" );
 * QImage image = ...;
 * htmlSig.addImage( image, "hello.png" );
 * ...
 * KTextEdit edit;
Laurent Montel's avatar
Laurent Montel committed
63 64
 * htmlSig.insertIntoTextEdit( KIdentityManagement::Signature::End,
 *                             KIdentityManagement::Signature::AddSeparator, &edit );
Laurent Montel's avatar
Laurent Montel committed
65 66
 * @endcode
 */
Laurent Montel's avatar
Laurent Montel committed
67
class KIDENTITYMANAGEMENT_EXPORT Signature
Laurent Montel's avatar
Laurent Montel committed
68 69 70
{
    friend class Identity;

Laurent Montel's avatar
Laurent Montel committed
71 72
    friend KIDENTITYMANAGEMENT_EXPORT QDataStream &operator<<(QDataStream &stream, const Signature &sig);
    friend KIDENTITYMANAGEMENT_EXPORT QDataStream &operator>>(QDataStream &stream, Signature &sig);
Laurent Montel's avatar
Laurent Montel committed
73 74 75 76

public:
    /** Type of signature (ie. way to obtain the signature text) */
    enum Type {
Allen Winter's avatar
Allen Winter committed
77 78 79 80
        Disabled = 0,
        Inlined = 1,
        FromFile = 2,
        FromCommand = 3
Laurent Montel's avatar
Laurent Montel committed
81
    };
82

Laurent Montel's avatar
Laurent Montel committed
83 84 85 86 87
    /**
     * Describes the placement of the signature text when it is to be inserted into a
     * text edit
     */
    enum Placement {
88 89 90
        Start,                   ///< The signature is placed at the start of the textedit
        End,                     ///< The signature is placed at the end of the textedit
        AtCursor                 ///< The signature is placed at the current cursor position
Laurent Montel's avatar
Laurent Montel committed
91 92
    };

Laurent Montel's avatar
Laurent Montel committed
93 94 95 96 97 98
    struct EmbeddedImage {
        QImage image;
        QString name;
    };
    typedef QSharedPointer<EmbeddedImage> EmbeddedImagePtr;

Laurent Montel's avatar
Laurent Montel committed
99
    /** Used for comparison */
Laurent Montel's avatar
Laurent Montel committed
100
    bool operator==(const Signature &other) const;
Laurent Montel's avatar
Laurent Montel committed
101 102 103 104 105 106

    /** Constructor for disabled signature */
    Signature();
    /** Constructor for inline text */
    Signature(const QString &text);
    /** Constructor for text from a file or from output of a command */
Laurent Montel's avatar
Fix api  
Laurent Montel committed
107
    Signature(const QString &path, bool isExecutable);
Laurent Montel's avatar
Laurent Montel committed
108 109 110
    /** Copy constructor */
    Signature(const Signature &that);
    /** Assignment operator */
Laurent Montel's avatar
Laurent Montel committed
111
    Signature &operator=(const Signature &that);
Laurent Montel's avatar
Laurent Montel committed
112 113 114 115 116 117
    /** Destructor */
    ~Signature();

    /** @return the raw signature text as entered resp. read from file.
        @param ok set to @c true if reading succeeded
     */
Laurent Montel's avatar
Laurent Montel committed
118
    Q_REQUIRED_RESULT QString rawText(bool *ok = nullptr) const;
Laurent Montel's avatar
Laurent Montel committed
119 120 121 122 123

    /** @return the signature text with a "-- \n" separator added, if
        necessary. A newline will not be appended or prepended.
        @param ok set to @c true if reading succeeded
     */
Laurent Montel's avatar
Laurent Montel committed
124
    Q_REQUIRED_RESULT QString withSeparator(bool *ok = nullptr) const;
Laurent Montel's avatar
Laurent Montel committed
125 126 127 128

    /** Set the signature text and mark this signature as being of
        "inline text" type. */
    void setText(const QString &text);
Laurent Montel's avatar
Laurent Montel committed
129
    Q_REQUIRED_RESULT QString text() const;
Laurent Montel's avatar
Laurent Montel committed
130 131 132 133 134 135

    /**
     * Returns the text of the signature. If the signature is HTML, the HTML
     * tags will be stripped.
     * @since 4.4
     */
Laurent Montel's avatar
Laurent Montel committed
136
    Q_REQUIRED_RESULT QString toPlainText() const;
Laurent Montel's avatar
Laurent Montel committed
137 138 139

    /** Set the signature URL and mark this signature as being of
        "from file" resp. "from output of command" type. */
Laurent Montel's avatar
Fix api  
Laurent Montel committed
140
    void setPath(const QString &path, bool isExecutable = false);
Laurent Montel's avatar
Laurent Montel committed
141
    Q_REQUIRED_RESULT QString path() const;
Laurent Montel's avatar
Laurent Montel committed
142 143

    /// @return the type of signature (ie. way to obtain the signature text)
Laurent Montel's avatar
Laurent Montel committed
144
    Q_REQUIRED_RESULT Type type() const;
Laurent Montel's avatar
Laurent Montel committed
145 146 147 148 149 150 151 152 153 154 155 156 157
    void setType(Type type);

    /**
     * Sets the inlined signature to text or html
     * @param isHtml sets the inlined signature to html
     * @since 4.1
     */
    void setInlinedHtml(bool isHtml);

    /**
     * @return boolean whether the inlined signature is html
     * @since 4.1
     */
Laurent Montel's avatar
Laurent Montel committed
158
    Q_REQUIRED_RESULT bool isInlinedHtml() const;
Laurent Montel's avatar
Laurent Montel committed
159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175

    /**
     * Sets the location where the copies of the signature images will be stored.
     * The images will be stored there when calling writeConfig(). The image location
     * is stored in the config, so the next readConfig() call knows where to look for
     * images.
     * It is recommended to use KStandardDirs::locateLocal( "data", "emailidentities/%1" )
     * for the location, where %1 is the unique identifier of the identity.
     *
     * @warning readConfig will delete all other PNG files in this directory, as they could
     *          be stale inline image files
     *
     * Like with addImage(), the SignatureConfigurator will handle this for you.
     * @param path the path to set as image location
     * @since 4.4
     */
    void setImageLocation(const QString &path);
Laurent Montel's avatar
Laurent Montel committed
176
    Q_REQUIRED_RESULT QString imageLocation() const;
Laurent Montel's avatar
Laurent Montel committed
177

Laurent Montel's avatar
Laurent Montel committed
178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196
    /**
     * Adds the given image to the signature.
     * This is needed if you use setText() to set some HTML source that references images. Those
     * referenced images needed to be added by calling this function. The @imageName has to match
     * the src attribute of the img tag.
     *
     * If you use SignatureConfigurator, you don't need to call this function, as the configurator
     * will handle this for you.
     * setImageLocation() needs to be called once before.
     * @since 4.4
     */
    void addImage(const QImage &image, const QString &imageName);

    /**
     * @brief setEnabledSignature
     * @param enabled enables signature if set as @c true
     * @since 4.9
     */
    void setEnabledSignature(bool enabled);
Laurent Montel's avatar
Laurent Montel committed
197
    Q_REQUIRED_RESULT bool isEnabledSignature() const;
Laurent Montel's avatar
Laurent Montel committed
198 199

    enum AddedTextFlag {
200 201
        AddNothing = 0,         ///< Don't add any text to the signature
        AddSeparator = 1 << 0,  ///< The separator '-- \n' will be added in front
Laurent Montel's avatar
Laurent Montel committed
202
        ///  of the signature
203
        AddNewLines = 1 << 1    ///< Add a newline character in front or after the signature,
Laurent Montel's avatar
Laurent Montel committed
204 205 206 207 208 209 210
                      ///  depending on the placement
    };

    /// Describes which additional parts should be added to the signature
    typedef QFlags<AddedTextFlag> AddedText;

    /** Inserts this signature into the given text edit.
211 212 213
      * If the signature is inserted at the beginning, a couple of new
      * lines will be inserted before it, and the cursor is moved to
      * the beginning. Otherwise, the cursor position is preserved.
Laurent Montel's avatar
Laurent Montel committed
214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229
      * For undo/redo, this is treated as one operation.
      *
      * Rich text mode of the text edit will be enabled if the signature is in
      * inlined HTML format.
      *
      * If this signature uses images, they will be added automatically.
      *
      * @param placement defines where in the text edit the signature should be
      *                  inserted.
      * @param addedText defines which other texts should be added to the signature
      * @param textEdit the signature will be inserted into this text edit.
      *
      * @since 4.9
      */
    // TODO: KDE5: BIC: Reorder parameters, the order here is a workaround for ambiguous parameters
    //                  with the deprecated method
Laurent Montel's avatar
Laurent Montel committed
230
    void insertIntoTextEdit(Placement placement, AddedText addedText, KPIMTextEdit::RichTextComposer *textEdit, bool forceDisplay = false) const;
Laurent Montel's avatar
Laurent Montel committed
231

Laurent Montel's avatar
Laurent Montel committed
232 233
    Q_REQUIRED_RESULT QVector<Signature::EmbeddedImagePtr> embeddedImages() const;
    void setEmbeddedImages(const QVector<EmbeddedImagePtr> &embedded);
Laurent Montel's avatar
Laurent Montel committed
234

Laurent Montel's avatar
Laurent Montel committed
235 236 237 238 239 240 241
protected:

    // TODO: KDE5: BIC: Move all to private class
    void writeConfig(KConfigGroup &config) const;
    void readConfig(const KConfigGroup &config);

private:
Laurent Montel's avatar
Laurent Montel committed
242
    //@cond PRIVATE
243
    SignaturePrivate *const d;
Laurent Montel's avatar
Laurent Montel committed
244
    //@endcond
Laurent Montel's avatar
Laurent Montel committed
245 246 247
};

Q_DECLARE_OPERATORS_FOR_FLAGS(Signature::AddedText)
248 249 250
}

#endif /*kpim_signature_h*/