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, 350 insertions, 0 deletions

diff --git a/kopete/libkopete/kopeteproperties.h b/kopete/libkopete/kopeteproperties.h
new file mode 100644
index 00000000..bfeaedea
--- /dev/null
+++ b/kopete/libkopete/kopeteproperties.h
@@ -0,0 +1,350 @@
+/*
+    kopeteproperties.h - Kopete Properties
+
+    Copyright (c) 2004      by Richard Smith         <kde@metafoo.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 KOPETEPROPERTIES_H
+#define KOPETEPROPERTIES_H
+
+#include <qasciidict.h>
+
+#include <typeinfo>
+
+class QString;
+class QVariant;
+class QDomElement;
+
+namespace Kopete
+{
+
+/**
+ * Contains the classes forming Kopete's Properties system.
+ *
+ * @todo Explain more, give examples.
+ *
+ * @author Richard Smith <kde@metafoo.co.uk>
+ */
+namespace Properties
+{
+
+//BEGIN core functionality
+
+/**
+ * @brief Property-type-independent base class for properties
+ *
+ * The base class for all properties of any type which can be set or got for @p Parent
+ * objects. It is rare to need to use this class directly. Usually you will want to use
+ * the @ref Property derived class, or dynamic_cast the PropertyBase object to another interface.
+ *
+ * @see Property UserVisible XMLSerializable StringSerializable
+ *
+ * @author Richard Smith <kde@metafoo.co.uk>
+ */
+template<class Parent>
+class PropertyBase
+{
+public:
+	/**
+	 * Returns the name of the property. This name should uniquely identify this property
+	 * within the type Parent, and will be used for persistently identifying this property.
+	 *
+	 * For core properties, the chosen name should not contain any slash characters. For
+	 * properties defined in plugins kept in Kopete's CVS, the name should be of the form
+	 * pluginName/propertyName. For third-party plugins, please use a URL with a host which
+	 * you own, such as "http://my-host.com/kopete/properties/groupId".
+	 *
+	 * @return the name of this property.
+	 */
+	virtual const char *name() const = 0;
+};
+
+/**
+ * @brief Property-type-dependent base class for properties
+ *
+ * This class represents a property of type @p Type applicable to @p Parent objects. Usage
+ * of this class is usually as simple as:
+ *
+ * \code
+ * SomeParent *propertyContainer = ...
+ * Property<SomeParent,QString> &myProperty = ...
+ * QString value = propertyContainer->property(myProperty);
+ * propertyContainer->setProperty(myProperty, "hello");
+ * \endcode
+ *
+ * You should never need to call functions in this class directly.
+ */
+template<class Parent, typename Type>
+class Property : public PropertyBase<Parent>
+{
+public:
+	/**
+	 * Returns the value of this property in the object @p parent.
+	 */
+	virtual Type get( const Parent *parent ) const = 0;
+	/**
+	 * Sets the value of this property in the object @p parent.
+	 */
+	virtual void set( Parent *, const Type & ) const = 0;
+};
+
+/**
+ * @brief Base class for property data objects
+ *
+ * Some property objects want to store property-specific data in their parent objects.
+ * To support that, subclasses of this class are permitted to be stored. Once passed
+ * to the @ref PropertyStorage object via @ref PropertyStorage::setCustomPropertyData,
+ * the @ref PropertyStorage object owns the PropertyData, and will delete it when it
+ * is no longer needed.
+ */
+struct PropertyData
+{
+	virtual ~PropertyData() {}
+};
+
+/**
+ * @brief Storage object for PropertyData objects
+ *
+ * This class is responsible for storing PropertyData-derived data objects for properties.
+ * This is the non-templated part of the @ref WithProperties class, split out into its own
+ * class to eliminate the template bloat.
+ */
+class PropertyStorage
+{
+	typedef QAsciiDict<PropertyData> PropertyDict;
+	// setCustomPropertyData can be called on a const object, allowing the
+	// guarantee that DataProperty::data() never returns 0.
+	mutable PropertyDict _storage;
+
+public:
+	PropertyStorage() { _storage.setAutoDelete( true ); }
+
+	/**
+	 * Sets the stored property data with name @p name to be @p data.
+	 *
+	 * @note The @p name argument should usually be the name of the property which the data
+	 * is being stored for. However, if properties wish to share data, they may choose to
+	 * name their custom data differently. Names are bound by the same rules as are laid out
+	 * for naming properties in PropertyBase<Parent>::name.
+	 */
+	void setCustomPropertyData( const char *name, PropertyData *data ) const { _storage.replace( name, data ); }
+
+	/**
+	 * Gets the stored property data with name @p name. Returns a null
+	 * pointer if no data has been stored for that property.
+	 */
+	PropertyData *getCustomPropertyData( const char *name ) const { return _storage[name]; }
+};
+
+/**
+ * @brief Base class for classes to which properties can be applied
+ *
+ * This class provides support for properties to another class. If you want your class
+ * to support properties, derive from this passing your class as the Parent parameter:
+ *
+ * \code
+ * class YourClass : public WithProperties<YourClass> { ... };
+ * \endcode
+ *
+ * You will also need to explicitly specialise the propertyCreated() member function to
+ * load property data upon creation of a new property object.
+ */
+template<class Parent>
+class WithProperties : public PropertyStorage
+{
+public:
+	/**
+	 * Get the value of property @p prop in this object.
+	 * @param prop the Property object representing the property to get
+	 */
+	template<typename T>
+	T property( Property<Parent,T> const &prop ) { return prop.get( static_cast<Parent*>(this) ); }
+	/**
+	 * Set the value of property @p prop in this object.
+	 * @param prop the Property object representing the property to get
+	 * @param value the value to set the property to
+	 */
+	template<typename T>
+	void setProperty( Property<Parent,T> const &prop, const T &value ) { prop.set( static_cast<Parent*>(this), value ); }
+
+	/**
+	 * Called when a property is created; loads the Parent object's data into the property.
+	 *
+	 * @note Derived classes must explicitly specialize this to load the property's data into
+	 *       every object of this type.
+	 */
+	static void propertyCreated( const PropertyBase<Parent> &property );
+};
+
+//END core functionality
+
+//BEGIN interfaces
+
+/**
+ * @brief An interface for user-visible properties
+ * @todo document
+ */
+template<class Parent>
+struct UserVisible
+{
+	virtual QString userText( Parent * ) = 0;
+	virtual QString label() = 0;
+	virtual QString icon() = 0;
+};
+
+/**
+ * @brief An interface for properties which can be serialized as XML
+ * @todo document
+ */
+template<class Parent>
+struct XMLSerializable
+{
+	virtual void fromXML( Parent *, const QDomElement & ) = 0;
+	virtual void toXML( const Parent *, QDomElement & ) = 0;
+};
+
+/**
+ * @brief An interface for properties which can be serialized as strings
+ * @todo document
+ */
+template<class Parent>
+struct StringSerializable
+{
+	virtual void fromString( Parent *, const QString & ) = 0;
+	virtual QString toString( const Parent * ) = 0;
+};
+
+//END interfaces
+
+//BEGIN convenience classes
+
+/**
+ * @internal Display a warning message when the wrong type of property data is found
+ */
+void customPropertyDataIncorrectType( const char *name, const std::type_info &found, const std::type_info &expected );
+
+/**
+ * @brief Convenience implementation of a Property that stores PropertyData
+ *
+ * A property for objects of type @p Parent, that stores data in the class @p Data.
+ * @p Data must be derived from @ref PropertyBase, or your code will not compile.
+ */
+template<class Parent, typename Type, class Data>
+class DataProperty : public Property<Parent,Type>
+{
+public:
+	Data *data( const Parent *c ) const
+	{
+		PropertyData *pd = c->getCustomPropertyData( this->name() );
+		Data *data = dynamic_cast<Data*>(pd);
+		if ( !data )
+		{
+			if ( pd )
+				customPropertyDataIncorrectType( this->name(), typeid(*pd), typeid(Data) );
+			data = new Data;
+			c->setCustomPropertyData( this->name(), data );
+		}
+		return data;
+	}
+};
+
+/**
+ * @brief Convenience implementation of a PropertyData subclass which stores a single datum
+ *
+ * If a @ref Property needs to store only a single value in an object, using this
+ * class is simpler than deriving from @ref PropertyData yourself. The value will
+ * be default-constructed (which means for numeric types and pointers it will be
+ * set to 0).
+ */
+template<typename T>
+struct SimplePropertyData : public PropertyData
+{
+	SimplePropertyData() : value() {}
+	T value;
+};
+
+/**
+ * @brief Convenience implementation of a Property which stores a single datum as PropertyData
+ *
+ * This convenience class implements the @ref Property interface by simply storing and
+ * retrieving the datum from PropertyData. This class does not provide any serialization
+ * of the data.
+ *
+ * @note You will need to derive from this class to use it; the @ref name function is
+ * still pure virtual.
+ */
+template<class Parent, typename Type>
+class SimpleDataProperty : public DataProperty<Parent,Type,SimplePropertyData<Type> >
+{
+public:
+	Type get( const Parent *p ) const { return data(p)->value; }
+	void set( Parent *p, const Type &v ) const { data(p)->value = v; }
+};
+
+/**
+ * Move somewhere else
+ * @{
+ */
+
+/**
+ * Explicitly specialised for all types QVariant supports
+ */
+template<class T> T variantTo(QVariant);
+
+QVariant variantFromXML(const QDomElement&);
+void variantToXML(QVariant v, QDomElement &);
+
+/**
+ * @}
+ */
+
+/**
+ * @brief Convenience implementation of XMLSerializable in terms of QVariants
+ *
+ * This class provides XML serialization for data that can be stored in a QVariant. You
+ * will need to multiply-inherit from this class and (usually indirectly) from @ref Property.
+ *
+ * You can combine this class with other convenience classes such as SimpleDataProperty
+ * like this:
+ *
+ * \code
+ * class ContactNickNameProperty
+ *     : public SimpleDataProperty<Contact,QString>
+ *     , XMLProperty<ContactNickNameProperty,Contact,QString>
+ * {
+ * public:
+ *   const char *name() const { return "nickName"; }
+ * };
+ * \endcode
+ */
+template<class Derived, class Parent, typename Type>
+class XMLProperty : public XMLSerializable<Parent>
+{
+public:
+	void fromXML( Parent *t, const QDomElement &e )
+	{
+		static_cast<Derived*>(this)->set(t, variantTo<Type>(variantFromXML(e)));
+	}
+	void toXML( const Parent *t, QDomElement &e )
+	{
+		variantToXML(QVariant(static_cast<Derived*>(this)->get(t)),e);
+	}
+};
+
+//END convenience classes
+
+} // namespace Properties
+
+} // namespace Kopete
+
+#endif