kopete/libkopete/kopetemessage.h

   1 /*
   2     kopetemessage.h  -  Base class for Kopete messages
   3
   4     Copyright (c) 2002-2003 by Martijn Klingens      <klingens@kde.org>
   5     Copyright (c) 2002-2004 by Olivier Goffart       <ogoffart@kde.org>
   6     Copyright (c) 2006-2007 by Charles Connell       <charles@connells.org>
   7     Copyright (c) 2007      by Michaël Larouche      <larouche@kde.org>
   8
   9     Kopete    (c) 2002-2007 by the Kopete developers <kopete-devel@kde.org>
  10
  11     *************************************************************************
  12     *                                                                       *
  13     * This library is free software; you can redistribute it and/or         *
  14     * modify it under the terms of the GNU Lesser General Public            *
  15     * License as published by the Free Software Foundation; either          *
  16     * version 2 of the License, or (at your option) any later version.      *
  17     *                                                                       *
  18     *************************************************************************
  19 */
  20
  21 #ifndef __KOPETE_MESSAGE_H__
  22 #define __KOPETE_MESSAGE_H__
  23
  24 #include <QtCore/QSharedData>
  25 #include <QtCore/QList>
  26 #include <QtCore/Qt>
  27
  28 #include "kopete_export.h"
  29
  30 class QByteArray;
  31 class QColor;
  32 class QDateTime;
  33 class QFont;
  34 class QTextCodec;
  35 class QTextDocument;
  36 class QStringList;
  37
  38 namespace Kopete {
  39
  40
  41 class ChatSession;
  42 class Contact;
  43
  44
  45 /**
  46  * @brief Representation of a message in Kopete
  47  *
  48  * @author Martijn Klingens <klingens@kde.org>
  49  * @author Olivier Goffart <ogoffart@kde.org>
  50  * @author Charles Connell <charles@connells.org>
  51  * @author Michaël Larouche <larouche@kde.org>
  52  *
  53  * Message represents any kind of messages shown on a chat view.
  54  * The message may contain a simple plain text string, or a rich text HTML
  55  * message. Also, Message can use a QTextDocument to structure the message.
  56  *
  57  * Message in plain text can however have a color or a specific font. You can
  58  * set color with setForegroundColor() and setBackgroundColor() and change the font
  59  * with setFont()
  60  *
  61  * Message have a direction from where the message come from. By default, the direction
  62  * is Internal but it is strongly advised to set the direction explicitly.
  63  *
  64  * @section plainMessage Creating a plain text message
  65  * @code
  66 Kopete::Message newMessage(sourceContact, destionationContact);
  67 newMessage.setPlainBody( QString("A plain text message") );
  68 newMessage.setDirection( Kopete::Message::Inbound );
  69  * @endcode
  70  *
  71  * @section richTextMessage Creating a complete rich text message
  72  * @code
  73 Kopete::Message richTextMessage(sourceContact, destinationContactList);
  74 richTextMessage.setTimestamp( QDateTime::currentDateTime() );
  75 richTextMessage.setDirection( Kopete::Message::Outbound );
  76 richTextMessage.setSubjet( QString("Kopete API documentation thread") );
  77 richTextMessage.setHtmlBody( QString("<b>A bold text</b>") );
  78  * @endcode
  79  */
  80 class KOPETE_EXPORT Message
  81 {
  82 public:
  83         /**
  84          * Direction of a message.
  85          */
  86         enum MessageDirection
  87         {
  88                 Inbound = 0, ///< Message is from the chat partner
  89                 Outbound = 1, ///< Message sent by the user
  90                 Internal= 2 ///< (Default) Message which are not sent via the network. This is just a notification a plugin can show in a chat view
  91         };
  92
  93         /**
  94          * Specifies the type of the message.
  95          */
  96         enum MessageType
  97         {
  98                 TypeNormal, ///< A typical message
  99                 TypeAction ///< An IRC-style action.
 100         };
 101
 102         /**
 103          * Specifies the type of notification that will be sent with this message
 104          */
 105         enum MessageImportance
 106         {
 107                 Low = 0, ///< almost no notifications. automatically used in groupChat
 108                 Normal = 1, ///< Default notification, for normal message
 109                 Highlight = 2 ///< Highlight notification, for most important messages, which require particular attentions.
 110         };
 111
 112         /**
 113          * Constructs a new empty message
 114          */
 115         explicit Message();
 116
 117         /**
 118          * Deref and clean private object if refcount == 0
 119          */
 120         ~Message();
 121
 122         /**
 123          * @brief Constructs a new message with a from and to contact
 124          *
 125          * This constructor is a convience of the constructor who
 126          * take a list of contacts for destination
 127          * @param fromKC Contact who send the message
 128          * @param toKC Contact which the message is destined.
 129          */
 130         explicit Message( const Contact *fromKC, const Contact *toKC );
 131         /**
 132          * @brief Constructs a new message with many contacts as the destination.
 133          * @param fromKC Contact who send the message
 134          * @param contacts List of Contact to send the message
 135          */
 136         explicit Message( const Contact *fromKC, const QList<Contact*> &contacts);
 137
 138         /**
 139          * Copy constructor.
 140          * Just adds a reference, doesn't actually copy.
 141          */
 142         Message( const Message &other );
 143
 144         /**
 145          * Assignment operator
 146          * Just like the copy constructor it just refs and doesn't copy.
 147          */
 148         Message & operator=( const Message &other );
 149
 150         /**
 151          * @brief Accessor method for the timestamp of the message
 152          * @return The message's timestamp
 153          */
 154         QDateTime timestamp() const;
 155
 156         /**
 157          * @brief Set the message timestamp
 158          * @param timestamp timestamp as QDateTime. By default the current date and time.
 159          */
 160         void setTimestamp(const QDateTime &timestamp);
 161
 162         /**
 163          * @brief Accessor method for the Contact that sent this message
 164          * @return The Contact who sent this message
 165          */
 166         const Contact * from() const;
 167
 168         /**
 169          * @brief Accessor method for the Contacts that this message was sent to
 170          * @return Pointer list of the Contacts this message was sent to
 171          */
 172         QList<Contact*> to() const;
 173
 174         /**
 175          * @brief Accessor method for the message type
 176          * @return The type of the message
 177          * @see MessageType
 178          */
 179         MessageType type() const;
 180
 181         /**
 182          * @brief Set message type
 183          * @param type The type of the message
 184          * @see MessageType
 185          */
 186         void setType(MessageType type);
 187
 188         /**
 189          * @brief Accessor method for the preferred plugin
 190          * If null, Kopete will use the user's preferred plugin.
 191          * @return The preferred plugin
 192          */
 193         QString requestedPlugin() const;
 194
 195         /**
 196          * @brief Set a view plugin which will display the message
 197          *
 198          * This is used mostly by Jabber plugin to select between
 199          * the email window or the chat window depending of the
 200          * type of message.
 201          * @param requesedPlugin View plugin name
 202          */
 203         void setRequestedPlugin(const QString &requestedPlugin);
 204
 205         /**
 206          * @brief Accessor method for the foreground color
 207          * @return The message's foreground color
 208          */
 209         QColor foregroundColor() const;
 210
 211         /**
 212          * @brief Accessor method for the background color of the message
 213          * @return The message's background color
 214          */
 215         QColor backgroundColor() const;
 216
 217         /**
 218          * @brief Accesssor method for the direction of the text based on what language it is in
 219          * @return The message text's direction
 220          */
 221         bool isRightToLeft() const;
 222
 223         /**
 224          * @brief Accessor method for the font of the message
 225          * @return The message's font
 226          */
 227         QFont font() const;
 228
 229         /**
 230          * @brief Accessor method for the subject of the message
 231          * @return The message subject
 232          */
 233         QString subject() const;
 234
 235         /**
 236          * @brief Set message subject
 237          * @param subject Message's subject
 238          */
 239         void setSubject(const QString &subject);
 240
 241         /**
 242          * @brief Accessor method for the body of the message
 243          * This is used internaly, to modify it make a copy of it with QTextDocument::clone()
 244          * @return The message body
 245          */
 246         const QTextDocument *body() const;
 247
 248         /**
 249          * @brief Accessor method for the format of the message
 250          * @return The message format
 251          */
 252         Qt::TextFormat format() const;
 253
 254         /**
 255          * @brief Accessor method for the direction of the message
 256          * @return The message direction
 257          */
 258         MessageDirection direction() const;
 259
 260         /**
 261          * @brief Set the message direction
 262          * @param direction The message direction
 263          * @see MessageDirection
 264          */
 265         void setDirection(MessageDirection direction);
 266
 267         /**
 268          * @brief Accessor method for the importance
 269          * @see setImportance
 270          * @return The message importance (low/normal/highlight)
 271          */
 272         MessageImportance importance() const;
 273
 274         /**
 275          * @brief Set the importance.
 276          * @see importance and @see MessageImportance
 277          * @param importance The message importance to set
 278          */
 279         void setImportance(MessageImportance importance);
 280
 281         /**
 282          * @brief Sets the foreground color for the message
 283          * @see foregroundColor
 284          * @param color The color
 285          */
 286         void setForegroundColor( const QColor &color );
 287
 288         /**
 289          * @brief Sets the background color for the message
 290          * @see backgroundColor
 291          * @param color The color
 292          */
 293         void setBackgroundColor( const QColor &color );
 294
 295         /**
 296          * @brief Sets the font for the message
 297          * @see font
 298          * @param font The font
 299          */
 300         void setFont( const QFont &font );
 301
 302         /**
 303          * @brief Sets the body of the message
 304          *
 305          * @param body The body, intpreted as plain text
 306          */
 307         void setPlainBody( const QString &body);
 308
 309         /**
 310          * @brief Sets the body of the message
 311          *
 312          * @param body The body, interpreted as HTML
 313          */
 314         void setHtmlBody( const QString &body);
 315
 316         /**
 317          * @brief Sets the body of the message
 318          * The format is changed to RichText automatically
 319          * @param body The body
 320          */
 321         void setBody( const QTextDocument *body);
 322
 323         /**
 324          * @brief Get the message body back as plain text
 325          * @return The message body as plain text
 326          */
 327         QString plainBody() const;
 328
 329         /**
 330          * @brief Get the message body as escaped (X)HTML format.
 331          * That means every HTML special char (\>, \<, \&, ...) is escaped to the HTML entity (\&lt;, \&gt;, ...)
 332          * and newlines (\\n) are converted to \<br /\>
 333          * Just because you set an HTML body doesn't mean you'll get the same string back here, but it will
 334          * be equivalent in meaning
 335          * @return The message body as escaped text
 336          */
 337         QString escapedBody() const;
 338
 339         /**
 340          * @brief Get the message body as parsed HTML with Emoticons, and URL parsed
 341          * This should be ready to be shown in the chatwindow.
 342          * @return The HTML and Emoticon parsed message body
 343          */
 344         QString parsedBody() const;
 345
 346         /**
 347          * Get the related message manager.
 348          * If it is not set, returns 0L.
 349          *
 350          * The @ref ChatSession is only set if the message is already passed by the manager.
 351          * We should trust this only in aboutToSend/aboutToReceive signals
 352          */
 353          ChatSession *manager() const ;
 354
 355          /**
 356           * @brief Set the messagemanager for this message.
 357           * Should be only used by the manager itself. @see manager
 358           * @param manager The chat session
 359           */
 360          void setManager(ChatSession * manager);
 361
 362         /**
 363          * @brief Enables the use of a background for a message
 364          * @param enable A flag to indicate if the background should be enabled or disabled.
 365          */
 366         void setBackgroundOverride( bool enable );
 367
 368         /**
 369          * @brief Enables the use of a foreground for a message
 370          * @param enable A flag to indicate if the foreground should be enabled or disabled.
 371          */
 372         void setForegroundOverride( bool enable );
 373
 374         /**
 375          * @brief Enables the use of a RTF formatting for a message
 376          * @param enable A flag to indicate if the RTF formatting should be enabled or disabled.
 377          */
 378         void setRichTextOverride( bool enable );
 379
 380         /**
 381          * @brief Return HTML style attribute for this message.
 382          * @return A string formatted like this: "style=attr"
 383          */
 384         QString getHtmlStyleAttribute() const;
 385
 386         /**
 387          * @return The list of classes
 388          * Class are used to give different notification on a message. They are also used in the chatwindow as an HTML class
 389          */
 390         QStringList classes() const;
 391
 392         /**
 393          * @brief Add a class
 394          * @see classes
 395          * @param class class to add
 396          */
 397         void addClass(const QString& classe);
 398
 399         /**
 400          * @brief Set the classes
 401          * @see classes
 402          * @param classes The new classes
 403          */
 404         void setClasses(const QStringList &classes);
 405
 406 public:  /* static helpers */
 407
 408         /**
 409         * Unescapes a string, removing XML entity references and returns a plain text.
 410         *
 411         * Note that this method is *VERY* expensive when called on rich text bodies,
 412         * use with care!
 413         *
 414         */
 415         static QString unescape( const QString &xml );
 416
 417         /**
 418          * @brief Transform a plaintext message into HTML.
 419          * it escape main entity like &gt; &lt; add some &lt;br /&gt; or &amp;nbsp;
 420          */
 421         static QString escape( const QString & );
 422
 423 #if 0
 424         //candidate for removal!
 425         /**
 426          * Helper function to decode a string. Whatever returned here is *nearly guaranteed* to
 427          * be parseable by the XML engine.
 428          *
 429          * @param message The string you are trying to decode
 430          * @param providedCodec A codec you want to try to decode with
 431          * @param success Optional pointer to a bool you want updated on success. "Success"
 432          *      is defined as a successful decoding using either UTF8 or the codec you
 433          *      provided. If a guess has to be taken, success will be false.
 434          * @return The decoded string
 435
 436          */
 437         static QString decodeString( const QByteArray &message,
 438                 const QTextCodec *providedCodec = 0L, bool *success = 0L );
 439 #endif
 440
 441 private:
 442         class Private;
 443         QSharedDataPointer<Private> d;
 444
 445         /**
 446          * Called internally by @ref setBody() and the constructor
 447          * Basically @ref setBody() without detach
 448          * @internal
 449          */
 450         void doSetBody( const QString &body, Qt::TextFormat format = Qt::PlainText );
 451
 452         /**
 453          * Called internally by @ref setBody() and the constructor
 454          * Basically @ref setBody() without detach
 455          * @internal
 456          */
 457         void doSetBody (const QTextDocument *body, Qt::TextFormat format = Qt::PlainText);
 458
 459         /**
 460          * Called internally in rich text handling
 461          * @internal
 462          */
 463         static QString parseLinks( const QString &message, Qt::TextFormat format );
 464 };
 465
 466 }
 467
 468 #endif
 469
 470 // vim: set noet ts=4 sts=4 sw=4:
 471