Copy the KDE 3.5 branch to branches/trinity for new KDE 3.5 features.

BUG:215923


git-svn-id: svn://anonsvn.kde.org/home/kde/branches/trinity/kdenetwork@1054174 283d02a7-25f6-0310-bc7c-ecb5cbfe19da

1 files changed, 405 insertions, 0 deletions

diff --git a/kopete/libkopete/kopetecontactlist.h b/kopete/libkopete/kopetecontactlist.h
new file mode 100644
index 00000000..fc6dd5f9
--- /dev/null
+++ b/kopete/libkopete/kopetecontactlist.h
@@ -0,0 +1,405 @@
+/*
+    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
+
+