You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
tdenetwork/kopete/libkopete/kopetemessage.h

425 lines
14 KiB

/*
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 <tqptrlist.h>
#include <tqstring.h>
#include <tqdom.h>
#include <tqcolor.h>
#include <tqfont.h>
#include <tqdatetime.h>
#include <tqvaluelist.h>
#include "kopete_export.h"
class TQDateTime;
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 TQPtrList<Contact> &toKC, const TQString &body,
MessageDirection direction, MessageFormat format = PlainText,
const TQString &requestedPlugin = TQString(), 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 TQString &body,
MessageDirection direction, MessageFormat format = PlainText,
const TQString &requestedPlugin = TQString(), 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 TQPtrList<Contact> &toKC, const TQString &body,
const TQString &subject, MessageDirection direction, MessageFormat format = PlainText,
const TQString &requestedPlugin = TQString(), 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 TQDateTime &timeStamp, const Contact *fromKC, const TQPtrList<Contact> &toKC,
const TQString &body, MessageDirection direction, MessageFormat format = PlainText,
const TQString &requestedPlugin = TQString(), 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 TQDateTime &timeStamp, const Contact *fromKC, const TQPtrList<Contact> &toKC,
const TQString &body, const TQString &subject, MessageDirection direction,
MessageFormat format = PlainText, const TQString &requestedPlugin = TQString(),
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
*/
TQDateTime 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
*/
TQPtrList<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.
*/
TQString requestedPlugin() const;
/**
* Accessor method for the foreground color
* @return The message's foreground color
*/
TQColor fg() const;
/**
* Accessor method for the background color of the message
* @return The message's background color
*/
TQColor bg() const;
/**
* Accessor method for the font of the message
* @return The message's font
*/
TQFont font() const;
/**
* Accessor method for the subject of the message
* @return The message subject
*/
TQString 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 TQColor &color );
/**
* Sets the background color for the message
* @param color The color
*/
void setBg( const TQColor &color );
/**
* Sets the font for the message
* @param font The font
*/
void setFont( const TQFont &font );
/**
* @brief Sets the body of the message
*
* @param body The body
* @param format The format of the message, @see MessageFormat
*/
void setBody( const TQString &body, MessageFormat format = PlainText );
/**
* Get the message body back as plain text
* @return The message body as plain text
*/
TQString 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
*/
TQString 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
*/
TQString 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"
*/
TQString 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 TQString unescape( const TQString &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 TQString escape( const TQString & );
/**
* 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 TQString decodeString( const TQCString &message,
const TQTextCodec *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 TQString &body, MessageFormat format = PlainText );
class Private;
KSharedPtr<Private> d;
static TQString parseLinks( const TQString &message, MessageFormat format );
};
}
#endif
// vim: set noet ts=4 sts=4 sw=4: