/* kopetechatsession.h - Manages all chats Copyright (c) 2002 by Duncan Mac-Vicar Prett Copyright (c) 2002 by Daniel Stone Copyright (c) 2002-2003 by Martijn Klingens Copyright (c) 2002-2004 by Olivier Goffart Copyright (c) 2003 by Jason Keirstead Copyright (c) 2005 by Michaël Larouche Kopete (c) 2002-2003 by the Kopete developers ************************************************************************* * * * 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 #include #include #include #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 ContactPtrList; typedef TQValueList MessageList; /** * @author Duncan Mac-Vicar Prett * @author Daniel Stone * @author Martijn Klingens * @author Olivier Goffart * @author Jason Keirstead * * 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