kopete/libkopete

Kopete::ChatSession

Kopete::ChatSession Class Reference

#include <kopetechatsession.h>

Inheritance diagram for Kopete::ChatSession:

[legend]

List of all members.

Detailed Description

Author:: Duncan Mac-Vicar Prett <duncan@kde.org>

Author:

Daniel Stone <dstone@kde.org>

Martijn Klingens <klingens@kde.org>

Olivier Goffart <ogoffart@kde.org>

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 messageSent() signals to send the message, and can append received message with 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.

Definition at line 72 of file kopetechatsession.h.


Public Types
enum	Form { Small, Chatroom }
Public Slots
void	addContact (const Kopete::Contact *c, const Kopete::OnlineStatus &initialStatus, bool suppress=false)
void	addContact (const Kopete::Contact *c, bool suppress=false)
void	appendMessage (Kopete::Message &msg)
void	deref ()
void	emitNudgeNotification ()
void	messageSucceeded ()
void	raiseView ()
void	receivedEventNotification (const QString &notificationText)
void	receivedMessageState (uint messageId, Kopete::Message::MessageState state)
void	receivedTypingMsg (const QString &contactId, bool isTyping=true)
void	receivedTypingMsg (const Kopete::Contact *contact, bool isTyping=true)
void	ref ()
void	removeContact (const Kopete::Contact *contact, const QString &reason=QString(), Qt::TextFormat format=Qt::PlainText, bool suppressNotification=false)
void	sendMessage (Kopete::Message &message)
void	setCanBeDeleted (bool canBeDeleted)
void	typing (bool t)
Signals
void	closing (Kopete::ChatSession *kmm)
void	contactAdded (const Kopete::Contact *contact, bool suppress)
void	contactRemoved (const Kopete::Contact *contact, const QString &reason, Qt::TextFormat format=Qt::PlainText, bool contactRemoved=false)
void	displayNameChanged ()
void	eventNotification (const QString &notificationText)
void	messageAppended (Kopete::Message &msg, Kopete::ChatSession *kmm=0L)
void	messageReceived (Kopete::Message &msg, Kopete::ChatSession *kmm=0L)
void	messageSent (Kopete::Message &msg, Kopete::ChatSession *kmm=0L)
void	messageStateChanged (uint messageId, Kopete::Message::MessageState state)
void	messageSuccess ()
void	myselfTyping (bool isTyping)
void	onlineStatusChanged (Kopete::Contact *, const Kopete::OnlineStatus &, const Kopete::OnlineStatus &)
void	photoChanged ()
void	remoteTyping (const Kopete::Contact *contact, bool isTyping)
Public Member Functions
Account *	account () const
MessageHandlerChain::Ptr	chainForDirection (Message::MessageDirection dir)
const OnlineStatus	contactOnlineStatus (const Contact *contact) const
const QString	displayName ()
Form	form () const
virtual void	inviteContact (const QString &contactId)
bool	mayInvite () const
const ContactPtrList &	members () const
const Contact *	myself () const
Protocol *	protocol () const
void	setContactOnlineStatus (const Contact *contact, const OnlineStatus &newStatus)
void	setDisplayName (const QString &displayName)
KopeteView *	view (bool canCreate=false, const QString &requestedPlugin=QString())
	~ChatSession ()
Protected Member Functions
	ChatSession (const Contact user, ContactPtrList others, Protocol protocol, Form form=Small)
void	setMayInvite (bool)

Member Enumeration Documentation

enum Kopete::ChatSession::Form

Describes the form of this chat session.

Enumerator:

Small	The chat is a small group or 1:1 chat.
Chatroom	Chat with many members and high traffic.

Definition at line 83 of file kopetechatsession.h.

Constructor & Destructor Documentation

Kopete::ChatSession::~ChatSession ( )

Delete a chat manager instance You shouldn't delete the KMM yourself.

it will be deleted when the chatwindow is closed see also setCanBeDeleted() , deref()

Definition at line 95 of file kopetechatsession.cpp.

