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