kopete/libkopete/kopetemetacontact.h

   1 /*
   2     kopetemetacontact.h - Kopete Meta Contact
   3
   4     Copyright (c) 2002-2003 by Martijn Klingens       <klingens@kde.org>
   5     Copyright (c) 2002-2005 by Duncan Mac-Vicar Prett <duncan@kde.org>
   6     Copyright (c) 2002-2005 by Olivier Goffart        <ogoffart@kde.org>
   7     Copyright (c) 2003      by Will Stephenson        <will@stevello.free-online.co.uk>
   8
   9     Kopete    (c) 2002-2005 by the Kopete developers  <kopete-devel@kde.org>
  10
  11     *************************************************************************
  12     *                                                                       *
  13     * This library is free software; you can redistribute it and/or         *
  14     * modify it under the terms of the GNU Lesser General Public            *
  15     * License as published by the Free Software Foundation; either          *
  16     * version 2 of the License, or (at your option) any later version.      *
  17     *                                                                       *
  18     *************************************************************************
  19 */
  20
  21 #ifndef kopetemetacontact_h__
  22 #define kopetemetacontact_h__
  23
  24 #include "kopetecontactlistelement.h"
  25
  26 #include <QtCore/QList>
  27
  28 #include <kdemacros.h>
  29 #include <kurl.h>
  30 #include "kopete_export.h"
  31
  32 #include "kopeteonlinestatus.h"
  33
  34 namespace Kopete {
  35
  36
  37 class Plugin;
  38 class Group;
  39 class Picture;
  40
  41 /**
  42  * @author Will Stephenson <will@stevello.free-online.co.uk>
  43  * @author Martijn Klingens <klingens@kde.org>
  44  * @author Duncan Mac-Vicar Prett <duncan@kde.org>
  45  * @author Olivier Goffart <ogoffart@kde.org>
  46  *
  47  * A metacontact represent a person. This is a kind of entry to
  48  * the contact list. All information of a contact is contained in
  49  * the metacontact. Plugins can store data in it with all
  50  * @ref ContactListElement methods
  51  */
  52 class KOPETE_EXPORT MetaContact : public ContactListElement
  53 {
  54         Q_OBJECT
  55
  56         Q_PROPERTY( QString displayName READ displayName WRITE setDisplayName )
  57         Q_PROPERTY( QString statusString READ statusString )
  58         Q_PROPERTY( QString statusIcon READ statusIcon )
  59         Q_PROPERTY( bool isOnline READ isOnline )
  60         Q_PROPERTY( bool isReachable READ isReachable )
  61         Q_PROPERTY( bool isTemporary READ isTemporary )
  62         Q_PROPERTY( bool canAcceptFiles READ canAcceptFiles )
  63         //Q_PROPERTY( ulong idleTime READ idleTime )
  64         Q_PROPERTY( QString metaContactId READ metaContactId WRITE setMetaContactId )
  65         Q_PROPERTY( bool photoSyncedWithKABC READ isPhotoSyncedWithKABC WRITE setPhotoSyncedWithKABC )
  66
  67 public:
  68         typedef QList<MetaContact *> List;
  69         /**
  70          * Enumeration of possible sources for a property (which may be
  71          * photos, see setPhotoSource() for instance).
  72          */
  73         enum PropertySource {
  74                 SourceContact /**< Data comes from the contact itself. */,
  75                 SourceKABC /**< Data comes from KABC (addressbook). */,
  76                 SourceCustom /**< Data comes from somewhere else. */
  77         };
  78
  79         /**
  80          * constructor
  81          */
  82         MetaContact();
  83         /**
  84          * destructor
  85          */
  86         ~MetaContact();
  87
  88         /**
  89          * @brief Returns this metacontact's ID.
  90          *
  91          * Every metacontact has a unique id, set by  when creating the contact, or reading the contact list
  92          * TODO: make it real
  93          */
  94         QString metaContactId() const;
  95
  96         /**
  97          * @brief Add or change the link to a KDE addressbook (KABC) Addressee.
  98          * FIXME: Use with care.  You could create 1 to many relationships with the current implementation
  99          */
 100         void setMetaContactId( const QString& newMetaContactId );
 101
 102         /**
 103          * @brief Retrieve the list of contacts that are part of the meta contact
 104          */
 105         QList<Contact *> contacts() const;
 106
 107         /**
 108          * @brief The groups the contact is stored in
 109          */
 110         QList<Group *> groups() const;
 111
 112         /**
 113          * Find the Contact to a given contact. If contact
 114          * is not found, a null pointer is returned.
 115          * if @p protocolId or @p accountId are null, it is searched over all protocols/accounts
 116          */
 117         Contact *findContact( const QString &protocolId, const QString &accountId, const QString &contactId );
 118
 119         /**
 120          * @brief Set the source of metacontact displayName
 121          *
 122          * This method selects the display name source for one
 123          * of the sources defined in @ref PropertySource
 124          *
 125          * @see PropertySource
 126          */
 127         void setDisplayNameSource(PropertySource source);
 128
 129         void setDisplayNameSource( const QString &nameSourcePID, const QString &nameSourceAID, const QString &nameSourceCID );
 130
 131         /**
 132          * @brief get the source of metacontact display name
 133          *
 134          * This method obtains the current name source for one
 135          * of the sources defined in @ref PropertySource
 136          *
 137          * @see PropertySource
 138          */
 139         PropertySource displayNameSource() const;
 140
 141         /**
 142          * @brief Set the source of metacontact photo
 143          *
 144          * This method selects the photo source for one
 145          * of the sources defined in @ref PropertySource
 146          *
 147          * @see PropertySource
 148          */
 149         void setPhotoSource(PropertySource source);
 150
 151         void setPhotoSource( const QString &photoSourcePID, const QString &photoSourceAID, const QString &photoSourceCID );
 152
 153         /**
 154          * @brief get the source of metacontact photo
 155          *
 156          * This method obtains the current photo source for one
 157          * of the sources defined in @ref PropertySource
 158          *
 159          * @see PropertySource
 160          */
 161         PropertySource photoSource() const;
 162
 163         /**
 164          * @brief the display name showed in the contact list window
 165          *
 166          * The displayname is the name which should be shown almost everywere to
 167          * represent the metacontact.  (in the contact list, in the chatwindow, ...)
 168          *
 169          * This is a kind of alias, set by the kopete user, as opposed to a nickname
 170          * set by the contact itself.
 171          *
 172          * If the protocol support alias serverside, the metacontact displayname
 173          * should probably be synchronized with the alias on the server.
 174          *
 175          * This displayName is obtained from the source set with @ref setDisplayNameSource
 176          */
 177         QString displayName() const;
 178
 179         /**
 180          * @brief the photo showed in the contact list window
 181          *
 182          * Returns a image for the metacontact. If the metacontact photo source is
 183          * the KDE addressbook. it will return the picture stored in the addressbook
 184          * It can also use a subcontact as the photo source.
 185          *
 186          * This photo is obtained from the source set with @ref setPhotoSource
 187          * @deprecated Use picture().image() instead.
 188          */
 189         KDE_DEPRECATED QImage photo() const;
 190
 191         /**
 192          * Return the correct Kopete::Picture object depending of the metacontact photo source.
 193          *
 194          * This photo is obtained from the source set with @ref setPhotoSource
 195          *
 196          * KDE4 TODO: Rename this to photo() and use the new object.
 197          */
 198         Picture &picture() const;
 199
 200         /**
 201          * @brief Set the custom displayName.
 202          *
 203          * This display name is used when name source is Custom
 204          * this metohd may emit @ref displayNameChanged signal.
 205          * And will call @ref Kopete::Contact::sync
 206          *
 207          * @see displayName()
 208          * @see displayNameSource()
 209          */
 210         void setDisplayName( const QString &name );
 211
 212         /**
 213          * @brief Returns the custom display name
 214          *
 215          * @see displayName()
 216          * @see displayNameSource()
 217          */
 218         QString customDisplayName() const;
 219
 220         /**
 221          * @brief Returns the custom display photo
 222          *
 223          * @see photo()
 224          * @see photoSource()
 225          */
 226         KUrl customPhoto() const;
 227
 228
 229         /**
 230          * @brief Set the custom photo.
 231          *
 232          * This photo is used when photo source is set toCustom
 233          * this metohd may emit @ref photoChanged signal.
 234          *
 235          * @see photo()
 236          * @see photoSource()
 237          */
 238         void setPhoto( const KUrl &url );
 239
 240         /**
 241          * @brief get the subcontact being tracked for its displayname (null if not set)
 242          *
 243          * The MetaContact will adjust its displayName() every time the
 244          * "nameSource" changes its nickname property.
 245          */
 246         Contact *displayNameSourceContact() const;
 247
 248         /**
 249          * @brief set the subcontact whose name is to be tracked (set to null to disable tracking)
 250          * @see nameSource
 251          */
 252         void setDisplayNameSourceContact( Contact* contact );
 253
 254         /**
 255          * @brief get the subcontact being tracked for its photo
 256          */
 257         Contact *photoSourceContact() const;
 258
 259         /**
 260          * @brief set the subcontact to use for SourceContact source
 261          */
 262         void setPhotoSourceContact( Contact* contact );
 263
 264         /**
 265          * @return true if when a subcontact change his photo, the photo will be set to the kabc contact.
 266          */
 267         bool isPhotoSyncedWithKABC() const;
 268
 269         /**
 270          * Set if the photo should be synced with the adressbook when the photosource change his photo
 271          *
 272          * If  \p b is true, the photo will be synced immediately if possible
 273          */
 274         void setPhotoSyncedWithKABC(bool b);
 275
 276
 277         /**
 278          * Temporary contacts will not be serialized.
 279          * If they are added to the contact list, they appears in a special "Not in your contact list" group.
 280          * (the @ref Group::temporary  group)
 281          */
 282         bool isTemporary() const;
 283
 284         /**
 285          * @brief Add a contact which has just been deserialised to the meta contact
 286          * @param c The Contact being added
 287          */
 288         void addContact( Contact *c );
 289
 290         /**
 291          * @brief remove the contact from this metacontact
 292          *
 293          * set 'deleted' to true if the Contact is already deleted
 294          *
 295          * @param c is the contact to remove
 296          * @param deleted : if it is false, it will disconnect the old contact, and call some method.
 297          */
 298         void removeContact( Contact *c , bool deleted = false );
 299
 300         /**
 301          * @return the preferred child Contact for communication, or 0 if none is suitable (all unreachable).
 302          */
 303         Contact *preferredContact();
 304
 305         /**
 306          * @brief The name of the icon associated with the contact's status
 307          * @todo improve with OnlineStatus
 308          */
 309         QString statusIcon() const;
 310
 311         /**
 312          * @brief The status string of the contact
 313          *
 314          * @see @ref status()
 315          * @todo improve with OnlineStatus
 316          */
 317         QString statusString() const;
 318
 319         /**
 320          * Returns whether this contact can be reached online for at least one
 321          * FIXME: Make that an enum, because status can be unknown for certain
 322          *        protocols
 323          */
 324         bool isOnline() const;
 325
 326         /**
 327          * Returns whether this contact can accept files
 328          * @return True if the user is online with a file capable protocol, false otherwise
 329          */
 330         bool canAcceptFiles() const;
 331
 332         /**
 333          * Return a more fine-grained status.
 334          * Online means at least one sub-contact is online, away means at least
 335          * one is away, but nobody is online and offline speaks for itself
 336          */
 337         OnlineStatus::StatusType status() const;
 338
 339         /**
 340          * Like isOnline, but returns true even if the contact is not online, but
 341          * can be reached trough offline-messages.
 342          * it it return false, you are unable to open a chatwindow
 343          * @todo : Here too, use preference order, not append order!
 344          * @todo : Here too an enum.
 345          */
 346         bool isReachable() const;
 347
 348         /**
 349          * return the time in second the contact is idle.
 350          */
 351         unsigned long int idleTime() const;
 352
 353         /**
 354          * Get or set a field for the KDE address book backend. Fields not
 355          * registered during the call to Plugin::addressBookFields()
 356          * cannot be altered!
 357          *
 358          * @param p The Plugin by which uses this field
 359          * @param app refers to the application id in the libkabc database.
 360          * This should be a standardized format to make sense in the address
 361          * book in the first place - if you could use "" as application
 362          * then probably you should use the plugin data API instead of the
 363          * address book fields.
 364          * @param key The name of the address book field to get or set
 365          *
 366          * @todo: In the code the requirement that fields are registered first
 367          *        is already lifted, but the API needs some review before we
 368          *        can remove it here too.
 369          *        Probably it requires once more some rewrites to get it working
 370          *        properly :( - Martijn
 371          */
 372         QString addressBookField( Plugin *p, const QString &app, const QString &key ) const;
 373
 374         /**
 375          * @brief set an address book field
 376          *
 377          * @see also @ref addressBookField()
 378          * @param p The Plugin by which uses this field
 379          * @param app The application ID in the KABC database
 380          * @param key The name of the address book field to set
 381          * @param value The value of the address book field to set
 382          */
 383         void setAddressBookField( Plugin *p, const QString &app, const QString &key, const QString &value );
 384
 385 public slots:
 386
 387         /**
 388          * @brief Send a file to this metacontact
 389          *
 390          * This is the MetaContact level slot for sending files. It may be called through the
 391          * "Send File" entry in the GUI, or over DCOP. If the function is called through the GUI,
 392          * no parameters are sent and they assume default values. This slot calls the slotSendFile
 393          * with identical params of the highest ranked contact capable of sending files (if any)
 394          *
 395          * @param sourceURL The actual KUrl of the file you are sending
 396          * @param altFileName (Optional) An alternate name for the file - what the receiver will see
 397          * @param fileSize (Optional) Size of the file being sent. Used when sending a nondeterminate
 398          *                file size (such as over a socket)
 399          *
 400          */
 401         void sendFile( const KUrl &sourceURL, const QString &altFileName = QString(),
 402                 unsigned long fileSize = 0L );
 403
 404         /**
 405          * Emit aboutToSave signal to notify plugins that this metaContact is going to be saved
 406          */
 407         void emitAboutToSave();
 408
 409 signals:
 410         /**
 411          * This metaContact is going to be saved to the contact list. Plugins should
 412          * connect to this signal to update data with setPluginData()
 413          */
 414         void aboutToSave( Kopete::MetaContact *metaContact );
 415
 416         /**
 417          * One of the subcontacts' idle status has changed.  As with online status,
 418          * this can occur without the metacontact changing idle state
 419          */
 420         void contactIdleStateChanged( Kopete::Contact *contact );
 421
 422
 423 public slots:
 424
 425         /**
 426          * @brief Move a contact from one group to another.
 427          */
 428         void moveToGroup( Kopete::Group *from, Kopete::Group *to );
 429
 430         /**
 431          * @brief Remove a contact from one group
 432          */
 433         void removeFromGroup( Kopete::Group *from );
 434
 435         /**
 436          * @brief Add a contact to another group.
 437          */
 438         void addToGroup( Kopete::Group *to );
 439
 440         /**
 441          * @brief Set if this is a temporary contact. (see @ref isTemporary)
 442          *
 443          * @param b if the contact is or not temporary
 444          * @param group if the contact was temporary and b is false, then the contact will be moved to this group.
 445          *  if group is null, it will be moved to top-level
 446          */
 447         void setTemporary( bool b = true, Kopete::Group *group = 0L );
 448
 449         /**
 450          * @brief Contact another user.
 451          *
 452          * Depending on the config settings, call sendMessage() or
 453          * startChat()
 454          *
 455          * returns the Contact that was chosen as the preferred
 456          */
 457         Contact *execute();
 458
 459         /**
 460          * @brief Send a single message, classic ICQ style.
 461          *
 462          * The actual sending is done by the Contact, but the meta contact
 463          * does the GUI side of things.
 464          * This is a slot to allow being called easily from e.g. a GUI.
 465          *
 466          * returns the Contact that was chosen as the preferred
 467          */
 468         Contact *sendMessage();
 469
 470         /**
 471          * @brief Start a chat in a persistent chat window
 472          *
 473          * Like sendMessage, but this time a full-blown chat will be opened.
 474          * Most protocols can't distinguish between the two and are either
 475          * completely session based like MSN or completely message based like
 476          * ICQ the only true difference is the GUI shown to the user.
 477          *
 478          * returns the Contact that was chosen as the preferred
 479          */
 480         Contact *startChat();
 481
 482         /**
 483          * When all the plugins are loaded, set the Contact Source.
 484          */
 485         void slotAllPluginsLoaded();
 486
 487         /**
 488          * If a plugin is loaded, maybe data about this plugin are already cached in the metacontact
 489          */
 490         void slotPluginLoaded( Kopete::Plugin *plugin );
 491
 492 signals:
 493         /**
 494          *  @brief The MetaContact online status changed
 495          */
 496         void onlineStatusChanged( Kopete::MetaContact *contact, Kopete::OnlineStatus::StatusType status );
 497
 498         /**
 499          * @brief A contact's online status changed
 500          *
 501          * this signal differs from @ref onlineStatusChanged because a contact can
 502          * change his status without changing MetaContact status. It is mainly used to update the small icons
 503          * in the contact list
 504          */
 505         void contactStatusChanged( Kopete::Contact *contact, const Kopete::OnlineStatus &status );
 506
 507         /**
 508          * @brief The meta contact's display name changed
 509          */
 510         void displayNameChanged( const QString &oldName, const QString &newName );
 511
 512         /**
 513          * @brief The meta contact's photo changed
 514          */
 515         void photoChanged();
 516
 517         /**
 518          * @brief  The contact was moved
 519          */
 520         void movedToGroup( Kopete::MetaContact *contact, Kopete::Group *from, Kopete::Group *to );
 521
 522         /**
 523          * @brief The contact was removed from group
 524          */
 525         void removedFromGroup( Kopete::MetaContact *contact, Kopete::Group *group );
 526
 527         /**
 528          * @brief The contact was added to another group
 529          */
 530         void addedToGroup( Kopete::MetaContact *contact, Kopete::Group *to );
 531
 532         /**
 533          * @brief a contact has been added into this metacontact
 534          *
 535          * This signal is emitted when a contact is added to this metacontact
 536          */
 537         void contactAdded( Kopete::Contact *c );
 538
 539         /**
 540          * @brief a contact has been removed from this metacontact
 541          *
 542          * This signal is emitted when a contact is removed from this metacontact
 543          */
 544         void contactRemoved( Kopete::Contact *c );
 545
 546         /**
 547          * Some part of this object's persistent data (as returned by toXML) has changed.
 548          */
 549         void persistentDataChanged(  );
 550
 551 private slots:
 552         /**
 553          * Update the contact's online status and emit onlineStatusChanged
 554          * when appropriate
 555          */
 556         void updateOnlineStatus();
 557
 558         /**
 559          * One of the child contact's online status changed
 560          */
 561         void slotContactStatusChanged( Kopete::Contact *c, const Kopete::OnlineStatus &status, const Kopete::OnlineStatus &oldStatus );
 562
 563         /**
 564          * One of the child contact's property changed
 565          */
 566         void slotPropertyChanged( Kopete::PropertyContainer *contact, const QString &key, const QVariant &oldValue, const QVariant &newValue  );
 567
 568         /**
 569          * A child contact was deleted, remove it from the list, if it's still
 570          * there
 571          */
 572         void slotContactDestroyed( Kopete::Contact* );
 573
 574         /**
 575          * Update the KABC Picture when the addressbook is changed.
 576          */
 577         void slotUpdateAddressBookPicture();
 578
 579 protected:
 580         //QImage photoFromContact( Kopete::Contact *c) const;
 581         //QImage photoFromKABC( const QString &id ) const;
 582         QImage photoFromCustom() const;
 583         //QString nameFromContact( Kopete::Contact *c) const;
 584         //QString nameFromKABC( const QString &id ) const;
 585
 586 private:
 587         class Private;
 588         Private * const d;
 589 };
 590
 591 // util functions shared with metacontact property dialog
 592 KOPETE_EXPORT QImage photoFromContact( Kopete::Contact *c) /*const*/;
 593 KOPETE_EXPORT QImage photoFromKABC( const QString &id ) /*const*/;
 594 KOPETE_EXPORT QString nameFromContact( Kopete::Contact *c) /*const*/;
 595 KOPETE_EXPORT QString nameFromKABC( const QString &id ) /*const*/;
 596
 597 } //END namespace Kopete
 598
 599
 600 #endif
 601
 602 // vim: set noet ts=4 sts=4 sw=4:
 603