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