summaryrefslogtreecommitdiffstats
path: root/kopete/libkopete/kopetecontactlist.h
diff options
context:
space:
mode:
Diffstat (limited to 'kopete/libkopete/kopetecontactlist.h')
-rw-r--r--kopete/libkopete/kopetecontactlist.h405
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
+
+