KIdentityManagementCore::Signature Class

class KIdentityManagementCore::Signature

Abstraction of a signature (aka "footer"). More...

Header: #include <KIdentityManagementCore/Signature>
CMake: find_package(KPim6IdentityManagementCore REQUIRED)
target_link_libraries(mytarget PRIVATE KPim6::IdentityManagementCore)

Public Types

enum AddedTextFlag { AddNothing, AddSeparator, AddNewLines }
enum Placement { Start, End, AtCursor }
enum Type { Disabled, Inlined, FromFile, FromCommand }

Public Functions

Signature()
Signature(const QString &text)
Signature(const QString &path, bool isExecutable)
Signature(const KIdentityManagementCore::Signature &that)
~Signature()
void addImage(const QImage &image, const QString &imageName)
QList<Signature::EmbeddedImagePtr> embeddedImages() const
QString imageLocation() const
bool isEnabledSignature() const
bool isInlinedHtml() const
QString path() const
QString rawText(bool *ok = nullptr, QString *errorMessage = nullptr) const
void setEmbeddedImages(const QList<KIdentityManagementCore::Signature::EmbeddedImagePtr> &embedded)
void setEnabledSignature(bool enabled)
void setImageLocation(const QString &path)
void setInlinedHtml(bool isHtml)
void setPath(const QString &path, bool isExecutable = false)
void setText(const QString &text)
void setType(KIdentityManagementCore::Signature::Type type)
QString text() const
QString toPlainText() const
KIdentityManagementCore::Signature::Type type() const
QString withSeparator(bool *ok = nullptr, QString *errorMessage = nullptr) const
KIdentityManagementCore::Signature &operator=(const KIdentityManagementCore::Signature &that)
bool operator==(const KIdentityManagementCore::Signature &other) const

Protected Functions

void readConfig(const KConfigGroup &config)
void writeConfig(KConfigGroup &config) const

Detailed Description

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:

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;
htmlSig.insertIntoTextEdit( KIdentityManagementCore::Signature::End,
                            KIdentityManagementCore::Signature::AddSeparator, &edit );

Member Type Documentation

enum Signature::AddedTextFlag

Describes which additional parts should be added to the signature.

ConstantValueDescription
KIdentityManagementCore::Signature::AddNothing0Don't add any text to the signature
KIdentityManagementCore::Signature::AddSeparator1 << 0The separator '– \n' will be added in front of the signature
KIdentityManagementCore::Signature::AddNewLines1 << 1Add a newline character in front or after the signature, depending on the placement

enum Signature::Placement

Describes the placement of the signature text when it is to be inserted into a text edit

ConstantValueDescription
KIdentityManagementCore::Signature::Start0The signature is placed at the start of the textedit
KIdentityManagementCore::Signature::End1The signature is placed at the end of the textedit
KIdentityManagementCore::Signature::AtCursor2The signature is placed at the current cursor position

enum Signature::Type

Type of signature (ie. way to obtain the signature text)

ConstantValueDescription
KIdentityManagementCore::Signature::Disabled0No signature
KIdentityManagementCore::Signature::Inlined1The signature text is stored in the configuration
KIdentityManagementCore::Signature::FromFile2The signature text is read from a file
KIdentityManagementCore::Signature::FromCommand3The signature text is the output of a command

Member Function Documentation

Signature::Signature()

Constructor for disabled signature

Signature::Signature(const QString &text)

Constructor for inline text

Signature::Signature(const QString &path, bool isExecutable)

Constructor for text from the file path or, if isExecutable is true, from the output of the command path

Signature::Signature(const KIdentityManagementCore::Signature &that)

Copy constructor

[noexcept] Signature::~Signature()

Destructor

void Signature::addImage(const QImage &image, const QString &imageName)

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.

QList<Signature::EmbeddedImagePtr> Signature::embeddedImages() const

Returns the list of images embedded in the signature.

See also setEmbeddedImages().

QString Signature::imageLocation() const

Returns the location where the copies of the signature images are stored.

See also setImageLocation().

bool Signature::isEnabledSignature() const

Returns true if the signature is enabled.

bool Signature::isInlinedHtml() const

Returns boolean whether the inlined signature is html

QString Signature::path() const

Returns the path of the signature file or command.

See also setPath().

QString Signature::rawText(bool *ok = nullptr, QString *errorMessage = nullptr) const

Returns the raw signature text as entered resp. read from file. ok set to true if reading succeeded errorMessage If available, contains a human readable explanation for ok being false.

[protected] void Signature::readConfig(const KConfigGroup &config)

Reads the signature from the configuration group config.

void Signature::setEmbeddedImages(const QList<KIdentityManagementCore::Signature::EmbeddedImagePtr> &embedded)

Sets the list of images embedded in the signature to embedded.

See also embeddedImages().

void Signature::setEnabledSignature(bool enabled)

setEnabledSignature enabled enables signature if set as true

See also isEnabledSignature().

void Signature::setImageLocation(const QString &path)

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. path the path to set as image location

See also imageLocation().

void Signature::setInlinedHtml(bool isHtml)

Sets the inlined signature to text or html isHtml sets the inlined signature to html

See also isInlinedHtml().

void Signature::setPath(const QString &path, bool isExecutable = false)

Set the signature URL to path and mark this signature as being of "from file" resp. "from output of command" type, depending on isExecutable.

See also path().

void Signature::setText(const QString &text)

Set the signature text to text and mark this signature as being of "inline text" type.

See also text().

void Signature::setType(KIdentityManagementCore::Signature::Type type)

Sets the type of signature to type.

See also type().

QString Signature::text() const

Returns the inlined signature text.

See also setText().

QString Signature::toPlainText() const

Returns the text of the signature. If the signature is HTML, the HTML tags will be stripped.

KIdentityManagementCore::Signature::Type Signature::type() const

Returns the type of signature (ie. way to obtain the signature text)

See also setType().

QString Signature::withSeparator(bool *ok = nullptr, QString *errorMessage = nullptr) const

Returns the signature text with a "– \n" separator added, if necessary. A newline will not be appended or prepended. ok set to true if reading succeeded errorMessage If available, contains a human readable explanation for ok being false.

[protected] void Signature::writeConfig(KConfigGroup &config) const

Writes the signature to the configuration group config.

KIdentityManagementCore::Signature &Signature::operator=(const KIdentityManagementCore::Signature &that)

Assigns that to this signature.

bool Signature::operator==(const KIdentityManagementCore::Signature &other) const

Returns true if this signature is equal to other.