Kopete::ChatSession::ChatSession	(	const Contact *	user,
		Kopete::ContactPtrList	others,
		Kopete::Protocol *	protocol,
		Form	form = `Small`
	)			`[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!

Definition at line 65 of file kopetechatsession.cpp.

Member Function Documentation

Kopete::Account * Kopete::ChatSession::account ( ) const

get the account

Returns:: the account

Note:: Can be 0 if account was already deleted

Definition at line 477 of file kopetechatsession.cpp.

void Kopete::ChatSession::addContact	(	const Kopete::Contact *	c,
		const Kopete::OnlineStatus &	initialStatus,
		bool	suppress = `false`
	)			`[slot]`

Add a contact to the session with a pre-set initial status.

Parameters:

	c	is the contact
	initialStatus	The initial contactOnlineStatus of the contact
	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 also:: contactOnlineStatus

Definition at line 300 of file kopetechatsession.cpp.

void Kopete::ChatSession::addContact	(	const Kopete::Contact *	c,
		bool	suppress = `false`
	)			`[slot]`

Add a contact to the session.

Parameters:

	c	is the contact
	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)

Definition at line 307 of file kopetechatsession.cpp.

void Kopete::ChatSession::appendMessage ( Kopete::Message & msg ) [slot]

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

Definition at line 273 of file kopetechatsession.cpp.

Kopete::MessageHandlerChain::Ptr Kopete::ChatSession::chainForDirection ( Message::MessageDirection dir )

Returns the message handler chain for the message direction dir.

Definition at line 233 of file kopetechatsession.cpp.

void Kopete::ChatSession::closing ( Kopete::ChatSession * kmm ) [signal]

the KMM will be deleted Used by a Kopete::ChatSession to signal that it is closing.

void Kopete::ChatSession::contactAdded	(	const Kopete::Contact *	contact,
		bool	suppress
	)			`[signal]`

a new contact is now in the chat

const Kopete::OnlineStatus Kopete::ChatSession::contactOnlineStatus ( const Contact * contact ) const

get the status of a contact.

see setContactOnlineStatus()

Definition at line 123 of file kopetechatsession.cpp.

void Kopete::ChatSession::contactRemoved	(	const Kopete::Contact *	contact,
		const QString &	reason,
		Qt::TextFormat	format = `Qt::PlainText`,
		bool	contactRemoved = `false`
	)			`[signal]`

a contact is no longer in this chat

void Kopete::ChatSession::deref ( ) [slot]

dereference count the chat session if the reference counter reach 0 and there is no chat window open, the chat session will be deleted.

Definition at line 444 of file kopetechatsession.cpp.

const QString Kopete::ChatSession::displayName ( )

The caption of the chat.

Used for named chats

Definition at line 131 of file kopetechatsession.cpp.

void Kopete::ChatSession::displayNameChanged ( ) [signal]

The name of the chat is changed.

void Kopete::ChatSession::emitNudgeNotification ( ) [slot]

Protocols have to call this method if they want to emit a notification when a nudge/buzz is received.

Definition at line 268 of file kopetechatsession.cpp.

void Kopete::ChatSession::eventNotification ( const QString & notificationText ) [signal]

Signals that a an event has to be displayed in the statusbar.

The chatwindow connects to this signal to update the statusbar.

Kopete::ChatSession::Form Kopete::ChatSession::form ( ) const

Get the form of this chatsession.

This is a hint to the UI so it can present the chat appropriately

Definition at line 528 of file kopetechatsession.cpp.

void Kopete::ChatSession::inviteContact ( const QString & contactId ) [virtual]

this method is called when a contact is dragged to the contact list.

contactId is the id of the contact. the contact is supposed to be of the same account as the account() but we can't be sure the Kopete::Contact is really on the contact list

It is possible to drag contact only if mayInvite return true

the default implementaiton do nothing

Definition at line 511 of file kopetechatsession.cpp.

bool Kopete::ChatSession::mayInvite ( ) const

says if you may invite contact from the same account to this chat with inviteContact

See also:: setMayInvite

Returns:: true if it is possible to invite contact to this chat.

Definition at line 506 of file kopetechatsession.cpp.

const Kopete::ContactPtrList & Kopete::ChatSession::members ( ) const

Get a list of all contacts in the session.

Definition at line 183 of file kopetechatsession.cpp.

void Kopete::ChatSession::messageAppended	(	Kopete::Message &	msg,
		Kopete::ChatSession *	kmm = `0L`
	)			`[signal]`

a message will be soon shown in the chatwindow.

See Kopete::ChatSessionManager::aboutToDisplay() signal

void Kopete::ChatSession::messageReceived	(	Kopete::Message &	msg,
		Kopete::ChatSession *	kmm = `0L`
	)			`[signal]`

a message will be soon received See Kopete::ChatSessionManager::aboutToReceive() signal

void Kopete::ChatSession::messageSent	(	Kopete::Message &	msg,
		Kopete::ChatSession *	kmm = `0L`
	)			`[signal]`

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 appendMessage() and messageSucceeded() See also Kopete::ChatSessionManager::aboutToSend() signal

void Kopete::ChatSession::messageStateChanged	(	uint	messageId,
		Kopete::Message::MessageState	state
	)			`[signal]`

Signals that a message has changed its state.

The chat window connects to this signal to update the message in chat view.

void Kopete::ChatSession::messageSucceeded ( ) [slot]

Protocols have to call this method when the last message sent has been correctly sent This will emit messageSuccess signal.

and allow the email window to get closed

Definition at line 263 of file kopetechatsession.cpp.

void Kopete::ChatSession::messageSuccess ( ) [signal]

The last message has finaly successfully been sent.

const Kopete::Contact * Kopete::ChatSession::myself ( ) const

Get the local user in the session.

Returns:: the local user in the session, same as account()->myself()

Note:: Can be 0 if local user was already deleted during account destruction

Definition at line 188 of file kopetechatsession.cpp.

void Kopete::ChatSession::myselfTyping ( bool isTyping ) [signal]

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

Parameters:

isTyping

say if the user is typing or not

void Kopete::ChatSession::onlineStatusChanged	(	Kopete::Contact *	,
		const Kopete::OnlineStatus &	,
		const Kopete::OnlineStatus &
	)			`[signal]`

a contact in this chat has changed his status

void Kopete::ChatSession::photoChanged ( ) [signal]

A contact within the chat session changed his photo.

Used to update the contacts photo in chat window.

Kopete::Protocol * Kopete::ChatSession::protocol ( ) const

Get the protocol being used.

Returns:: the protocol

Definition at line 193 of file kopetechatsession.cpp.

void Kopete::ChatSession::raiseView ( ) [slot]

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).

Definition at line 521 of file kopetechatsession.cpp.

void Kopete::ChatSession::receivedEventNotification ( const QString & notificationText ) [slot]

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.

Definition at line 423 of file kopetechatsession.cpp.

void Kopete::ChatSession::receivedMessageState	(	uint	messageId,
		Kopete::Message::MessageState	state
	)			`[slot]`

Change state of message.

It will emit the signal messageStateChanged(). Use this slot in your protocols and plugins to change message state.

Definition at line 428 of file kopetechatsession.cpp.

void Kopete::ChatSession::receivedTypingMsg	(	const QString &	contactId,
		bool	isTyping = `true`
	)			`[slot]`

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

Definition at line 402 of file kopetechatsession.cpp.

void Kopete::ChatSession::receivedTypingMsg	(	const Kopete::Contact *	contact,
		bool	isTyping = `true`
	)			`[slot]`

Got a typing notification from a user.

Definition at line 397 of file kopetechatsession.cpp.

void Kopete::ChatSession::ref ( ) [slot]

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 also:: deref()

Definition at line 440 of file kopetechatsession.cpp.

void Kopete::ChatSession::remoteTyping	(	const Kopete::Contact *	contact,
		bool	isTyping
	)			`[signal]`

Signals that a remote user is typing a message.

the chatwindow connects to this signal to update the statusbar

void Kopete::ChatSession::removeContact	(	const Kopete::Contact *	contact,
		const QString &	reason = `QString()`,
		Qt::TextFormat	format = `Qt::PlainText`,
		bool	suppressNotification = `false`
	)			`[slot]`

Remove a contact from the session.

Parameters:

	contact	is the contact
	reason	is the optional raison message showed in the chatwindow
	format	The format of the message
	suppressNotification	prevents a notification of the removal in the chat view. See note in addContact

Definition at line 362 of file kopetechatsession.cpp.

void Kopete::ChatSession::sendMessage ( Kopete::Message & message ) [slot]

Send a message to the user.

Definition at line 245 of file kopetechatsession.cpp.

void Kopete::ChatSession::setCanBeDeleted ( bool canBeDeleted ) [slot]

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

Definition at line 433 of file kopetechatsession.cpp.

void Kopete::ChatSession::setContactOnlineStatus	(	const Contact *	contact,
		const OnlineStatus &	newStatus
	)

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

Definition at line 114 of file kopetechatsession.cpp.

void Kopete::ChatSession::setDisplayName ( const QString & displayName )

change the displayname

change the display name of the chat

Definition at line 141 of file kopetechatsession.cpp.

void Kopete::ChatSession::setMayInvite ( bool b ) [protected]

Set whether or not contact from this account may be invited in this chat.

By default, it is set to false

See also:: inviteContact()
mayInvite()

Definition at line 516 of file kopetechatsession.cpp.

void Kopete::ChatSession::typing ( bool t ) [slot]

Tell the KMM that the user is typing This method should be called only by a chatwindow.

It emits myselfTyping signal

Definition at line 418 of file kopetechatsession.cpp.

KopeteView * Kopete::ChatSession::view	(	bool	canCreate = `false`,
		const QString &	requestedPlugin = `QString()`
	)

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

Parameters:

	canCreate	create a new one if it does not exist
	requestedPlugin	Specifies the view plugin to use if we have to create one.

Definition at line 451 of file kopetechatsession.cpp.

The documentation for this class was generated from the following files:

kopete/libkopete

Kopete::ChatSession Class Reference

Detailed Description

Public Types

Public Slots

Signals

Public Member Functions

Protected Member Functions

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

kopete/libkopete

kdenetwork