kopete/libkopete/kopetecontactlist.h

   1 /*
   2     kopetecontactlist.h - Kopete's Contact List backend
   3
   4     Copyright (c) 2002      by Martijn Klingens       <klingens@kde.org>
   5     Copyright (c) 2002-2004 by Olivier Goffart        <ogoffart@kde.org>
   6
   7     Kopete    (c) 2002-2004 by the Kopete developers  <kopete-devel@kde.org>
   8
   9     *************************************************************************
  10     *                                                                       *
  11     * This library is free software; you can redistribute it and/or         *
  12     * modify it under the terms of the GNU Lesser General Public            *
  13     * License as published by the Free Software Foundation; either          *
  14     * version 2 of the License, or (at your option) any later version.      *
  15     *                                                                       *
  16     *************************************************************************
  17 */
  18
  19 #ifndef KOPETECONTACTLIST_H__
  20 #define KOPETECONTACTLIST_H__
  21
  22 #include <QtCore/QObject>
  23 #include <QtCore/QList>
  24
  25 #include <kurl.h>
  26
  27 #include "kopete_export.h"
  28
  29 namespace Kopete
  30 {
  31
  32 class MetaContact;
  33 class Group;
  34 class Contact;
  35
  36
  37 /**
  38  * @brief manage contacts and metacontact
  39  *
  40  * The contactList is a singleton you can uses with @ref ContactList::self()
  41  *
  42  * it let you get a list of metacontact with metaContacts()
  43  * Only metacontact which are on the contact list are returned.
  44  *
  45  * @author Martijn Klingens <klingens@kde.org>
  46  * @author Olivier Goffart <ogoffart@tiscalinet.be>
  47  */
  48 class KOPETE_EXPORT ContactList : public QObject
  49 {
  50         Q_OBJECT
  51
  52 public:
  53         /**
  54          * The contact list is a singleton object. Use this method to retrieve
  55          * the instance.
  56          */
  57         static ContactList *self();
  58         ~ContactList();
  59
  60         /**
  61          * @brief return a list of all metacontact of the contact list
  62          * Retrieve the list of all available meta contacts.
  63          * The returned QPtrList is not the internally used variable, so changes
  64          * to it won't propagate into the actual contact list. This can be
  65          * useful if you need a subset of the contact list, because you can
  66          * simply filter the result set as you wish without worrying about
  67          * side effects.
  68          * The contained MetaContacts are obviously _not_ duplicates, so
  69          * changing those *will* have the expected result :-)
  70          */
  71         QList<MetaContact *> metaContacts() const;
  72
  73         /**
  74          * @return all groups
  75          */
  76         QList<Group *> groups() const;
  77
  78         /**
  79          * Return the metacontact referenced by the given id. is none is found, return 0L
  80          * @sa MetaContact::metaContactId()
  81          */
  82         MetaContact *metaContact( const QString &metaContactId ) const;
  83
  84         /**
  85          * return the group with the given unique id. if none is found return 0L
  86          */
  87         Group * group(unsigned int groupId) const;
  88
  89
  90         /**
  91          * @brief find a contact in the contact list.
  92          * Browse in each metacontact of the list to find the contact with the given ID.
  93          * @param protocolId the @ref Plugin::pluginId() of the protocol ("MSNProtocol")
  94          * @param accountId the @ref Account::accountId()
  95          * @param contactId the @ref Contact::contactId()
  96          * @return the contact with the parameters, or 0L if not found.
  97          */
  98         Contact *findContact( const QString &protocolId, const QString &accountId, const QString &contactId ) const;
  99
 100         /**
 101          * Find a contact by display name. Returns the first match.
 102          */
 103         MetaContact *findMetaContactByDisplayName( const QString &displayName ) const;
 104
 105         /**
 106          * Find a meta contact by its contact id. Returns the first match.
 107          */
 108         MetaContact *findMetaContactByContactId( const QString &contactId ) const;
 109
 110         /**
 111          * @brief find a group with his displayName
 112          * If a group already exists with the given name and the given type, the existing group will be returned.
 113          * Otherwise, a new group will be created.
 114          * @param displayName is the display name to search
 115          * @param type is the Group::GroupType to search, the default value is group::Normal
 116          * @return always a valid Group
 117          */
 118         Group * findGroup( const QString &displayName, int type = 0/*Group::Normal*/ );
 119
 120         /**
 121          * return the list of metacontact actually selected in the contact list UI
 122          */
 123         QList<MetaContact *> selectedMetaContacts() const;
 124
 125         /**
 126          * return the list of groups actualy selected in the contact list UI
 127          */
 128         QList<Group *> selectedGroups() const ;
 129
 130         /**
 131           * return the metacontact that represent the user itself.
 132           * This metacontact should be the parent of every Kopete::Account::myself() contacts.
 133           *
 134           * This metacontact is not in the contact list.
 135           */
 136         MetaContact* myself();
 137
 138 public slots:
 139         /**
 140          * Add metacontacts into the contact list
 141          * When calling this method, contacts have to be already placed in the correct group.
 142          * If contacts are not in a group, they will be added to the top-level group.
 143          * It is also better if the MetaContacts could also be completely created, i.e: all contacts already in it
 144          */
 145         void addMetaContacts( QList<MetaContact *> metaContacts );
 146
 147         /**
 148          * Add the metacontact into the contact list
 149          * When calling this method, the contact has to be already placed in the correct group.
 150          * If the contact is not in a  group, it will be added to the top-level group.
 151          * It is also better if the MetaContact could also be completely created, i.e: all contacts already in it
 152          */
 153         void addMetaContact( Kopete::MetaContact *c );
 154
 155         /**
 156          * Remove a metacontact from the contact list.
 157          * This method delete itself the metacontact.
 158          */
 159         void removeMetaContact( Kopete::MetaContact *contact );
 160
 161         /**
 162          * Add groups
 163          * each group must be added on the list after his creation.
 164          */
 165         void addGroups( QList<Group *> groups );
 166
 167         /**
 168          * Add a group
 169          * each group must be added on the list after his creation.
 170          */
 171         void addGroup(Kopete::Group *);
 172
 173         /**
 174          * Remove a group
 175          * this method delete the group
 176          */
 177         void removeGroup(Kopete::Group *);
 178
 179         /**
 180          * Set which items are selected in the ContactList GUI.
 181          * This method has to be called by the contact list UI side.
 182          * it stores the selected items, and emits signals
 183          */
 184          void setSelectedItems(QList<MetaContact *> metaContacts , QList<Group *> groups);
 185
 186         /**
 187          * @internal
 188          * Load the contact list
 189          */
 190         void load();
 191
 192         void save();
 193
 194 signals:
 195         /**
 196          * A meta contact was added to the contact list. Interested classes
 197          * ( like the listview widgets ) can connect to this signal to receive
 198          * the newly added contacts.
 199          */
 200         void metaContactAdded( Kopete::MetaContact *mc );
 201
 202         /**
 203          * A metacontact has just been removed.  and will be soon deleted
 204          */
 205         void metaContactRemoved( Kopete::MetaContact *mc );
 206
 207         /**
 208          * A group has just been added
 209          */
 210         void groupAdded( Kopete::Group * );
 211
 212         /**
 213          * A group has just been removed
 214          */
 215         void groupRemoved( Kopete::Group * );
 216
 217         /**
 218          * A group has just been renamed
 219          */
 220         void groupRenamed(Kopete::Group *, const QString & oldname);
 221
 222         /**
 223          * A contact has been added to a group
 224          */
 225         void metaContactAddedToGroup( Kopete::MetaContact *mc, Kopete::Group *to );
 226         /**
 227          * A contact has been removed from a group
 228          */
 229         void metaContactRemovedFromGroup( Kopete::MetaContact *mc, Kopete::Group *from );
 230
 231         /**
 232          * This signal is emit when the selection has changed, it is emitted after the following slot
 233          * Warning: Do not delete any contacts in slots connected to this signal.  (it is the warning in the QListView::selectionChanged() doc)
 234          */
 235         void selectionChanged();
 236         /**
 237          * This signal is emitted each time the selection has changed. the bool is set to true if only one meta contact has been selected,
 238          * and set to false if none, or several contacts are selected
 239          * you can connect this signal to KAction::setEnabled if you have an action which is applied to only one contact
 240          */
 241         void metaContactSelected(bool);
 242
 243 private slots:
 244         /**
 245          * Called when the contact list changes. Flags the list dirty and schedules a save for a little while later.
 246          */
 247         void slotSaveLater();
 248         /**
 249          * Called on contact list load or when KABC has changed, to check if we need to update our contact list from there.
 250          */
 251         void slotKABCChanged();
 252
 253 private:
 254         /**
 255          * Private constructor: we are a singleton
 256          */
 257         ContactList();
 258
 259         static ContactList *s_self;
 260         class Private;
 261         Private *d;
 262 };
 263
 264 } //END namespace Kopete
 265
 266
 267 #endif
 268
 269