Copy the KDE 3.5 branch to branches/trinity for new KDE 3.5 features.

BUG:215923


git-svn-id: svn://anonsvn.kde.org/home/kde/branches/trinity/kdenetwork@1054174 283d02a7-25f6-0310-bc7c-ecb5cbfe19da

1 files changed, 557 insertions, 0 deletions

diff --git a/kopete/libkopete/kopetecontact.h b/kopete/libkopete/kopetecontact.h
new file mode 100644
index 00000000..8f02bfc2
--- /dev/null
+++ b/kopete/libkopete/kopetecontact.h
@@ -0,0 +1,557 @@
+/*
+    kopetecontact.h - Kopete Contact
+
+    Copyright (c) 2002-2004 by Duncan Mac-Vicar Prett <duncan@kde.org>
+    Copyright (c) 2002-2003 by Martijn Klingens       <klingens@kde.org>
+    Copyright (c) 2002-2004 by Olivier Goffart        <ogoffart @ tiscalinet.be>
+
+    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 __KOPETECONTACT_H__
+#define __KOPETECONTACT_H__
+
+#include <qobject.h>
+#include <kurl.h>
+#include <kdemacros.h>
+#include "kopeteglobal.h"
+
+#include "kopete_export.h"
+
+class QImage;
+class KPopupMenu;
+class KAction;
+
+namespace Kopete
+{
+
+class Group;
+class MetaContact;
+class ChatSession;
+class OnlineStatus;
+class Plugin;
+class Protocol;
+class Account;
+typedef QPtrList<Group> GroupList;
+
+/**
+ * @author Duncan Mac-Vicar P. <duncan@kde.org>
+ * @author Martijn Klingens <klingens@kde.org>
+ * @author Olivier Goffart <ogoffart@ tiscalinet.be>
+ *
+ * This class abstracts a generic contact
+ * Use it for inserting contacts in the contact list for example.
+ */
+class KOPETE_EXPORT Contact : public QObject
+{
+	Q_OBJECT
+
+	Q_ENUMS( CanCreateFlags )
+	Q_PROPERTY( QString formattedName READ formattedName )
+	Q_PROPERTY( QString formattedIdleTime READ formattedIdleTime )
+	Q_PROPERTY( bool isOnline READ isOnline )
+	Q_PROPERTY( bool fileCapable READ isFileCapable WRITE setFileCapable )
+	Q_PROPERTY( bool canAcceptFiles READ canAcceptFiles )
+	//Q_PROPERTY( bool isReachable READ isReachable )
+	Q_PROPERTY( QString contactId READ contactId )
+	Q_PROPERTY( QString icon READ icon WRITE setIcon )
+	Q_PROPERTY( QString toolTip READ toolTip )
+	Q_PROPERTY( QString nickName READ nickName WRITE setNickName )
+	//Q_PROPERTY( unsigned long idleTime READ idleTime WRITE setIdleTime )
+
+public:
+	/**
+	 * \brief Create new contact.
+	 *
+	 * <b>The parent MetaContact must not be NULL</b>
+	 *
+	 * \note id is required to be unique per protocol and per account.
+	 * Across those boundaries ids may occur multiple times.
+	 * The id is solely for comparing items safely (using pointers is
+	 * more crash-prone). DO NOT assume anything regarding the id's
+	 * value! Even if it may look like an ICQ UIN or an MSN passport,
+	 * this is undefined and may change at any time!
+	 *
+	 * @param account is the parent account. this constructor automatically register the contact to the account
+	 * @param id is the Contact's unique Id (mostly the user's login)
+	 * @param parent is the parent @ref MetaContact this Contact is part of
+	 * @param icon is an optional icon
+	 */
+	Contact( Account *account, const QString &id, MetaContact *parent,
+		const QString &icon = QString::null );
+
+	~Contact();
+
+	/**
+	 * \brief Get the metacontact for this contact
+	 * @return The MetaContact object for this contact
+	 */
+	MetaContact *metaContact() const;
+
+
+	/**
+	 * \brief Get the unique id that identifies a contact.
+	 *
+	 * \note Id is required to be unique per protocol and per account.
+	 * Across those boundaries ids may occur multiple times.
+	 * The id is solely for comparing items safely (using pointers is
+	 * more crash-prone). DO NOT assume anything regarding the id's
+	 * value! Even if it may look like an ICQ UIN or an MSN passport,
+	 * this is undefined and may change at any time!
+	 *
+	 * @return The unique id of the contact
+	 */
+	QString contactId() const;
+
+	/**
+	 * \brief Get the protocol that the contact belongs to.
+	 *
+	 * simply return account()->protocol()
+	 *
+	 * @return the contact's protocol
+	 */
+	Protocol* protocol() const;
+
+	/**
+	 * \brief Get the account that this contact belongs to
+	 *
+	 * @return the Account object for this contact
+	 */
+	Account* account() const;
+
+	/**
+	 * \brief Move this contact to a new MetaContact.
+	 * This basically reparents the contact and updates the internal
+	 * data structures.
+	 * If the old contact is going to be empty, a question may ask to the user if it wants to delete the old contact.
+	 *
+	 * @param m The new MetaContact to move this contact to
+	 */
+	void setMetaContact(MetaContact *m);
+
+
+	/**
+	 * @brief Get whether this contact is online.
+	 * @return @c true if the contact is online, @c false otherwise.
+	 */
+	bool isOnline() const;
+
+	/**
+	 * \brief Get whether this contact can receive messages
+	 *
+	 * Used in determining if the contact is able to
+	 * receive messages.  This function must be defined by child classes
+	 *
+	 * @return true if the contact can be reached
+	 * @return false if the contact can not be reached
+	 */
+	// FIXME: After KDE 3.2 we should split this into a public, NON-virtual
+	//        isReachable() accessor that checks for account->isConnected()
+	//        and then calls a new virtual method that does the
+	//        protocol-specific work, like 'doIsUnreachable' or so - Martijn
+	//
+	//FIXME: Can this be made const please? - JK
+	virtual bool isReachable();
+
+	/**
+	 * @brief Serialize the contact for storage in the contact list.
+	 *
+	 * The provided serializedData contain the contact id in the field
+	 * "contactId". If you don't like this, or don't want to
+	 * store these fields at all,
+	 * you are free to remove them from the list.
+	 *
+	 * Most plugins don't need more than these fields, so they only need
+	 * to set the address book fields themselves. If you have nothing to
+	 * save at all you can clear the QMap, an empty map is treated as
+	 * 'nothing to save'.
+	 *
+	 * The provided addressBookFields QMap contains the index field as
+	 * marked with @ref Plugin::addAddressBookField() with the
+	 * contact id as value. If no index field is available the QMap is
+	 * simply passed as an empty map.
+	 *
+	 * @sa Protocol::deserializeContact
+	 */
+	virtual void serialize( QMap<QString, QString> &serializedData, QMap<QString, QString> &addressBookData );
+
+	/**
+	 * @brief Serialize the contacts persistent properties for storage in the contact list.
+	 *
+	 * Does the same as @ref serialize() does but for KopeteContactProperties
+	 * set in this contact with their persistency flag turned on.
+	 * In contrary to @ref serialize() this does not need to be reimplemented.
+	 *
+	 */
+	void serializeProperties(QMap<QString, QString> &serializedData);
+
+	/**
+	 * @brief Deserialize the contacts persistent properties
+	 */
+	void deserializeProperties(QMap<QString, QString> &serializedData);
+
+	/**
+	 * @brief Get the online status of the contact
+	 * @return the online status of the contact
+	 */
+	OnlineStatus onlineStatus() const;
+
+	/**
+	 * \brief Set the contact's online status
+	 */
+	void setOnlineStatus(const OnlineStatus &status);
+
+	/**
+	 * \brief Get the set of custom menu items for this contact
+	 *
+	 * Returns a set of custom menu items for the context menu
+	 * which is displayed in showContextMenu (private).  Protocols
+	 * should use this to add protocol-specific actions to the
+	 * popup menu. Kopete take care of the deletion of the action collection.
+	 * Actions should have the collection as parent.
+	 *
+	 * @return Collection of menu items to be show on the context menu
+	 * @todo if possible, try to use KXMLGUI
+	 */
+	virtual QPtrList<KAction> *customContextMenuActions();
+
+	/**
+	 * @todo  What is this function for ?
+	 */
+	virtual QPtrList<KAction> *customContextMenuActions( ChatSession *manager );
+
+	/**
+	 * @brief Get the Context Menu for this contact
+	 *
+	 * This menu includes generic actions common to each protocol, and action defined in
+	 * @ref customContextMenuActions()
+	 */
+	KPopupMenu *popupMenu( ChatSession *manager = 0L );
+
+	/**
+	 * \brief Get whether or not this contact is capable of file transfers
+	 *
+	 *
+	 * \see setFileCapable()
+	 * \return true if the protocol for this contact is capable of file transfers
+	 * \return false if the protocol for this contact is not capable of file transfers
+	 *
+	 * @todo have a capabilioties. or move to protocol capabilities
+	 */
+	bool isFileCapable() const;
+
+	/**
+	 * \brief Set the file transfer capability of this contact
+	 *
+	 * \param filecap The new file transfer capability setting
+	 * @todo have a capabilioties. or move to protocol capabilities
+	 */
+	void setFileCapable( bool filecap );
+
+	/**
+	 * \brief Get whether or not this contact can accept file transfers
+	 *
+	 * This function checks to make sure that the contact is online as well as
+	 * capable of sending files.
+	 * \see isReachable()
+	 * @return true if this contact is online and is capable of receiving files
+	 * @todo have a capabilioties. or move to protocol capabilities
+	 */
+	bool canAcceptFiles() const;
+
+	enum CanCreateFlags {  CannotCreate=false , CanCreate=true  };
+
+	/**
+	 * Returns the primary message manager affiliated with this contact
+	 * Although a contact can have more than one active message manager
+	 * (as is the case with MSN at least), only one message manager will
+	 * ever be the contacts "primary" message manager.. aka the 1 on 1 chat.
+	 * This function should always return that instance.
+	 *
+	 * @param canCreate If a new message manager can be created in addition
+	 * to any existing managers. Currently, this is only set to true when
+	 * a chat is initiated by the user by clicking the contact list.
+	 */
+	virtual ChatSession * manager( CanCreateFlags canCreate = CannotCreate ) =0;
+
+	/**
+	 * Returns the name of the icon to use for this contact
+	 *  If null, the protocol icon need to be used.
+	 * The icon is not colored, nor has the status icon overloaded
+	 */
+	QString& icon() const;
+
+	/**
+	 * @brief Change the icon to use for this contact
+	 * If you don't want to have the protocol icon as icon for this contact, you may set
+	 * another icon.  The icon doesn't need to be colored with the account icon as this operation
+	 * will be performed later.
+	 *
+	 * if you want to go back to the protocol icon, set a null string.
+	 */
+	void setIcon( const QString& icon );
+
+	/**
+	 * \brief Get the time (in seconds) this contact has been idle
+	 * It will return the time set in @ref setIdleTime() with an addition of the time
+	 * since you set this last time
+	 * @return time this contact has been idle for, in seconds
+	 //
+         // FIXME: Can we make this just 'unsigned long' ? QT Properties can't handle
+         // 'unsigned long int'
+	 */
+	virtual unsigned long int idleTime() const;
+
+	/**
+	 * \brief Set the current idle time in seconds.
+	 * Kopete will automatically calculate the time in @ref idleTime
+	 * except if you set 0.
+	 //
+	 // FIXME: Can we make this just 'unsigned long' ? QT Properties can't handle
+	 // 'unsigned long int'
+	 */
+	void setIdleTime(unsigned long int);
+
+	/**
+	 * @return A QStringList containing all property keys
+	 **/
+	QStringList properties() const;
+
+	/**
+	 * Check for existance of a certain property stored
+	 * using "key".
+	 * \param key the property to check for
+	 **/
+	bool hasProperty(const QString &key) const;
+
+	/**
+	 * \brief Get the value of a property with key "key".
+	 *
+	 * If you don't know the type of the returned QVariant, you will need
+	 * to check for it.
+	 * \return the value of the property
+	 **/
+	const Kopete::ContactProperty &property(const QString &key) const;
+	const Kopete::ContactProperty &property(const Kopete::ContactPropertyTmpl &tmpl) const;
+
+	/**
+	 * \brief Add or Set a property for this contact.
+	 *
+	 * @param tmpl The template this property is based on, key, label etc. are
+	 * taken from this one
+	 * @param value The value to store
+	 *
+	 * \note Setting a NULL value or an empty QString castable value
+	 * removes the property if it already existed.
+	 * <b>Don't</b> abuse this for property-removal, instead use
+	 * @ref removeProperty() if you want to remove on purpose.
+	 * The Removal is done to clean up the list of properties and to purge them
+	 * from UI.
+	 **/
+	void setProperty(const Kopete::ContactPropertyTmpl &tmpl, const QVariant &value);
+
+        /**
+	 * \brief Convenience method to set the nickName property to the specified value
+	 * @param name The nickname to set
+	 */
+	void setNickName( const QString &name );
+
+	/**
+	 * \brief Convenience method to retrieve the nickName property.
+	 *
+	 * This method will return the contactId if there has been no nickName property set
+	 */
+	QString nickName() const;
+
+	/**
+	 * \brief Remove a property if it exists
+	 *
+	 * @param tmpl the template this property is based on
+	 **/
+	void removeProperty(const Kopete::ContactPropertyTmpl &tmpl);
+
+	/**
+	 * \brief Get the tooltip for this contact
+	 * Makes use of formattedName() and formattedIdleTime().
+	 * \return an RTF tooltip depending on KopetePrefs settings
+	 **/
+	QString toolTip() const;
+
+	/**
+	 * Returns a formatted string of "firstName" and/or "lastName" properties
+	 * if present.
+	 * Suitable for GUI display
+	 **/
+	QString formattedName() const;
+
+	/**
+	 * Returns a formatted string of idleTime().
+	 * Suitable for GUI display
+	 **/
+	QString formattedIdleTime() const;
+
+	/**
+	 * used in @ref sync()
+	 */
+	enum Changed{ MovedBetweenGroup = 0x01, ///< the contact has been moved between groups
+		      DisplayNameChanged = 0x02 ///< the displayname of the contact changed
+	};
+
+
+public slots:
+	/**
+	 * This should typically pop up a KopeteChatWindow
+	 */
+	void startChat();
+
+	/**
+	 * Pops up an email type window
+	 */
+	void sendMessage();
+
+	/**
+	 * The user clicked on the contact, do the default action
+	 */
+	void execute();
+
+	/**
+	 * Changes the MetaContact that this contact is a part of.  This function
+	 * is called by the KAction changeMetaContact that is part of the context
+	 * menu.
+	 */
+	void changeMetaContact();
+
+	/**
+	 * Method to retrieve user information.  Should be implemented by
+	 * the protocols, and popup some sort of dialog box
+	 *
+	 * reimplement it to show the informlation
+	 * @todo rename and make it pure virtual
+	 */
+	virtual void slotUserInfo() {};
+
+	/**
+	 * @brief Syncronise the server and the metacontact.
+	 * Protocols with server-side contact lists can implement this to
+	 * sync the server groups with the metaContact groups. Or the server alias if any.
+	 *
+	 * This method is called every time the metacontact has been moved or renamed.
+	 *
+	 * default implementation does nothing
+	 *
+	 * @param changed is a bitmask of the @ref Changed enum which say why the call to this funtion is done.
+	 */
+	virtual void sync(unsigned int changed = 0xFF);
+
+	/**
+	 * Method to delete a contact from the contact list,
+	 * should be implemented by protocol plugin to handle
+	 * protocol-specific actions required to delete a contact
+	 * (ie. messages to the server, etc)
+	 * the default implementation simply call deleteLater()
+	 */
+	virtual void deleteContact();
+
+	/**
+	 * This is the Contact level slot for sending files. It should be
+	 * implemented by all contacts which have the setFileCapable() flag set to
+	 * true. If the function is called through the GUI, no parameters are sent
+	 * and they take on default values (the file is chosen with a file open dialog)
+	 *
+	 * @param sourceURL The actual KURL of the file you are sending
+	 * @param fileName (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  asocket
+	 */
+	virtual void sendFile( const KURL &sourceURL = KURL(),
+			       const QString &fileName = QString::null, uint fileSize = 0L );
+
+private slots:
+
+	/**
+	 * This add the contact totally in the list if it was a temporary contact
+	 */
+	void slotAddContact();
+
+	/**
+	 * slot called when the action "delete" is called.
+	 */
+	void slotDelete();
+
+	/**
+	 * slot called when the action "block" is called.
+	 */
+	void slotBlock();
+
+	/**
+	 * slot called when the action "unblock" is called.
+	 */
+	void slotUnblock();
+
+	/**
+	 * The account's isConnected has changed.
+	 */
+	void slotAccountIsConnectedChanged();
+
+signals:
+	/**
+	 * The contact's online status changed
+	 */
+	void onlineStatusChanged( Kopete::Contact *contact,
+		const Kopete::OnlineStatus &status, const Kopete::OnlineStatus &oldStatus );
+
+	/**
+	 * The contact is about to be destroyed.
+	 * Called when entering the destructor. Useful for cleanup, since
+	 * metaContact() is still accessible at this point.
+	 *
+	 * @warning this signal is emit in the Contact destructor, so all
+	 * virtual method are not available
+	 */
+	void contactDestroyed( Kopete::Contact *contact );
+
+	/**
+	 * The contact's idle state changed.
+	 * You need to emit this signal to update the view.
+	 * That mean when activity has been noticed
+	 */
+	void idleStateChanged( Kopete::Contact *contact );
+
+	/**
+	 * One of the contact's properties has changed.
+	 * @param contact this contact, useful for listening to signals from more than one contact
+	 * @param key the key whose value has changed
+	 * @param oldValue the value before the change, or an invalid QVariant if the property is new
+	 * @param newValue the value after the change, or an invalid QVariant if the property was removed
+	 */
+	void propertyChanged( Kopete::Contact *contact, const QString &key,
+		const QVariant &oldValue, const QVariant &newValue );
+
+protected:
+	virtual void virtual_hook(uint id, void *data);
+
+private:
+	class Private;
+	Private *d;
+
+
+};
+
+
+} //END namespace Kopete
+
+#endif
+
+// vim: set noet ts=4 sts=4 sw=4:
+