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 | |
30 | namespace Kopete |
31 | { |
32 | |
33 | class MetaContact; |
34 | class Group; |
35 | class 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 | */ |
49 | class KOPETE_EXPORT ContactList : public QObject |
50 | { |
51 | Q_OBJECT |
52 | |
53 | public: |
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 | |
139 | public 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 | |
208 | signals: |
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 | |
264 | private 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 | |
274 | private: |
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 | |