summaryrefslogtreecommitdiffstats
path: root/kopete/libkopete/kopetemetacontact.h
blob: b7f9fbc72a2c7fee21e9bd65c919c4349254c512 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
/*
    kopetemetacontact.h - Kopete Meta Contact

    Copyright (c) 2002-2003 by Martijn Klingens       <klingens@kde.org>
    Copyright (c) 2002-2005 by Duncan Mac-Vicar Prett <duncan@kde.org>
    Copyright (c) 2002-2005 by Olivier Goffart        <ogoffart @ kde.org>
    Copyright (c) 2003      by Will Stephenson        <will@stevello.free-online.co.uk>

    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 kopetemetacontact_h__
#define kopetemetacontact_h__

#include "kopetecontactlistelement.h"
#include <tqptrlist.h>
#include <tqstring.h>

#include <kdemacros.h>
#include "kopete_export.h"

#include "kopetenotifydataobject.h"
#include "kopetecontactlistelement.h"
#include "kopeteonlinestatus.h"

class TQDomNode;

class KURL;

namespace Kopete {


class Plugin;
class Group;
class Picture;

/**
 * @author Will Stephenson <will@stevello.free-online.co.uk>
 * @author Martijn Klingens <klingens@kde.org>
 * @author Duncan Mac-Vicar Prett <duncan@kde.org>
 * @author Olivier Goffart <ogoffart@tiscalinet.be>
 *
 * A metacontact represent a person. This is a kind of entry to
 * the contactlist. All information of a contact is contained in
 * the metacontact. Plugins can store data in it with all
 * @ref ContactListElement methods
 */
class KOPETE_EXPORT MetaContact : public ContactListElement, public NotifyDataObject
{
	Q_OBJECT
  

	TQ_PROPERTY( TQString displayName READ displayName WRITE setDisplayName )
	TQ_PROPERTY( TQString statusString READ statusString )
	TQ_PROPERTY( TQString statusIcon READ statusIcon )
	TQ_PROPERTY( bool isOnline READ isOnline )
	TQ_PROPERTY( bool isReachable READ isReachable )
	TQ_PROPERTY( bool isTemporary READ isTemporary )
	TQ_PROPERTY( bool canAcceptFiles READ canAcceptFiles )
	//TQ_PROPERTY( ulong idleTime READ idleTime )
	TQ_PROPERTY( TQString metaContactId READ metaContactId WRITE setMetaContactId )
	TQ_PROPERTY( bool photoSyncedWithKABC READ isPhotoSyncedWithKABC WRITE setPhotoSyncedWithKABC )

public:
	/** 
	 * Enumeration of possible sources for a property (which may be
	 * photos, see setPhotoSource() for instance).
	 */
	enum PropertySource { 
		SourceContact /**< Data comes from the contact itself. */, 
		SourceKABC /**< Data comes from KABC (addressbook). */, 
		SourceCustom /**< Data comes from somewhere else. */
	};

	/**
	 * constructor
	 */
	MetaContact();
	/**
	 * destructor
	 */
	~MetaContact();

	/**
	 * @brief Returns this metacontact's ID.
	 *
	 * Every metacontact has a unique id, set by  when creating the contact, or reading the contactlist
	 * TODO: make it real
	 */
	TQString metaContactId() const;

	/**
	 * @brief Add or change the link to a KDE addressbook (KABC) Addressee.
	 * FIXME: Use with care.  You could create 1 to many relationships with the current implementation
	 */
	void setMetaContactId( const TQString& newMetaContactId );

	/**
	 * @brief Retrieve the list of contacts that are part of the meta contact
	 */
	TQPtrList<Contact> contacts() const;

	/**
	 * @brief The groups the contact is stored in
	 */
	TQPtrList<Group> groups() const;

	/**
	 * Find the Contact to a given contact. If contact
	 * is not found, a null pointer is returned.
	 * if @p protocolId or @p accountId are null, it is searched over all protocols/accounts
	 */
	Contact *findContact( const TQString &protocolId, const TQString &accountId, const TQString &contactId );

	/**
	 * @brief Set the source of metacontact displayName
	 *
	 * This method selects the display name source for one
	 * of the sources defined in @ref PropertySource
	 *
	 * @see PropertySource
	 */
	void setDisplayNameSource(PropertySource source);

	/**
	 * @brief get the source of metacontact display name
	 *
	 * This method obtains the current name source for one
	 * of the sources defined in @ref PropertySource
	 *
	 * @see PropertySource
	 */
	PropertySource displayNameSource() const;

	/**
	 * @brief Set the source of metacontact photo
	 *
	 * This method selects the photo source for one
	 * of the sources defined in @ref PropertySource
	 *
	 * @see PropertySource
	 */
	void setPhotoSource(PropertySource source);

