#include <signature.h>

Public Types
typedef QFlags< AddedTextFlag >	AddedText

enum	AddedTextFlag { AddNothing = 0, AddSeparator = 1 << 0, AddNewLines = 1 << 1 }

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 &url, bool isExecutable)

	Signature (const Signature &that)

	~Signature ()

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

void KPIMIDENTITIES_DEPRECATED	insertIntoTextEdit (KRichTextEdit *textEdit, Placement placement=End, bool addSeparator=true)

void	insertIntoTextEdit (Placement placement, AddedText addedText, KPIMTextEdit::TextEdit *textEdit) const

void	insertIntoTextEdit (Placement placement, AddedText addedText, KPIMTextEdit::TextEdit *textEdit, bool forceDisplay) const

bool	isEnabledSignature () const

bool	isInlinedHtml () const

Signature &	operator= (const Signature &that)

bool	operator== (const Signature &other) const

QString	rawText (bool *ok=0) const

void	setEnabledSignature (bool enabled)

void	setImageLocation (const QString &path)

void	setInlinedHtml (bool isHtml)

void	setText (const QString &text)

void	setType (Type type)

void	setUrl (const QString &url, bool isExecutable=false)

QString	text () const

QString	toPlainText () const

Type	type () const

QString	url () const

QString	withSeparator (bool *ok=0) const

Static Public Member Functions
static void KPIMIDENTITIES_DEPRECATED	insertPlainSignatureIntoTextEdit (const QString &signature, KRichTextEdit *textEdit, Placement placement=End, bool isHtml=false)

Protected Member Functions
void	readConfig (const KConfigGroup &config)

void	writeConfig (KConfigGroup &config) const

Friends
KPIMIDENTITIES_EXPORT QDataStream &	operator<< (QDataStream &stream, const Signature &sig)

KPIMIDENTITIES_EXPORT QDataStream &	operator>> (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( KPIMIdentities::Signature::End,
                            KPIMIdentities::Signature::AddSeparator, &edit );

Definition at line 89 of file signature.h.

Member Typedef Documentation

typedef QFlags<AddedTextFlag> KPIMIdentities::Signature::AddedText

Describes which additional parts should be added to the signature.

Definition at line 232 of file signature.h.

Member Enumeration Documentation

enum KPIMIdentities::Signature::AddedTextFlag

Enumerator
AddNothing	Don't add any text to the signature.
AddSeparator	The separator '– ' will be added in front of the signature.
AddNewLines	Add a newline character in front or after the signature, depending on the placement.

Definition at line 223 of file signature.h.

enum KPIMIdentities::Signature::Placement

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 109 of file signature.h.

enum KPIMIdentities::Signature::Type

Type of signature (ie.

way to obtain the signature text)

Definition at line 98 of file signature.h.

Constructor & Destructor Documentation

Signature::Signature ( )

Constructor for disabled signature.

Definition at line 99 of file signature.cpp.

Signature::Signature ( const QString & text )

Constructor for inline text.

Definition at line 104 of file signature.cpp.

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

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

Definition at line 110 of file signature.cpp.

Signature::Signature ( const Signature & that )

Copy constructor.

Definition at line 127 of file signature.cpp.

Signature::~Signature ( )

Destructor.

Definition at line 142 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 633 of file signature.cpp.

void Signature::insertIntoTextEdit	(	KRichTextEdit *	textEdit,
		Placement	placement = `End`,
		bool	addSeparator = `true`
	)

Since: 4.3

Deprecated:: Use the other overload of insertIntoTextEdit() instead. This one doesn't support inline images and always adds newline characters.

Definition at line 507 of file signature.cpp.

void Signature::insertIntoTextEdit	(	Placement	placement,
		AddedText	addedText,
		KPIMTextEdit::TextEdit *	textEdit
	)		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

placement	defines where in the text edit the signature should be inserted.
addedText	defines which other texts should be added to the signature
textEdit	the signature will be inserted into this text edit.

Since: 4.4

Definition at line 525 of file signature.cpp.

void Signature::insertIntoTextEdit	(	Placement	placement,
		AddedText	addedText,
		KPIMTextEdit::TextEdit *	textEdit,
		bool	forceDisplay
	)		const

Since: 4.9

Definition at line 531 of file signature.cpp.

void Signature::insertPlainSignatureIntoTextEdit	(	const QString &	signature,
		KRichTextEdit *	textEdit,
		Signature::Placement	placement = `End`,
		bool	isHtml = `false`
	)

static

Inserts this given 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. A leading or trailing newline is also added automatically, depending on the placement. For undo/redo, this is treated as one operation. A separator is not added.

Use the insertIntoTextEdit() function if possible, as it has support for separators and does HTML detection automatically.

Rich text mode of the text edit will be enabled if isHtml is true.

Parameters

signature	the signature, either as plain text or as HTML
textEdit	the text edit to insert the signature into
placement	defines where in the textedit the signature should be inserted.
isHtml	defines whether the signature should be inserted as text or html

Since: 4.3

Deprecated:: Use the non-static insertIntoTextEdit() instead

Definition at line 564 of file signature.cpp.

bool Signature::isInlinedHtml ( ) const

Returns: boolean whether the inlined signature is html

Since: 4.1

Definition at line 273 of file signature.cpp.

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

Assignment operator.

Definition at line 132 of file signature.cpp.

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

Used for comparison.

Definition at line 588 of file signature.cpp.

QString Signature::rawText ( bool * ok = 0 ) const

Returns: the raw signature text as entered resp. read from file.

Parameters

ok	set to `true` if reading succeeded

Definition at line 147 of file signature.cpp.

void Signature::setEnabledSignature ( bool enabled )

setEnabledSignature

Parameters

enabled enables signature if set as true

Since: 4.9

Definition at line 678 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

path	the path to set as image location

Since: 4.4

Definition at line 642 of file signature.cpp.

void Signature::setInlinedHtml ( bool isHtml )

Sets the inlined signature to text or html.

Parameters

isHtml sets the inlined signature to html

Since: 4.1

Definition at line 268 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 666 of file signature.cpp.

void Signature::setUrl	(	const QString &	url,
		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 262 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 619 of file signature.cpp.

Signature::Type Signature::type ( ) const

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

Definition at line 659 of file signature.cpp.

QString Signature::withSeparator ( bool * ok = 0 ) const

Returns: the signature text with a "-- \n" separator added, if necessary. A newline will not be appended or prepended.

Parameters

ok	set to `true` if reading succeeded

Definition at line 235 of file signature.cpp.

The documentation for this class was generated from the following files:

kpimidentities

Public Types

Public Member Functions

Static Public Member Functions

Protected Member Functions

Friends

Detailed Description

Member Typedef Documentation

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

kpimidentities

kdepimlibs API Reference

Search