KIdentityManagement::Signature

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
 

Friends

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

Enumerator
AddNothing 

Don't add any text to the signature.

AddSeparator 

The separator '–
' will be added in front.

AddNewLines 

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.

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

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 ( )

Destructor.

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.

Since
4.4

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.

Parameters
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.
Since
4.9

Definition at line 498 of file signature.cpp.

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

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
Returns
the raw signature text as entered resp. read from file.
Parameters
okset to true if reading succeeded

Definition at line 356 of file signature.cpp.

void Signature::setEnabledSignature ( bool  enabled)

setEnabledSignature

Parameters
enabledenables signature if set as true
Since
4.9

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.

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.

Parameters
paththe path to set as image location
Since
4.4

Definition at line 595 of file signature.cpp.

void Signature::setInlinedHtml ( bool  isHtml)

Sets the inlined signature to text or html.

Parameters
isHtmlsets the inlined signature to html
Since
4.1

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.

Since
4.4

Definition at line 572 of file signature.cpp.

Signature::Type Signature::type ( ) const
Returns
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
Returns
the signature text with a "-- \n" separator added, if necessary. A newline will not be appended or prepended.
Parameters
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.