• Skip to content
  • Skip to link menu
KDE 4.6 API Reference
  • KDE API Reference
  • KDE-PIM Libraries
  • KDE Home
  • Contact Us
 

kpimidentities

  • KPIMIdentities
  • Signature
Public Types | Public Member Functions | Static Public Member Functions | Protected Member Functions | Friends

KPIMIdentities::Signature Class Reference

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

#include <signature.h>

List of all members.

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 &url, bool isExecutable)
 Signature (const Signature &that)
 Signature (const QString &text)
 ~Signature ()
void addImage (const QImage &image, const QString &imageName)
void insertIntoTextEdit (KRichTextEdit *textEdit, Placement placement=End, bool addSeparator=true)
void insertIntoTextEdit (Placement placement, AddedText addedText, KPIMTextEdit::TextEdit *textEdit) const
bool isInlinedHtml () const
Signature & operator= (const Signature &that)
bool operator== (const Signature &other) const
QString rawText (bool *ok=0) const
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 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 219 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 210 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 94 of file signature.cpp.

Signature::Signature ( const QString &  text)

Constructor for inline text.

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

Signature::Signature ( const Signature &  that)

Copy constructor.

Definition at line 121 of file signature.cpp.

Signature::~Signature ( )

Destructor.

Definition at line 135 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 590 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 490 of file signature.cpp.

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

Inserts this signature into the given text edit.

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

Definition at line 505 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.

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:
signaturethe signature, either as plain text or as HTML
textEditthe text edit to insert the signature into
placementdefines where in the textedit the signature should be inserted.
isHtmldefines whether the signature should be inserted as text or html
Since:
4.3
Deprecated:
Use the non-static insertIntoTextEdit() instead

Definition at line 527 of file signature.cpp.

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

Definition at line 266 of file signature.cpp.

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

Assignment operator.

Definition at line 126 of file signature.cpp.

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

Used for comparison.

Definition at line 551 of file signature.cpp.

QString Signature::rawText ( bool *  ok = 0) const
Returns:
the raw signature text as entered resp. read from file.

Definition at line 140 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.

Since:
4.4

Definition at line 599 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 261 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 623 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 255 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 576 of file signature.cpp.

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

Definition at line 616 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.

Definition at line 228 of file signature.cpp.


The documentation for this class was generated from the following files:
  • signature.h
  • signature.cpp

kpimidentities

Skip menu "kpimidentities"
  • Main Page
  • Alphabetical List
  • Class List
  • File List
  • Class Members
  • Related Pages

KDE-PIM Libraries

Skip menu "KDE-PIM Libraries"
  • akonadi
  •   contact
  •   kmime
  • kabc
  • kblog
  • kcal
  • kcalcore
  • kcalutils
  • kholidays
  • kimap
  • kioslave
  •   imap4
  •   mbox
  •   nntp
  • kldap
  • kmbox
  • kmime
  • kontactinterface
  • kpimidentities
  • kpimtextedit
  •   richtextbuilders
  • kpimutils
  • kresources
  • ktnef
  • kxmlrpcclient
  • mailtransport
  • microblog
  • qgpgme
  • syndication
  •   atom
  •   rdf
  •   rss2
Generated for KDE-PIM Libraries by doxygen 1.7.3
This website is maintained by Adriaan de Groot and Allen Winter.
KDE® and the K Desktop Environment® logo are registered trademarks of KDE e.V. | Legal