	/**
	 * @brief get the source of metacontact photo
	 *
	 * This method obtains the current photo source for one
	 * of the sources defined in @ref PropertySource
	 *
	 * @see PropertySource
	 */
	PropertySource photoSource() const;

	/**
	 * @brief the display name showed in the contactlist window
	 *
	 * The displayname is the name which should be shown almost everywere to
	 * represent the metacontact.  (in the contactlist, in the chatwindow, ....)
	 *
	 * This is a kind of alias, set by the kopete user, as opposed to a nickname
	 * set by the contact itself.
	 *
	 * If the protocol support alias serverside, the metacontact displayname
	 * should probably be syncronized with the alias on the server.
	 *
	 * This displayName is obtained from the source set with @ref setDisplayNameSource
	 */
	TQString displayName() const;

	/**
	 * @brief the photo showed in the contactlist window
	 *
	 * Returns a image for the metacontact. If the metacontact photo source is
	 * the KDE addressbook. it will return the picture stored in the addressbook
	 * It can also use a subcontact as the photo source.
	 *
	 * This photo is obtained from the source set with @ref setPhotoSource
	 */
	TQImage photo() const;

	/**
	 * Return the correct Kopete::Picture object depending of the metacontact photo source.
	 *
	 * This photo is obtained from the source set with @ref setPhotoSource
	 *
	 * KDE4 TODO: Rename this to photo() and use the new object.
	 */
	Picture &picture() const;

	/**
	 * @brief Set the custom displayName.
	 *
	 * This display name is used when name source is Custom
	 * this metohd may emit @ref displayNameChanged signal.
	 * And will call @ref Kopete::Contact::sync
	 *
	 * @see displayName()
	 * @see displayNameSource()
	 */
	void setDisplayName( const TQString &name );

	/**
	 * @brief Returns the custom display name
	 *
	 * @see displayName()
	 * @see displayNameSource()
	 */
	TQString customDisplayName() const;

	/**
	 * @brief Returns the custom display photo
	 *
	 * @see photo()
	 * @see photoSource()
	 */
	KURL customPhoto() const;


	/**
	 * @brief Set the custom photo.
	 *
	 * This photo is used when photo source is set toCustom
	 * this metohd may emit @ref photoChanged signal.
	 *
	 * @see photo()
	 * @see photoSource()
	 */
	void setPhoto( const KURL &url );

	/**
	 * @brief get the subcontact being tracked for its displayname (null if not set)
	 *
	 * The MetaContact will adjust its displayName() every time the
	 * "nameSource" changes its nickname property.
	 */
	Contact *displayNameSourceContact() const;

	/**
	 * @brief set the subcontact whose name is to be tracked (set to null to disable tracking)
	 * @see nameSource
	 */
	void setDisplayNameSourceContact( Contact* contact );

	/**
	 * @brief get the subcontact being tracked for its photo
	 */
	Contact *photoSourceContact() const;

	/**
	 * @brief set the subcontact to use for SourceContact source
	 */
	void setPhotoSourceContact( Contact* contact );

	/**
	 * @return true if when a subcontact change his photo, the photo will be set to the tdeabc contact.
	 */
	bool isPhotoSyncedWithKABC() const;

	/**
	 * Set if the photo should be synced with the adressbook when the photosource change his photo
	 *
	 * If  \p b is true, the photo will be synced immediatly if possible
	 */
	void setPhotoSyncedWithKABC(bool b);


	/**
	 * Temporary contacts will not be serialized.
	 * If they are added to the contactlist, they appears in a special "Not in your contactlist" group.
	 * (the @ref Group::temporary  group)
	 */
	bool isTemporary() const;

	/**
	 * @brief Add a contact which has just been deserialised to the meta contact
	 * @param c The Contact being added
	 */
	void addContact( Contact *c );

	/**
	 * @brief remove the contact from this metacontact
	 *
	 * set 'deleted' to true if the Contact is already deleted
	 *
	 * @param c is the contact to remove
	 * @param deleted : if it is false, it will disconnect the old contact, and call some method.
	 */
	void removeContact( Contact *c , bool deleted = false );

	/**
	 * @return the preferred child Contact for communication, or 0 if none is suitable (all unreachable).
	 */
	Contact *preferredContact();

	/**
	 * @brief The name of the icon associated with the contact's status
	 * @todo improve with OnlineStatus
	 */
	TQString statusIcon() const;

	/**
	 * @brief The status string of the contact
	 *
	 * @see @ref status()
	 * @todo improve with OnlineStatus
	 */
	TQString statusString() const;

