tdenetwork/kopete/libkopete/kopetechatsession.h

/*
    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 <tqobject.h>
#include <tqptrlist.h>
#include <tqvaluelist.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 TQPtrList<Contact>   ContactPtrList;
typedef TQValueList<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 TQObject , 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 TQString displayName();

	/**
	 * @brief change the displayname
	 *
	 * change the display name of the chat
	 */
	void setDisplayName( const TQString &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 TQString &requestedPlugin = TQString::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 TQString &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 TQString &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 TQString& 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 TQString contactId instead of a full
	 * Kopete::Contact
	 */
	void receivedTypingMsg( const TQString &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 TQString& 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 TQString& reason = TQString::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: