diff options
Diffstat (limited to 'kopete/libkopete/kopetemessage.h')
| -rw-r--r-- | kopete/libkopete/kopetemessage.h | 424 |
1 files changed, 424 insertions, 0 deletions
diff --git a/kopete/libkopete/kopetemessage.h b/kopete/libkopete/kopetemessage.h new file mode 100644 index 00000000..0737d2ae --- /dev/null +++ b/kopete/libkopete/kopetemessage.h @@ -0,0 +1,424 @@ +/* + kopetemessage.h - Base class for Kopete messages + + Copyright (c) 2002-2003 by Martijn Klingens <klingens@kde.org> + Copyright (c) 2002-2004 by Olivier Goffart <ogoffart @ kde.org> + + Kopete (c) 2002-2004 by the Kopete developers <kopete-devel@kde.org> + + ************************************************************************* + * * + * This library is free software; you can redistribute it and/or * + * modify it under the terms of the GNU Lesser General Public * + * License as published by the Free Software Foundation; either * + * version 2 of the License, or (at your option) any later version. * + * * + ************************************************************************* +*/ + +#ifndef __KOPETE_MESSAGE_H__ +#define __KOPETE_MESSAGE_H__ + +#include "kopetecontact.h" + +#include <ksharedptr.h> + +#include <qptrlist.h> +#include <qstring.h> +#include <qdom.h> +#include <qcolor.h> +#include <qfont.h> +#include <qdatetime.h> +#include <qvaluelist.h> + +#include "kopete_export.h" + + +class QDateTime; + +namespace Kopete { + + + class ChatSession; +class Contact; + + +/** + * @author Martijn Klingens <klingens@kde.org> + * @author Olivier Goffart <ogoffart @ kde.org> + * + * Message represents any kind of messages shown on a chat view. + * + * The message may be a simple plaintext string, or a Richtext HTML like message, + * this is indicated by the @ref format() flag. + * PlainText message can however have a color, or specific fonts with the flag + * @ref bg(), @ref fg(), @ref font() + * It is recommended to use these flags, even for RichText messages, so the user can disable + * custom colors in the chat window style. + */ +class KOPETE_EXPORT Message +{ +public: + /** + * Direction of a message. + * - Inbound: Message is from the chat partner + * - Outbound: Message sent by the user. + * - Internal: Messages which are not sent via the network. This is just a notification a plugin can show in a chat view + * - Action: For the /me command , like on irc + */ + enum MessageDirection { Inbound = 0, Outbound = 1, Internal= 2 }; + + /** + * Format of body + * - PlainText: Just a simple text, without any formatting. If it contains HTML tags then they will be simply shown in the chatview. + * - RichText: Text already HTML escaped and which can contains some tags. the string + * should be a valid (X)HTML string. + * Any HTML specific characters (\<, \>, \&, ...) are escaped to the equivalent HTML + * entity (\>, \<, ...) newlines are \<br /\> and any other HTML tags will be interpreted. + * - ParsedHTML: only used by the chatview, this text is parsed and ready to + * show into the chatview, with Emoticons, and URLs + * - Crypted is used only by Jabber and the Cryptography plugin + */ + enum MessageFormat{ PlainText = 0x01 , RichText =0x02 , ParsedHTML = 0x04|RichText , Crypted = 0x08|PlainText}; + + /** + * Specifies the type of the message. + * Currently supported types are: + * - Normal: a message + * - Action: an IRC-style DESCRIBE action. + */ + enum MessageType { TypeNormal, TypeAction }; + + /** + * Specifies the type of notification that will be sent with this message + * - Low: almost no notifications. automatically used in groupChat + * - Normal: Default notification, for normal message + * - Highlight: Highlight notification, for most important messages, which require particular attentions. + */ + enum MessageImportance { Low = 0, Normal = 1, Highlight = 2 }; + + /** + * Constructs a new empty message + */ + Message(); + + /** + * Deref and clean private object if refcount == 0 + */ + ~Message(); + + /** + * Constructs a new message. See @ref setBody() to more information about the format + * @param fromKC The Contact that the message is coming from + * @param toKC List of Contacts the message is going to + * @param body Message body + * @param direction The direction of the message, Message::Inbound, Message::Outbound, Message::Internal + * @param format Format of the message + * @param requestedPlugin Requested view plugin for the message + * @param type Type of the message, see @ref MessageType + */ + Message( const Contact *fromKC, const QPtrList<Contact> &toKC, const QString &body, + MessageDirection direction, MessageFormat format = PlainText, + const QString &requestedPlugin = QString::null, MessageType type = TypeNormal ); + + /** + * Constructs a new message. See @ref setBody() to more information about the format + * @param fromKC The Contact that the message is coming from + * @param toKC List of Contacts the message is going to + * @param body Message body + * @param direction The direction of the message, Message::Inbound, Message::Outbound, Message::Internal + * @param format Format of the message + * @param requestedPlugin Requested view plugin for the message + * @param type Type of the message, see @ref MessageType + */ + Message( const Contact *fromKC, const Contact *toKC, const QString &body, + MessageDirection direction, MessageFormat format = PlainText, + const QString &requestedPlugin = QString::null, MessageType type = TypeNormal ); + + /** + * Constructs a new message. See @ref setBody() to more information about the format + * @param fromKC The Contact that the message is coming from + * @param toKC List of Contacts the message is going to + * @param body Message body + * @param subject The subject of the message + * @param direction The direction of the message, Message::Inbound, Message::Outbound, Message::Internal + * @param format Format of the message + * @param requestedPlugin Requested view plugin for the message + * @param type Type of the message, see @ref MessageType + */ + Message( const Contact *fromKC, const QPtrList<Contact> &toKC, const QString &body, + const QString &subject, MessageDirection direction, MessageFormat format = PlainText, + const QString &requestedPlugin = QString::null, MessageType type = TypeNormal ); + + /** + * Constructs a new message. See @ref setBody() to more information about the format + * @param timeStamp Timestamp for the message + * @param fromKC The Contact that the message is coming from + * @param toKC List of Contacts the message is going to + * @param body Message body + * @param direction The direction of the message, Message::Inbound, Message::Outbound, Message::Internal + * @param format Format of the message + * @param requestedPlugin Requested view plugin for the message + * @param type Type of the message, see @ref MessageType + */ + Message( const QDateTime &timeStamp, const Contact *fromKC, const QPtrList<Contact> &toKC, + const QString &body, MessageDirection direction, MessageFormat format = PlainText, + const QString &requestedPlugin = QString::null, MessageType type = TypeNormal ); + + /** + * Constructs a new message. See @ref setBody() to more information about the format + * @param timeStamp Timestamp for the message + * @param fromKC The Contact that the message is coming from + * @param toKC List of Contacts the message is going to + * @param body Message body + * @param subject The subject of the message + * @param direction The direction of the message, Message::Inbound, Message::Outbound, Message::Internal + * @param format Format of the message + * @param requestedPlugin Requested view plugin for the message + * @param type Type of the message, see @ref MessageType + */ + Message( const QDateTime &timeStamp, const Contact *fromKC, const QPtrList<Contact> &toKC, + const QString &body, const QString &subject, MessageDirection direction, + MessageFormat format = PlainText, const QString &requestedPlugin = QString::null, + MessageType type = TypeNormal ); + + /** + * Copy constructor. + * Just adds a reference, doesn't actually copy. + */ + Message( const Message &other ); + + /** + * Assignment operator + * Just like the copy constructor it just refs and doesn't copy. + */ + Message & operator=( const Message &other ); + + /** + * Accessor method for the timestamp of the message + * @return The message's timestamp + */ + QDateTime timestamp() const; + + /** + * Accessor method for the Contact that sent this message + * @return The Contact who sent this message + */ + const Contact * from() const; + + /** + * Accessor method for the Contacts that this message was sent to + * @return Pointer list of the Contacts this message was sent to + */ + QPtrList<Contact> to() const; + + /** + * @return the @ref MessageType of this message + */ + MessageType type() const; + + /** + * @return the view plugin you would prefer to use to read this message. If + * null, Kopete will use the user's preferred plugin. + */ + QString requestedPlugin() const; + + /** + * Accessor method for the foreground color + * @return The message's foreground color + */ + QColor fg() const; + + /** + * Accessor method for the background color of the message + * @return The message's background color + */ + QColor bg() const; + + /** + * Accessor method for the font of the message + * @return The message's font + */ + QFont font() const; + + /** + * Accessor method for the subject of the message + * @return The message subject + */ + QString subject() const; + + /** + * Accessor method for the format of the message + * @return The message format + */ + MessageFormat format() const; + + /** + * Accessor method for the direction of the message + * @return The message direction + */ + MessageDirection direction() const; + + /** + * @brief Accessor method for the importance + * @return The message importance (low/normal/highlight) + */ + MessageImportance importance() const; + + /** + * @brief Set the importance. + * @see importance + * @param importance The message importance to set + */ + void setImportance(MessageImportance importance); + + /** + * Sets the foreground color for the message + * @param color The color + */ + void setFg( const QColor &color ); + + /** + * Sets the background color for the message + * @param color The color + */ + void setBg( const QColor &color ); + + /** + * Sets the font for the message + * @param font The font + */ + void setFont( const QFont &font ); + + /** + * @brief Sets the body of the message + * + * @param body The body + * @param format The format of the message, @see MessageFormat + */ + void setBody( const QString &body, MessageFormat format = PlainText ); + + /** + * Get the message body back as plain text + * @return The message body as plain text + */ + QString plainBody() const; + + /** + * Get the message body as escaped (X)HTML format. + * That means every HTML special char (\>, \<, \&, ...) is escaped to the HTML entity (\<, \>, ...) + * and newlines (\\n) are converted to \<br /\> + * @return The message body as escaped text + */ + QString escapedBody() const; + + /** + * Get the message body as parsed HTML with Emoticons, and URL parsed + * this should be ready to be shown in the chatwindow. + * @return The HTML and Emoticon parsed message body + */ + QString parsedBody() const; + + /** + * Get the related message manager. + * If it is not set, returns 0L. + * + * The @ref ChatSession is only set if the message is already passed by the manager. + * We should trust this only in aboutToSend/aboutToReceive signals + */ + ChatSession *manager() const ; + + /** + * set the messagemanager for this message. + * should be only used by the manager itself + */ + void setManager(ChatSession *); + + /** + * Enables the use of a background for a message + * @param enable A flag to indicate if the background should be enabled or disabled. + */ + void setBgOverride( bool enable ); + + /** + * Enables the use of a foreground for a message + * @param enable A flag to indicate if the foreground should be enabled or disabled. + */ + void setFgOverride( bool enable ); + + /** + * Enables the use of a RTF formatting for a message + * @param enable A flag to indicate if the RTF formatting should be enabled or disabled. + */ + void setRtfOverride( bool enable ); + + /** + * Return HTML style attribute for this message. + * @return A string formatted like this: "style=attr" + */ + QString getHtmlStyleAttribute() const; + +public: /* static helpers */ + + /** + * Unescapes a string, removing XML entity references and returns a plain text. + * + * Note that this method is *VERY* expensive when called on rich text bodies, + * use with care! + * + * @param xml The string you want to unescape + */ + static QString unescape( const QString &xml ); + + /** + * Indicate whether the string is right-to-left (Arabic or Hebrew are bidi locales) + * or "normal" left-to-right. Calculating RTL on rich text is expensive, and + * isRightToLeft() therefore uses a cached value. + */ + bool isRightToLeft() const; + + /** + * @brief Transform a pleintext message to an html. + * it escape main entity like > < add some <br /> or &nbsp; + */ + static QString escape( const QString & ); + + + /** + * Helper function to decode a string. Whatever returned here is *nearly guarenteed* to + * be parseable by the XML engine. + * + * @param message The string you are trying to decode + * @param providedCodec A codec you want to try to decode with + * @param success Optional pointer to a bool you want updated on success. "Success" + * is defined as a successfull decoding using either UTF8 or the codec you + * provided. If a guess has to be taken, success will be false. + */ + static QString decodeString( const QCString &message, + const QTextCodec *providedCodec = 0L, bool *success = 0L ); + +private: + /** + * Message is implicitly shared. + * Detach the instance when modifying data. + */ + void detach(); + + /** + * Called internally by @ref setBody() and the constructor + * Basically @ref setBody() without detach + */ + void doSetBody( const QString &body, MessageFormat format = PlainText ); + + class Private; + KSharedPtr<Private> d; + + static QString parseLinks( const QString &message, MessageFormat format ); +}; + +} + +#endif + +// vim: set noet ts=4 sts=4 sw=4: + |