summaryrefslogtreecommitdiffstats
path: root/kopete/libkopete/kopetechatsession.h
diff options
context:
space:
mode:
authortoma <toma@283d02a7-25f6-0310-bc7c-ecb5cbfe19da>2009-11-25 17:56:58 +0000
committertoma <toma@283d02a7-25f6-0310-bc7c-ecb5cbfe19da>2009-11-25 17:56:58 +0000
commitbcb704366cb5e333a626c18c308c7e0448a8e69f (patch)
treef0d6ab7d78ecdd9207cf46536376b44b91a1ca71 /kopete/libkopete/kopetechatsession.h
downloadtdenetwork-bcb704366cb5e333a626c18c308c7e0448a8e69f.tar.gz
tdenetwork-bcb704366cb5e333a626c18c308c7e0448a8e69f.zip
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
Diffstat (limited to 'kopete/libkopete/kopetechatsession.h')
-rw-r--r--kopete/libkopete/kopetechatsession.h405
1 files changed, 405 insertions, 0 deletions
diff --git a/kopete/libkopete/kopetechatsession.h b/kopete/libkopete/kopetechatsession.h
new file mode 100644
index 00000000..86d5fa64
--- /dev/null
+++ b/kopete/libkopete/kopetechatsession.h
@@ -0,0 +1,405 @@
+/*
+ kopetechatsession.h - Manages all chats
+
+ Copyright (c) 2002 by Duncan Mac-Vicar Prett <duncan@kde.org>
+ Copyright (c) 2002 by Daniel Stone <dstone@kde.org>
+ Copyright (c) 2002-2003 by Martijn Klingens <klingens@kde.org>
+ Copyright (c) 2002-2004 by Olivier Goffart <ogoffart @ kde.org>
+ Copyright (c) 2003 by Jason Keirstead <jason@keirstead.org>
+ Copyright (c) 2005 by Michaƫl Larouche <michael.larouche@kdemail.net>
+
+ Kopete (c) 2002-2003 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 __KOPETECHATSESSION_H__
+#define __KOPETECHATSESSION_H__
+
+#include <qobject.h>
+#include <qptrlist.h>
+#include <qvaluelist.h>
+
+#include <kxmlguiclient.h>
+
+#include "kopete_export.h"
+
+// FIXME: get rid of these includes
+#include "kopetemessage.h"
+#include "kopetemessagehandlerchain.h"
+
+class KMMPrivate;
+
+class KopeteView;
+
+namespace Kopete
+{
+
+class Contact;
+class Message;
+class Protocol;
+class OnlineStatus;
+class Account;
+class ChatSessionManager;
+class MessageHandlerChain;
+class TemporaryKMMCallbackAppendMessageHandler;
+
+typedef QPtrList<Contact> ContactPtrList;
+typedef QValueList<Message> MessageList;
+
+
+/**
+ * @author Duncan Mac-Vicar Prett <duncan@kde.org>
+ * @author Daniel Stone <dstone@kde.org>
+ * @author Martijn Klingens <klingens@kde.org>
+ * @author Olivier Goffart <ogoffart @ kde.org>
+ * @author Jason Keirstead <jason@keirstead.org>
+ *
+ * The Kopete::ChatSession manages a single chat.
+ * It is an interface between the protocol, and the chatwindow.
+ * The protocol can connect to @ref messageSent() signals to send the message, and can
+ * append received message with @ref messageReceived()
+ *
+ * The KMM inherits from KXMLGUIClient, this client is merged with the chatwindow's ui
+ * so plugins can add childClients of this client to add their own actions in the
+ * chatwindow.
+ */
+class KOPETE_EXPORT ChatSession : public QObject , public KXMLGUIClient
+{
+ // friend class so the object factory can access the protected constructor
+ friend class ChatSessionManager;
+
+ Q_OBJECT
+
+public:
+ /**
+ * Delete a chat manager instance
+ * You shouldn't delete the KMM yourself. it will be deleted when the chatwindow is closed
+ * see also @ref setCanBeDeleted() , @ref deref()
+ */
+ ~ChatSession();
+
+ /**
+ * @brief Get a list of all contacts in the session
+ */
+ const ContactPtrList& members() const;
+
+ /**
+ * @brief Get the local user in the session
+ * @return the local user in the session, same as account()->myself()
+ */
+ const Contact* myself() const;
+
+ /**
+ * @brief Get the protocol being used.
+ * @return the protocol
+ */
+ Protocol* protocol() const;
+
+ /**
+ * @brief get the account
+ * @return the account
+ */
+ Account *account() const ;
+
+ /**
+ * @brief The caption of the chat
+ *
+ * Used for named chats
+ */
+ const QString displayName();
+
+ /**
+ * @brief change the displayname
+ *
+ * change the display name of the chat
+ */
+ void setDisplayName( const QString &displayName );
+
+ /**
+ * @brief set a specified KOS for specified contact in this KMM
+ *
+ * Set a special icon for a contact in this kmm only.
+ * by default, all contact have their own status
+ */
+ void setContactOnlineStatus( const Contact *contact, const OnlineStatus &newStatus );
+
+ /**
+ * @brief get the status of a contact.
+ *
+ * see @ref setContactOnlineStatus()
+ */
+ const OnlineStatus contactOnlineStatus( const Contact *contact ) const;
+
+ /**
+ * @brief the manager's view
+ *
+ * Return the view for the supplied Kopete::ChatSession. If it already
+ * exists, it will be returned, otherwise, 0L will be returned or a new one
+ * if canCreate=true
+ * @param canCreate create a new one if it does not exist
+ * @param requestedPlugin Specifies the view plugin to use if we have to create one.
+ */
+ // FIXME: canCreate should definitely be an enum and not a bool - Martijn
+ KopeteView* view( bool canCreate = false, const QString &requestedPlugin = QString::null );
+
+ /**
+ * says if you may invite contact from the same account to this chat with @ref inviteContact
+ * @see setMayInvite
+ * @return true if it is possible to invite contact to this chat.
+ */
+ bool mayInvite() const ;
+
+ /**
+ * this method is called when a contact is dragged to the contactlist.
+ * @p contactId is the id of the contact. the contact is supposed to be of the same account as
+ * the @ref account() but we can't be sure the Kopete::Contact is realy on the contactlist
+ *
+ * It is possible to drag contact only if @ref mayInvite return true
+ *
+ * the default implementaiton do nothing
+ */
+ virtual void inviteContact(const QString &contactId);
+
+ /**
+ * Returns the message handler chain for the message direction @p dir.
+ */
+ MessageHandlerChain::Ptr chainForDirection( Message::MessageDirection dir );
+
+signals:
+ /**
+ * @brief the KMM will be deleted
+ * Used by a Kopete::ChatSession to signal that it is closing.
+ */
+ void closing( Kopete::ChatSession *kmm );
+
+ /**
+ * a message will be soon shown in the chatwindow.
+ * See @ref Kopete::ChatSessionManager::aboutToDisplay() signal
+ */
+ void messageAppended( Kopete::Message &msg, Kopete::ChatSession *kmm = 0L );
+
+ /**
+ * a message will be soon received
+ * See @ref Kopete::ChatSessionManager::aboutToReceive() signal
+ */
+ void messageReceived( Kopete::Message &msg, Kopete::ChatSession *kmm = 0L );
+
+ /**
+ * @brief a message is going to be sent
+ *
+ * The message is going to be sent.
+ * protocols can connect to this signal to send the message ro the network.
+ * the protocol have also to call @ref appendMessage() and @ref messageSucceeded()
+ * See also @ref Kopete::ChatSessionManager::aboutToSend() signal
+ */
+ void messageSent( Kopete::Message &msg, Kopete::ChatSession *kmm = 0L );
+
+ /**
+ * The last message has finaly successfully been sent
+ */
+ void messageSuccess();
+
+ /**
+ * @brief a new contact is now in the chat
+ */
+ // FIXME: What's 'suppress'? Shouldn't this be an enum? - Martijn
+ void contactAdded( const Kopete::Contact *contact, bool suppress );
+
+ /**
+ * @brief a contact is no longer in this chat
+ */
+ void contactRemoved( const Kopete::Contact *contact, const QString &reason, Kopete::Message::MessageFormat format = Message::PlainText, bool contactRemoved = false );
+
+ /**
+ * @brief a contact in this chat has changed his status
+ */
+ void onlineStatusChanged( Kopete::Contact *, const Kopete::OnlineStatus &, const Kopete::OnlineStatus & );
+
+ /**
+ * @brief The name of the chat is changed
+ */
+ void displayNameChanged();
+
+ /**
+ * @brief emitting a typing notification
+ *
+ * The user is typing a message, or just stopped typing
+ * the protocol should connect to this signal to signal to others
+ * that the user is typing if the protocol supports this
+ * @param isTyping say if the user is typing or not
+ */
+ void myselfTyping( bool isTyping );
+
+ /**
+ * Signals that a remote user is typing a message.
+ * the chatwindow connects to this signal to update the statusbar
+ */
+ void remoteTyping( const Kopete::Contact *contact, bool isTyping );
+
+ /**
+ * Signals that a an event has to be displayed in the statusbar.
+ * The chatwindow connects to this signal to update the statusbar.
+ */
+ void eventNotification( const QString& notificationText);
+
+ /**
+ * @brief A contact within the chat session changed his photo.
+ * Used to update the contacts photo in chat window.
+ */
+ void photoChanged();
+
+public slots:
+ /**
+ * @brief Got a typing notification from a user
+ */
+ void receivedTypingMsg( const Kopete::Contact *contact , bool isTyping = true );
+
+ /**
+ * Got a typing notification from a user. This is a convenience version
+ * of the above method that takes a QString contactId instead of a full
+ * Kopete::Contact
+ */
+ void receivedTypingMsg( const QString &contactId, bool isTyping = true );
+
+ /**
+ * @brief Got an event notification from a user.
+ * It will emit the signal eventNotification(). Use this slot in your protocols
+ * and plugins to change chatwindow statusBar text.
+ */
+ void receivedEventNotification( const QString& notificationText );
+
+ /**
+ * Show a message to the chatwindow, or append it to the queue.
+ * This is the function protocols HAVE TO call for both incoming and outgoing messages
+ * if the message must be showed in the chatwindow
+ */
+ void appendMessage( Kopete::Message &msg );
+
+ /**
+ * Add a contact to the session
+ * @param c is the contact
+ * @param suppress mean the there will be no automatic notifications in the chatwindow.
+ * (note that i don't like the param suppress at all. it is used in irc to show a different notification (with an info text)
+ * a QStringinfo would be more interesting, but it is also used to don't show the notification when entering in a channel)
+ */
+ void addContact( const Kopete::Contact *c, bool suppress = false );
+
+ /**
+ * Add a contact to the session with a pre-set initial status
+ * @param c is the contact
+ * @param initialStatus The initial contactOnlineStatus of the contact
+ * @param suppress mean the there will be no automatic notifications in the chatwindow.
+ * (note that i don't like the param suppress at all. it is used in irc to show a different notification (with an info text)
+ * a QStringinfo would be more interesting, but it is also used to don't show the notification when entering in a channel)
+ * @see contactOnlineStatus
+ */
+ void addContact( const Kopete::Contact *c, const Kopete::OnlineStatus &initialStatus, bool suppress = false );
+
+ /**
+ * Remove a contact from the session
+ * @param contact is the contact
+ * @param reason is the optional raison message showed in the chatwindow
+ * @param format The format of the message
+ * @param suppressNotification prevents a notification of the removal in the chat view. See note in @ref addContact
+ */
+ void removeContact( const Kopete::Contact *contact, const QString& reason = QString::null, Kopete::Message::MessageFormat format = Message::PlainText, bool suppressNotification = false );
+
+ /**
+ * Set if the KMM will be deleted when the chatwindow is deleted. It is useful if you want
+ * to keep the KMM alive even if the chatwindow is closed.
+ * Warning: if you set it to false, please keep in mind that you have to reset it to true
+ * later to delete it. In many case, you should never delete yourself the KMM, just call this
+ * this method.
+ * default is true.
+ * If there are no chatwindow when setting it to true, the kmm will be deleted.
+ *
+ * @deprecated use ref and deref
+ */
+ void setCanBeDeleted ( bool canBeDeleted );
+
+ /**
+ * reference count the chat session.
+ * the chat session may be deleted only if the count reach 0
+ * if you ref, don't forget to deref
+ * @see deref()
+ */
+ void ref();
+ /**
+ * dereference count the chat session
+ * if the reference counter reach 0 and there is no chat window open, the chat session will be deleted.
+ */
+ void deref();
+
+
+ /**
+ * Send a message to the user
+ */
+ void sendMessage( Kopete::Message &message );
+
+ /**
+ * Tell the KMM that the user is typing
+ * This method should be called only by a chatwindow. It emits @ref myselfTyping signal
+ */
+ void typing( bool t );
+
+ /**
+ * Protocols have to call this method when the last message sent has been correctly sent
+ * This will emit @ref messageSuccess signal. and allow the email window to get closed
+ */
+ void messageSucceeded();
+
+ /**
+ * Protcols have to call this method if they want to emit a notification when a nudge/buzz is received.
+ */
+ void emitNudgeNotification();
+
+ /**
+ * Raise the chat window and give him the focus
+ * It's used when the user wanted to activated (by clicking on the "view" button of a popup)
+ */
+ void raiseView();
+
+private slots:
+ void slotUpdateDisplayName();
+ void slotViewDestroyed();
+ void slotOnlineStatusChanged( Kopete::Contact *c, const Kopete::OnlineStatus &status, const Kopete::OnlineStatus &oldStatus );
+ void slotContactDestroyed( Kopete::Contact *contact );
+
+protected:
+ /**
+ * Create a message manager. This constructor is private, because the
+ * static factory method createSession() creates the object. You may
+ * not create instances yourself directly!
+ */
+ ChatSession( const Contact *user, ContactPtrList others,
+ Protocol *protocol, const char *name = 0 );
+
+ /**
+ * Set wether or not contact from this account may be invited in this chat.
+ * By default, it is set to false
+ * @see inviteContact()
+ * @see mayInvite()
+ */
+ void setMayInvite(bool);
+
+private:
+ KMMPrivate *d;
+
+ // FIXME: remove
+ friend class TemporaryKMMCallbackAppendMessageHandler;
+};
+
+}
+
+#endif
+
+// vim: set noet ts=4 sts=4 sw=4:
+