/* This file is part of the KDE project Copyright (C) 2004 Cedric Pasteur Copyright (C) 2004 Alexander Dymo Copyright (C) 2004-2006 Jaroslaw Staniek This library is free software; you can redistribute it and/or modify it under the terms of the GNU Library General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public License for more details. You should have received a copy of the GNU Library General Public License along with this library; see the file COPYING.LIB. If not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, * Boston, MA 02110-1301, USA. */ #ifndef KPROPERTY_SET_H #define KPROPERTY_SET_H #include "koproperty_global.h" #include #include namespace KoProperty { class Property; class SetPrivate; /*! \brief Lists holding properties in groups \author Cedric Pasteur \author Alexander Dymo \author Jaroslaw Staniek */ class KOPROPERTY_EXPORT Set : public QObject { Q_OBJECT public: /*! \brief A class to iterate over a Set. It behaves like a QDictIterator. To use it: \code for(Set::Iterator it(set); it.current(); ++it) { .... } \endcode \author Cedric Pasteur \author Alexander Dymo */ class KOPROPERTY_EXPORT Iterator { public: Iterator(const Set &set); ~Iterator(); void operator ++(); Property* operator *() const; QCString currentKey() const; Property* current() const; private: QAsciiDictIterator *iterator; friend class Set; }; explicit Set(QObject *parent=0, const QString &typeName=QString::null); /*! Constructs a deep copy of \a set. The new object will not have a QObject parent even if \a set has such parent. */ explicit Set(const Set& set); virtual ~Set(); /*! Adds the property to the set, in the group. You can use any group name, except "common" (which is already used for basic group). */ void addProperty(Property *property, QCString group = "common"); /*! Removes property from the set. Emits aboutToDeleteProperty before removing.*/ void removeProperty(Property *property); /*! Removes property with the given name from the set. Emits aboutToDeleteProperty() before removing.*/ void removeProperty(const QCString &name); /*! Removes all properties from the property set and destroys them. */ virtual void clear(); /*! \return the number of items in the set. */ uint count() const; /*! \return true if the set is empty, i.e. count() == 0; otherwise returns false. */ bool isEmpty() const; /*! \return true if the set is read-only. In read-only property set, no property can be modified regardless of read-only flag of any property (see Property::isReadOnly()). On the other hand, if Property::isReadOnly() is true of a property and Set::isReadOnly() is false, the property is still read-only. Read-only property set prevents editing in the property editor. By default the set is read-write. */ bool isReadOnly() const; /*! Sets this set to be read-only. @see isReadOnly */ void setReadOnly(bool readOnly); /*! \return true if the set contains property names \a name. */ bool contains(const QCString &name) const; /*! \return property named with \a name. If no such property is found, null property (Property::null) is returned. */ Property& property( const QCString &name) const; /*! Accesses a property by it's name. Property reference is returned, so all property modifications are allowed. If there is no such property, null property is returned, so it's good practice to use contains() is you're unsure if the property exists. For example, to set a value of a property, use: /code Set set; ... if (!set.contains("myProperty")) { dosomething; } set["myProperty"].setValue("My Value"); /endcode \return \ref Property with given name. */ Property& operator[](const QCString &name) const; /*! Creates a deep copy of \a set and assigns it to this property set. */ const Set& operator= (const Set &set); /*! Change the value of property whose key is \a property to \a value. By default, it only calls Property::setValue(). */ void changeProperty(const QCString &property, const QVariant &value); /*! Sets the i18n'ed string that will be shown in Editor to represent \a group. */ void setGroupDescription(const QCString &group, const QString& desc); /*! \return the i18n'ed description string for \a group that will be shown in Editor to represent \a group. If there is no special description set for the group, \a group is just returned. */ QString groupDescription(const QCString &group) const; /*! Sets the icon name \a icon to be displayed for \a group. */ void setGroupIcon(const QCString &group, const QString& icon); /*! \return the icons name for \a group. */ QString groupIcon(const QCString &group) const; /*! \return a list of all group names. The order is the same as the order of creation. */ const QValueList& groupNames() const; /*! \return a list of all property names. The order is the same as the order of creation. */ const QValueList& propertyNamesForGroup(const QCString &group) const; /*! Used by property editor to preserve previous selection when this set is assigned again. */ QCString prevSelection() const; void setPrevSelection(const QCString& prevSelection); /*! A name of this property set type, that is usable when we want to know if two property set objects have the same type. This avoids e.g. reloading of all Editor's contents. Also, this allows to know if two property set objects are compatible by their property sets. For comparing purposes, type names are case insensitive.*/ QString typeName() const; /*! Prints debug output for this set. */ void debug(); protected: /*! Constructs a set which owns or does not own it's properties.*/ Set(bool propertyOwner); /*! Adds property to a group.*/ void addToGroup(const QCString &group, Property *property); /*! Removes property from a group.*/ void removeFromGroup(Property *property); /*! Adds the property to the set, in the group. You can use any group name, except "common" (which is already used for basic group). If \a updateSortingKey is true, the sorting key will be set automatically to count(). @internal */ void addPropertyInternal(Property *property, QCString group, bool updateSortingKey); /*! @internal used to declare that \a property wants to be informed that the set has been cleared (all properties are deleted) */ void informAboutClearing(bool& cleared); signals: /*! Emitted when the value of the property is changed.*/ void propertyChanged(KoProperty::Set& set, KoProperty::Property& property); /*! @internal Exists to be sure that we emitted it before propertyChanged(), so Editor object can handle this. */ void propertyChangedInternal(KoProperty::Set& set, KoProperty::Property& property); /*! Emitted when the value of the property is reset.*/ void propertyReset(KoProperty::Set& set, KoProperty::Property& property); /*! Emitted when property is about to be deleted.*/ void aboutToDeleteProperty(KoProperty::Set& set, KoProperty::Property& property); /*! Emitted when property set object is about to be cleared (using clear()). This signal is also emmited from destructor before emitting aboutToBeDeleted(). */ void aboutToBeCleared(); /*! Emitted when property set object is about to be deleted.*/ void aboutToBeDeleted(); protected: SetPrivate *d; friend class Iterator; friend class Property; friend class Buffer; }; /*! \brief \todo find a better name to show it's a set that doesn't own property \author Cedric Pasteur \author Alexander Dymo \author Adam Treat */ class KOPROPERTY_EXPORT Buffer : public Set { Q_OBJECT public: Buffer(); Buffer(const Set *set); /*! Intersects with other Set.*/ virtual void intersect(const Set *set); protected slots: void intersectedChanged(KoProperty::Set& set, KoProperty::Property& prop); void intersectedReset(KoProperty::Set& set, KoProperty::Property& prop); private: void initialSet(const Set *set); }; } #endif