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.
406 lines
12 KiB
406 lines
12 KiB
/*
|
|
kopetecontactlist.h - Kopete's Contact List backend
|
|
|
|
Copyright (c) 2002 by Martijn Klingens <klingens@kde.org>
|
|
Copyright (c) 2002-2004 by Olivier Goffart <ogoffart @ kde.org>
|
|
|
|
Kopete (c) 2002-2004 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 KOPETECONTACTLIST_H__
|
|
#define KOPETECONTACTLIST_H__
|
|
|
|
#include <qobject.h>
|
|
#include <qptrlist.h>
|
|
|
|
#include "kopete_export.h"
|
|
|
|
class KURL;
|
|
class QDomDocument;
|
|
|
|
|
|
namespace Kopete
|
|
{
|
|
|
|
class MetaContact;
|
|
class Group;
|
|
class Contact;
|
|
|
|
|
|
/**
|
|
* @brief manage contacts and metacontact
|
|
*
|
|
* The contactList is a singleton you can uses with @ref ContactList::self()
|
|
*
|
|
* it let you get a list of metacontact with metaContacts()
|
|
* Only metacontact which are on the contactlist are returned.
|
|
*
|
|
* @author Martijn Klingens <klingens@kde.org>
|
|
* @author Olivier Goffart <ogoffart@tiscalinet.be>
|
|
*/
|
|
class KOPETE_EXPORT ContactList : public QObject
|
|
{
|
|
Q_OBJECT
|
|
|
|
public:
|
|
/**
|
|
* The contact list is a singleton object. Use this method to retrieve
|
|
* the instance.
|
|
*/
|
|
static ContactList *self();
|
|
~ContactList();
|
|
|
|
/**
|
|
* @brief return a list of all metacontact of the contactlist
|
|
* Retrieve the list of all available meta contacts.
|
|
* The returned QPtrList is not the internally used variable, so changes
|
|
* to it won't propagate into the actual contact list. This can be
|
|
* useful if you need a subset of the contact list, because you can
|
|
* simply filter the result set as you wish without worrying about
|
|
* side effects.
|
|
* The contained MetaContacts are obviously _not_ duplicates, so
|
|
* changing those *will* have the expected result :-)
|
|
*/
|
|
QPtrList<MetaContact> metaContacts() const;
|
|
|
|
/**
|
|
* @return all groups
|
|
*/
|
|
QPtrList<Group> groups() const;
|
|
|
|
/**
|
|
* Return the metacontact referenced by the given id. is none is found, return 0L
|
|
* @sa MetaContact::metaContactId()
|
|
*/
|
|
MetaContact *metaContact( const QString &metaContactId ) const;
|
|
|
|
/**
|
|
* return the group with the given unique id. if none is found return 0L
|
|
*/
|
|
Group * group(unsigned int groupId) const;
|
|
|
|
|
|
/**
|
|
* @brief find a contact in the contactlist.
|
|
* Browse in each metacontact of the list to find the contact with the given ID.
|
|
* @param protocolId the @ref Plugin::pluginId() of the protocol ("MSNProtocol")
|
|
* @param accountId the @ref Account::accountId()
|
|
* @param contactId the @ref Contact::contactId()
|
|
* @return the contact with the parameters, or 0L if not found.
|
|
*/
|
|
Contact *findContact( const QString &protocolId, const QString &accountId, const QString &contactId ) const;
|
|
|
|
/**
|
|
* Find a contact by display name. Returns the first match.
|
|
*/
|
|
MetaContact *findMetaContactByDisplayName( const QString &displayName ) const;
|
|
|
|
/**
|
|
* Find a meta contact by its contact id. Returns the first match.
|
|
*/
|
|
MetaContact *findMetaContactByContactId( const QString &contactId ) const;
|
|
|
|
/**
|
|
* @brief find a group with his displayName
|
|
* If a group already exists with the given name and the given type, the existing group will be returned.
|
|
* Otherwise, a new group will be created.
|
|
* @param displayName is the display name to search
|
|
* @param type is the Group::GroupType to search, the default value is group::Normal
|
|
* @return always a valid Group
|
|
*/
|
|
Group * findGroup( const QString &displayName, int type = 0/*Group::Normal*/ );
|
|
|
|
/**
|
|
* return the list of metacontact actually selected in the contactlist UI
|
|
*/
|
|
QPtrList<MetaContact> selectedMetaContacts() const;
|
|
|
|
/**
|
|
* return the list of groups actualy selected in the contactlist UI
|
|
*/
|
|
QPtrList<Group> selectedGroups() const ;
|
|
|
|
/**
|
|
* return the metacontact that represent the user itself.
|
|
* This metacontact should be the parent of every Kopete::Account::myself() contacts.
|
|
*
|
|
* This metacontact is not in the contactlist.
|
|
*/
|
|
MetaContact* myself();
|
|
|
|
|
|
public slots:
|
|
|
|
/**
|
|
* Add the metacontact into the contact list
|
|
* When calling this method, the contact has to be already placed in the correct group.
|
|
* If the contact is not in a group, it will be added to the top-level group.
|
|
* It is also better if the MetaContact could also be completely created, i.e: all contacts already in it
|
|
*/
|
|
void addMetaContact( Kopete::MetaContact *c );
|
|
|
|
/**
|
|
* Remove a metacontact from the contactlist.
|
|
* This method delete itself the metacontact.
|
|
*/
|
|
void removeMetaContact( Kopete::MetaContact *contact );
|
|
|
|
/**
|
|
* Add a group
|
|
* each group must be added on the list after his creation.
|
|
*/
|
|
void addGroup(Kopete::Group *);
|
|
|
|
/**
|
|
* Remove a group
|
|
* this method delete the group
|
|
*/
|
|
void removeGroup(Kopete::Group *);
|
|
|
|
/**
|
|
* Set which items are selected in the ContactList GUI.
|
|
* This method has to be called by the contactlist UI side.
|
|
* it stores the selected items, and emits signals
|
|
*/
|
|
void setSelectedItems(QPtrList<MetaContact> metaContacts , QPtrList<Group> groups);
|
|
|
|
/**
|
|
* Apply the global identity.
|
|
*/
|
|
void loadGlobalIdentity();
|
|
|
|
signals:
|
|
/**
|
|
* A meta contact was added to the contact list. Interested classes
|
|
* ( like the listview widgets ) can connect to this signal to receive
|
|
* the newly added contacts.
|
|
*/
|
|
void metaContactAdded( Kopete::MetaContact *mc );
|
|
|
|
/**
|
|
* A metacontact has just been removed. and will be soon deleted
|
|
*/
|
|
void metaContactRemoved( Kopete::MetaContact *mc );
|
|
|
|
/**
|
|
* A group has just been added
|
|
*/
|
|
void groupAdded( Kopete::Group * );
|
|
|
|
/**
|
|
* A group has just been removed
|
|
*/
|
|
void groupRemoved( Kopete::Group * );
|
|
|
|
/**
|
|
* A group has just been renamed
|
|
*/
|
|
void groupRenamed(Kopete::Group *, const QString & oldname);
|
|
|
|
/**
|
|
* A contact has been added to a group
|
|
*/
|
|
void metaContactAddedToGroup( Kopete::MetaContact *mc, Kopete::Group *to );
|
|
/**
|
|
* A contact has been removed from a group
|
|
*/
|
|
void metaContactRemovedFromGroup( Kopete::MetaContact *mc, Kopete::Group *from );
|
|
|
|
/**
|
|
* This signal is emit when the selection has changed, it is emitted after the following slot
|
|
* Warning: Do not delete any contacts in slots connected to this signal. (it is the warning in the QListView::selectionChanged() doc)
|
|
*/
|
|
void selectionChanged();
|
|
/**
|
|
* This signal is emitted each time the selection has changed. the bool is set to true if only one meta contact has been selected,
|
|
* and set to false if none, or several contacts are selected
|
|
* you can connect this signal to KAction::setEnabled if you have an action which is applied to only one contact
|
|
*/
|
|
void metaContactSelected(bool);
|
|
|
|
/**
|
|
* This signal is emitted each time a global identity field change.
|
|
* HOWTO use:
|
|
*
|
|
* - Connect signal globalIdentityChanged(const QString &key, const QVariant
|
|
* &value) to a slot in your derivate Account class (the best
|
|
* place to put it).
|
|
* - In the slot:
|
|
* - Check the key you want to be sync with global identity.
|
|
* - Update the myself contact and/or update on server.
|
|
*
|
|
* For now, when photo is changed, it always send the photo file path.
|
|
*
|
|
* Connect signal in your Account constructor:
|
|
* @code
|
|
* connect(Kopete::ContactList::self(), SIGNAL(globalIdentityChanged(const QString&, const QVariant&)), SLOT(slotglobalIdentityChanged(const QString&, const QVariant&)));
|
|
* @endcode
|
|
*
|
|
* Example of a typical implemented slot:
|
|
* @code
|
|
* void slotGlobalIdentityChanged(const QString &key, const QVariant &value)
|
|
* {
|
|
* if(key == Kopete::Global::Properties::self()->nickName().key())
|
|
* {
|
|
* myself()->setProperty(protocol()->propNickname, value.toString());
|
|
* this->slotUpdateUserInfo();
|
|
* }
|
|
* else if(key == Kopete::Global::Properties::self()->photo().key())
|
|
* {
|
|
* myself()->setProperty(protocol()->propPhotoUrl, value.toString());
|
|
* this->slotUpdateDisplayPicture();
|
|
* }
|
|
* }
|
|
* @endcode
|
|
*/
|
|
void globalIdentityChanged( const QString &key, const QVariant &value );
|
|
|
|
private slots:
|
|
/**
|
|
* Called when the contact list changes. Flags the list dirty and schedules a save for a little while later.
|
|
*/
|
|
void slotSaveLater();
|
|
/**
|
|
* Called on contactlist load or when KABC has changed, to check if we need to update our contactlist from there.
|
|
*/
|
|
void slotKABCChanged();
|
|
|
|
/**
|
|
* Called when the myself displayName changed.
|
|
*/
|
|
void slotDisplayNameChanged();
|
|
|
|
/**
|
|
* Called when the myself photo changed.
|
|
*/
|
|
void slotPhotoChanged();
|
|
|
|
private:
|
|
|
|
/**
|
|
* Convert the contact list from an older version
|
|
*/
|
|
void convertContactList( const QString &fileName, uint fromVersion, uint toVersion );
|
|
|
|
|
|
/**
|
|
* Private constructor: we are a singleton
|
|
*/
|
|
ContactList();
|
|
|
|
static ContactList *s_self;
|
|
class Private;
|
|
Private *d;
|
|
|
|
public: //TODO I think all theses method should be moved to the decop interface.
|
|
/**
|
|
* Return all meta contacts
|
|
*/
|
|
QStringList contacts() const;
|
|
|
|
/**
|
|
* Return all meta contacts that are reachable
|
|
*/
|
|
QStringList reachableContacts() const;
|
|
|
|
/**
|
|
* Return all contacts that are online
|
|
*/
|
|
QPtrList<Contact> onlineContacts() const;
|
|
|
|
/**
|
|
* Overloaded method of @ref onlineContacts() that only returns
|
|
* the online contacts for a single protocol
|
|
*/
|
|
QPtrList<Contact> onlineContacts( const QString &protocolId ) const;
|
|
|
|
/**
|
|
* Return all meta contacts that are online
|
|
*/
|
|
QPtrList<MetaContact> onlineMetaContacts() const;
|
|
|
|
/**
|
|
* Overloaded method of @ref onlineMetaContacts() that only returns
|
|
* the online meta contacts for a single protocol
|
|
*/
|
|
QPtrList<MetaContact> onlineMetaContacts( const QString &protocolId ) const;
|
|
|
|
/**
|
|
* Returns all contacts which can accept file transfers
|
|
*/
|
|
QStringList fileTransferContacts() const;
|
|
|
|
QStringList contactFileProtocols( const QString &displayName);
|
|
|
|
/**
|
|
* Return all meta contacts with their current status
|
|
*
|
|
* FIXME: Do we *need* this one? Sounds error prone to me, because
|
|
* nicknames can contain parentheses too. - Martijn
|
|
*/
|
|
QStringList contactStatuses() const;
|
|
|
|
|
|
/**
|
|
* Exposed via DCOP in kopeteiface
|
|
* Used to send a file to a MetaContact using the highest ranked protocol
|
|
*
|
|
* FIXME: We need to change this to use a unique ID instead of the displayName
|
|
*
|
|
* @param displayName Metacontact to send file to
|
|
* @param sourceURL The file we are sending
|
|
* @param altFileName (Optional) An alternate filename for the file we are sending
|
|
* @param fileSize (Optional) The size of the file
|
|
*/
|
|
void sendFile(const QString &displayName, const KURL &sourceURL,
|
|
const QString &altFileName = QString::null, const long unsigned int fileSize = 0L);
|
|
|
|
/**
|
|
* Open a chat to a contact, and optionally set some initial text
|
|
*/
|
|
void messageContact( const QString &displayName, const QString &messageText = QString::null );
|
|
|
|
public slots:
|
|
/**
|
|
* @internal
|
|
* Load the contact list
|
|
*
|
|
* FIXME: Use a better way, without exposing the XML backend, though.
|
|
*/
|
|
void load();
|
|
|
|
void save();
|
|
|
|
private:
|
|
/**
|
|
* Return a XML representation of the contact list
|
|
*/
|
|
const QDomDocument toXML();
|
|
|
|
/**
|
|
* Load the contact list from XML file
|
|
*/
|
|
void loadXML();
|
|
|
|
/**
|
|
* Save the contact list to XML file
|
|
*/
|
|
void saveXML();
|
|
};
|
|
|
|
} //END namespace Kopete
|
|
|
|
|
|
#endif
|
|
|
|
|