	/**
	 * Returns whether this contact can be reached online for at least one
	 * FIXME: Make that an enum, because status can be unknown for certain
	 *        protocols
	 */
	bool isOnline() const;

	/**
	 * Returns whether this contact can accept files
	 * @return True if the user is online with a file capable protocol, false otherwise
	 */
	bool canAcceptFiles() const;

	/**
	 * Return a more fine-grained status.
	 * Online means at least one sub-contact is online, away means at least
	 * one is away, but nobody is online and offline speaks for itself
	 */
	OnlineStatus::StatusType status() const;

	/**
	 * Like isOnline, but returns true even if the contact is not online, but
	 * can be reached trough offline-messages.
	 * it it return false, you are unable to open a chatwindow
	 * @todo : Here too, use preference order, not append order!
	 * @todo : Here too an enum.
	 */
	bool isReachable() const;

	/**
	 * return the time in second the contact is idle.
	 */
	unsigned long int idleTime() const;

	/**
	 * Return a XML representation of the metacontact
	 * @internal
	 * @param minimal When true, it doesn't save the
	 * plugins, groups and notification data. False by default.
	 */
	const TQDomElement toXML(bool minimal = false);

	/**
	 * Creates a metacontact from XML
	 * Return value of false indicated that
	 * creation failed and this contact should be
	 * discarded.
	 * @internal
	 */
	bool fromXML( const TQDomElement& cnode );

	/**
	 * Get or set a field for the KDE address book backend. Fields not
	 * registered during the call to Plugin::addressBookFields()
	 * cannot be altered!
	 *
	 * @param p The Plugin by which uses this field
	 * @param app refers to the application id in the libtdeabc database.
	 * This should be a standardized format to make sense in the address
	 * book in the first place - if you could use "" as application
	 * then probably you should use the plugin data API instead of the
	 * address book fields.
	 * @param key The name of the address book field to get or set
	 *
	 * @todo: In the code the requirement that fields are registered first
	 *        is already lifted, but the API needs some review before we
	 *        can remove it here too.
	 *        Probably it requires once more some rewrites to get it working
	 *        properly :( - Martijn
	 */
	TQString addressBookField( Plugin *p, const TQString &app, const TQString &key ) const;

	/**
	 * @brief set an address book field
	 *
	 * @see also @ref addressBookField()
	 * @param p The Plugin by which uses this field
	 * @param app The application ID in the KABC database
	 * @param key The name of the address book field to set
	 * @param value The value of the address book field to set
	 */
	void setAddressBookField( Plugin *p, const TQString &app, const TQString &key, const TQString &value );

public slots:

	/**
	 * @brief Send a file to this metacontact
	 *
	 * This is the MetaContact level slot for sending files. It may be called through the
	 * "Send File" entry in the GUI, or over DCOP. If the function is called through the GUI,
	 * no parameters are sent and they assume default values. This slot calls the slotSendFile
	 * with identical params of the highest ranked contact capable of sending files (if any)
	 *
	 * @param sourceURL The actual KURL of the file you are sending
	 * @param altFileName (Optional) An alternate name for the file - what the receiver will see
	 * @param fileSize (Optional) Size of the file being sent. Used when sending a nondeterminate
	 *                file size (such as over a socket)
	 *
	 */
	void sendFile( const KURL &sourceURL, const TQString &altFileName = TQString(),
		unsigned long fileSize = 0L );
signals:
	/**
	 * This metaContact is going to be saved to the contactlist. Plugins should
	 * connect to this signal to update data with setPluginData()
	 */
	void aboutToSave( Kopete::MetaContact *metaContact );

	/**
	 * One of the subcontacts' idle status has changed.  As with online status,
	 * this can occur without the metacontact changing idle state
	 */
	void contactIdleStateChanged( Kopete::Contact *contact );


public slots:

	/**
	 * @brief Move a contact from one group to another.
	 */
	void moveToGroup( Kopete::Group *from, Kopete::Group *to );

	/**
	 * @brief Remove a contact from one group
	 */
	void removeFromGroup( Kopete::Group *from );

	/**
	 * @brief Add a contact to another group.
	 */
	void addToGroup( Kopete::Group *to );

	/**
	 * @brief Set if this is a temporary contact. (see @ref isTemporary)
	 *
	 * @param b if the contact is or not temporary
	 * @param group if the contact was temporary and b is false, then the contact will be moved to this group.
	 *  if group is null, it will be moved to top-level
	 */
	void setTemporary( bool b = true, Kopete::Group *group = 0L );

