KIdentityManagement::Signature Class Reference

#include <signature.h>

Public Types

typedef QFlags< AddedTextFlagAddedText
enum  AddedTextFlag { AddNothing = 0, AddSeparator = 1 << 0, AddNewLines = 1 << 1 }
typedef QSharedPointer< EmbeddedImage > EmbeddedImagePtr
enum  Placement { Start, End, AtCursor }
enum  Type { Disabled = 0, Inlined = 1, FromFile = 2, FromCommand = 3 }

Public Member Functions

 Signature ()
 Signature (const QString &text)
 Signature (const QString &path, bool isExecutable)
 Signature (const Signature &that)
 ~Signature ()
void addImage (const QImage &image, const QString &imageName)
QVector< Signature::EmbeddedImagePtrembeddedImages () const
QString imageLocation () const
void insertIntoTextEdit (Placement placement, AddedText addedText, KPIMTextEdit::RichTextComposer *textEdit, bool forceDisplay=false) const
bool isEnabledSignature () const
bool isInlinedHtml () const
Signatureoperator= (const Signature &that)
bool operator== (const Signature &other) const
QString path () const
QString rawText (bool *ok=nullptr) const
void setEmbeddedImages (const QVector< 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 (Type type)
QString text () const
QString toPlainText () const
Type type () const
QString withSeparator (bool *ok=nullptr) const

Protected Member Functions

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


KIDENTITYMANAGEMENT_EXPORT QDataStreamoperator<< (QDataStream &stream, const Signature &sig)
KIDENTITYMANAGEMENT_EXPORT QDataStreamoperator>> (QDataStream &stream, Signature &sig)

Detailed Description

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:

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( KIdentityManagement::Signature::End,

Definition at line 67 of file signature.h.

Member Typedef Documentation

Describes which additional parts should be added to the signature.

Definition at line 208 of file signature.h.

Member Enumeration Documentation


Don't add any text to the signature.


The separator '–
' will be added in front.


of the signature

Add a newline character in front or after the signature,

Definition at line 199 of file signature.h.

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


The signature is placed at the start of the textedit.


The signature is placed at the end of the textedit.


The signature is placed at the current cursor position.

Definition at line 87 of file signature.h.

Type of signature (ie.

way to obtain the signature text)

Definition at line 76 of file signature.h.

Constructor & Destructor Documentation

Signature::Signature ( )

Constructor for disabled signature.

Definition at line 313 of file signature.cpp.

Signature::Signature ( const QString text)

Constructor for inline text.

Definition at line 320 of file signature.cpp.

Signature::Signature ( const QString path,
bool  isExecutable 

Constructor for text from a file or from output of a command.

Definition at line 328 of file signature.cpp.

Signature::Signature ( const Signature that)

Copy constructor.

Definition at line 335 of file signature.cpp.

Signature::~Signature ( )


Definition at line 351 of file signature.cpp.

Member Function Documentation

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 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.


Definition at line 586 of file signature.cpp.

void Signature::insertIntoTextEdit ( Placement  placement,
AddedText  addedText,
KPIMTextEdit::RichTextComposer textEdit,
bool  forceDisplay = false 
) const

Inserts this signature into the given text edit.

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. 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.

placementdefines where in the text edit the signature should be inserted.
addedTextdefines which other texts should be added to the signature
textEditthe signature will be inserted into this text edit.

Definition at line 498 of file signature.cpp.

bool Signature::isInlinedHtml ( ) const
boolean whether the inlined signature is html

Definition at line 416 of file signature.cpp.

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

Assignment operator.

Definition at line 341 of file signature.cpp.

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

Used for comparison.

Definition at line 541 of file signature.cpp.

QString Signature::rawText ( bool *  ok = nullptr) const
the raw signature text as entered resp. read from file.
okset to true if reading succeeded

Definition at line 356 of file signature.cpp.

void Signature::setEnabledSignature ( bool  enabled)


enabledenables signature if set as true

Definition at line 635 of file signature.cpp.

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.

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.

paththe path to set as image location

Definition at line 595 of file signature.cpp.

void Signature::setInlinedHtml ( bool  isHtml)

Sets the inlined signature to text or html.

isHtmlsets the inlined signature to html

Definition at line 411 of file signature.cpp.

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

Set the signature URL and mark this signature as being of "from file" resp.

"from output of command" type.

Definition at line 405 of file signature.cpp.

void Signature::setText ( const QString text)

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

Definition at line 624 of file signature.cpp.

QString Signature::toPlainText ( ) const

Returns the text of the signature.

If the signature is HTML, the HTML tags will be stripped.


Definition at line 572 of file signature.cpp.

Signature::Type Signature::type ( ) const
the type of signature (ie. way to obtain the signature text)

Definition at line 617 of file signature.cpp.

QString Signature::withSeparator ( bool *  ok = nullptr) const
the signature text with a "-- \n" separator added, if necessary. A newline will not be appended or prepended.
okset to true if reading succeeded

Definition at line 378 of file signature.cpp.

The documentation for this class was generated from the following files:
This file is part of the KDE documentation.
Documentation copyright © 1996-2020 The KDE developers.
Generated on Thu Aug 13 2020 23:11:30 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.