summaryrefslogtreecommitdiffstats
path: root/kopete/libkopete/kopetemessage.h
blob: 0737d2ae395d785753c00aea53e8e13c4473235d (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
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: