You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
404 lines
13 KiB
404 lines
13 KiB
/*
|
|
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;
|
|
|
|
TQ_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() );
|
|
|
|
/**
|
|
* 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 TQStringinfo 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 TQStringinfo 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(), 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
|