Copy the KDE 3.5 branch to branches/trinity for new KDE 3.5 features.

BUG:215923


git-svn-id: svn://anonsvn.kde.org/home/kde/branches/trinity/kdenetwork@1054174 283d02a7-25f6-0310-bc7c-ecb5cbfe19da

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 (\&gt;, \&lt;, ...) 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 (\&lt;, \&gt;, ...)
+	 * 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 &gt; &lt; add some &lt;br /&gt; or &amp;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:
+