	/**
	 * @brief Contact another user.
	 *
	 * Depending on the config settings, call sendMessage() or
	 * startChat()
	 *
	 * returns the Contact that was chosen as the preferred
	 */
	Contact *execute();

	/**
	 * @brief Send a single message, classic ICQ style.
	 *
	 * The actual sending is done by the Contact, but the meta contact
	 * does the GUI side of things.
	 * This is a slot to allow being called easily from e.g. a GUI.
	 *
	 * returns the Contact that was chosen as the preferred
	 */
	Contact *sendMessage();

	/**
	 * @brief Start a chat in a persistent chat window
	 *
	 * Like sendMessage, but this time a full-blown chat will be opened.
	 * Most protocols can't distinguish between the two and are either
	 * completely session based like ICQ or completely message based like
	 * ICQ the only true difference is the GUI shown to the user.
	 *
	 * returns the Contact that was chosen as the preferred
	 */
	Contact *startChat();

signals:
	/**
	 *  @brief The MetaContact online status changed
	 */
	void onlineStatusChanged( Kopete::MetaContact *contact, Kopete::OnlineStatus::StatusType status );

	/**
	 * @brief A contact's online status changed
	 *
	 * this signal differs from @ref onlineStatusChanged because a contact can
	 * change his status without changing MetaContact status. It is mainly used to update the small icons
	 * in the contactlist
	 */
	void contactStatusChanged( Kopete::Contact *contact, const Kopete::OnlineStatus &status );

	/**
	 * @brief The meta contact's display name changed
	 */
	void displayNameChanged( const TQString &oldName, const TQString &newName );

	/**
	 * @brief The meta contact's photo changed
	 */
	void photoChanged();

	/**
	 * @brief  The contact was moved
	 */
	void movedToGroup( Kopete::MetaContact *contact, Kopete::Group *from, Kopete::Group *to );

	/**
	 * @brief The contact was removed from group
	 */
	void removedFromGroup( Kopete::MetaContact *contact, Kopete::Group *group );

	/**
	 * @brief The contact was added to another group
	 */
	void addedToGroup( Kopete::MetaContact *contact, Kopete::Group *to );

	/**
	 * @brief a contact has been added into this metacontact
	 *
	 * This signal is emitted when a contact is added to this metacontact
	 */
	void contactAdded( Kopete::Contact *c );

	/**
	 * @brief a contact has been removed from this metacontact
	 *
	 * This signal is emitted when a contact is removed from this metacontact
	 */
	void contactRemoved( Kopete::Contact *c );

	/**
	 * Some part of this object's persistent data (as returned by toXML) has changed.
	 */
	void persistentDataChanged(  );

private slots:
	/**
	 * Update the contact's online status and emit onlineStatusChanged
	 * when appropriate
	 */
	void updateOnlineStatus();

	/**
	 * One of the child contact's online status changed
	 */
	void slotContactStatusChanged( Kopete::Contact *c, const Kopete::OnlineStatus &status, const Kopete::OnlineStatus &oldStatus );

	/**
	 * One of the child contact's property changed
	 */
	void slotPropertyChanged( Kopete::Contact *contact, const TQString &key, const TQVariant &oldValue, const TQVariant &newValue  );

	/**
	 * A child contact was deleted, remove it from the list, if it's still
	 * there
	 */
	void slotContactDestroyed( Kopete::Contact* );

	/**
	 * If a plugin is loaded, maybe data about this plugin are already cached in the metacontact
	 */
	void slotPluginLoaded( Kopete::Plugin *plugin );

	/**
	 * When all the plugins are loaded, set the Contact Source.
	 */
	void slotAllPluginsLoaded();

	/**
	 * Update the KABC Picture when the addressbook is changed.
	 */
	void slotUpdateAddressBookPicture();

protected:
	//TQImage photoFromContact( Kopete::Contact *c) const;
	//TQImage photoFromKABC( const TQString &id ) const;
	TQImage photoFromCustom() const;
	//TQString nameFromContact( Kopete::Contact *c) const;
	//TQString nameFromKABC( const TQString &id ) const;

	TQString sourceToString(PropertySource source) const;
	PropertySource stringToSource(const TQString &name) const;
private:
	class Private;
	Private *d;
};

// util functions shared with metacontact property dialog
KOPETE_EXPORT TQImage photoFromContact( Kopete::Contact *c) /*const*/;
KOPETE_EXPORT TQImage photoFromKABC( const TQString &id ) /*const*/;
KOPETE_EXPORT TQString nameFromContact( Kopete::Contact *c) /*const*/;
KOPETE_EXPORT TQString nameFromKABC( const TQString &id ) /*const*/;

} //END namespace Kopete


#endif

// vim: set noet ts=4 sts=4 sw=4: