A class that holds properties. More...
#include <klfpobj.h>
Public Types | |
enum | ToStringFlag { ToStringUseHtml = 0x0001, ToStringUseHtmlDiv = 0x0002, ToStringQuoteValues = 0x0004, ToStringAllProperties = 0x0008 } |
Flags for tuning the toString() method. More... | |
Public Member Functions | |
KLFPropertizedObject (const QString &propertyNameSpace) | |
virtual | ~KLFPropertizedObject () |
virtual QVariant | property (const QString &propName) const |
virtual QVariant | property (int propId) const |
QList< int > | propertyIdList () const |
A list of properties that have been set. More... | |
QStringList | propertyNameList () const |
A list of properties that have been set. More... | |
QMap< QString, QVariant > | allProperties () const |
Returns all properties that have been set. More... | |
void | setAllProperties (const QMap< QString, QVariant > &propValues) |
Initializes properties to given values. More... | |
QByteArray | allPropertiesToByteArray () const |
Saves all the properties in binary form. More... | |
void | setAllPropertiesFromByteArray (const QByteArray &data) |
Loads all properties saved by allPropertiesToByteArray() More... | |
virtual QString | toString (uint toStringFlags=0) const |
Formats the property contents in a (human and/or parsable) string. More... | |
int | propertyMaxId () const |
See the corresponding protected static method. More... | |
bool | propertyIdRegistered (int propId) const |
See the corresponding protected static method. More... | |
bool | propertyNameRegistered (const QString &propertyName) const |
See the corresponding protected static method. More... | |
int | propertyIdForName (const QString &propertyName) const |
See the corresponding protected static method. More... | |
QString | propertyNameForId (int propId) const |
See the corresponding protected static method. More... | |
QList< int > | registeredPropertyIdList () const |
See the corresponding protected static method. More... | |
QStringList | registeredPropertyNameList () const |
See the corresponding protected static method. More... | |
QMap< QString, int > | registeredProperties () const |
See the corresponding protected static method. More... | |
Protected Member Functions | |
virtual void | propertyValueChanged (int propId, const QVariant &oldValue, const QVariant &newValue) |
virtual void | setProperty (const QString &propname, const QVariant &value) |
virtual void | setProperty (int propId, const QVariant &value) |
virtual int | loadProperty (const QString &propname, const QVariant &value) |
void | registerBuiltInProperty (int propId, const QString &propName) const |
int | registerProperty (const QString &propertyName) const |
QString | propertyNameSpace () const |
QVector< QVariant > | propertyVector () const |
Static Protected Member Functions | |
static void | registerBuiltInProperty (const QString &propNameSpace, int propId, const QString &name) |
static int | registerProperty (const QString &propNameSpace, const QString &propertyName) |
static int | propertyMaxId (const QString &propNameSpace) |
static bool | propertyIdRegistered (const QString &propNameSpace, int propId) |
static bool | propertyNameRegistered (const QString &propNameSpace, const QString &propertyName) |
static int | propertyIdForName (const QString &propNameSpace, const QString &propertyName) |
static QString | propertyNameForId (const QString &propNameSpace, int propId) |
static QList< int > | registeredPropertyIdList (const QString &propNameSpace) |
static QStringList | registeredPropertyNameList (const QString &propNameSpace) |
static QMap< QString, int > | registeredProperties (const QString &propNameSpace) |
Friends | |
bool | operator== (const KLFPropertizedObject &a, const KLFPropertizedObject &b) |
A class that holds properties.
This class is meant to be subclassed to create objects that need to store properties. For an example, see KLFLibEntry in the klfapp library.
Properties are stored in QVariants, are referenced either by an integer ID or a QString name.
A subclass will be an object of a given logical type, say a library entry. It may want to store a few standard properties (Latex string, Preview image, Category and Tags string, etc.). However, eg. plugins may be able to store and understand more advanced properties (say the icon's position when viewed in an icon view) than what the base class KLFLibEntry had anticipated. In that case, the property needs to be registered statically with registerProperty() or registerBuiltInProperty(). Properties are registered statically, that means that all instances of, say a KLFLibEntry, always share the same property ID and names, even though they each store different values for them.
Property values may be queried with property(const QString&) const or property(int propId) const , and may be set with setProperty().
Subclasses have to provide their own public API for setting and/or registering property values, as setProperty() and registerProperty() are protected. This is because depending on the subclass this operation should not be openly publicly permitted without any checks.
All instances of a given subclass, say a KLFLibEntry, have values assigned to all registered properties. By default, their values are an invalid QVariant: QVariant()
.
What is the Property Name Space? The Property Name Space is a string identifying the type of object an instance belongs to. This will typically be the subclass name. Since all registered properties are stored (the names and IDs, not the values (!)) statically in this object, different subclasses must access different registered properties, and that is what the "property name spaces" are meant for. Subclasses specify once and for all the property name space to the ructor, then they can forget about it. Other classes than the direct subclass don't have to know about property name spaces.
Flags for tuning the toString() method.
|
explicit |
Constructs a KLFPropertizedObject, that implements an object of the kind propertyNameSpace
. See the Class Documentation for more information on property name spaces.
Definition at line 32 of file klfpobj.cpp.
References KLFPropertizedObject().
Referenced by KLFPropertizedObject().
|
virtual |
Definition at line 37 of file klfpobj.cpp.
Returns all properties that have been set.
Definition at line 153 of file klfpobj.cpp.
References property(), propertyIdList(), propertyNameForId(), and QList::size().
Referenced by operator<<().
QByteArray KLFPropertizedObject::allPropertiesToByteArray | ( | ) | const |
Saves all the properties in binary form.
Basically flushes the output of allProperties() into a QByteArray.
Definition at line 175 of file klfpobj.cpp.
|
protectedvirtual |
Like setProperty()
, except the property name propname
is registered with registerProperty() if it is not registered.
Definition at line 113 of file klfpobj.cpp.
References propertyIdForName(), propId, registerProperty(), and setProperty().
Referenced by setAllProperties().
Returns the value of the property designated by the name propName
, in this current object instance.
If the property has not been registered, a warning is printed and this function returns an invalid QVariant.
If the property has not yet been set, an invalid QVariant() is returned.
Definition at line 42 of file klfpobj.cpp.
References KLF_FUNC_NAME, propertyIdForName(), and propId.
Referenced by allProperties(), operator==(), and toString().
|
virtual |
Returns the value of the property designated by its ID propId
in this current object instance.
If no value was previously set for the given property, and the property has been registered, returns an invalid QVariant().
This function does not check that propId
has been registered. However the worst that can happen is that an invalid QVariant() is returned.
Definition at line 52 of file klfpobj.cpp.
References KLF_FUNC_NAME, propId, and QVector::size().
int KLFPropertizedObject::propertyIdForName | ( | const QString & | propertyName | ) | const |
See the corresponding protected static method.
Shortcut for the corresponding (protected) static method propertyIdForName(const QString&, const QString&); the property name space is automatically detected.
Definition at line 280 of file klfpobj.cpp.
Referenced by loadProperty(), property(), propertyNameRegistered(), and setProperty().
|
staticprotected |
propertyName
in property name space propNameSpace
.If the property name space does not exist, or if the property does not exist in that name space, -1
is returned (silently).
The property name space propNameSpace
must exist or a warning message is issued.
Subclasses may prefer to use the more convenient function propertyIdForName(const QString&) const, which automatically uses the correct property name space.
Definition at line 341 of file klfpobj.cpp.
References QMap::contains(), KLF_FUNC_NAME, and QMap::value().
QList< int > KLFPropertizedObject::propertyIdList | ( | ) | const |
A list of properties that have been set.
More exactly: returns all property IDs that have a valid (see QVariant::isValid()) value in this object.
Definition at line 126 of file klfpobj.cpp.
References QVector::size().
Referenced by allProperties(), and toString().
bool KLFPropertizedObject::propertyIdRegistered | ( | int | propId | ) | const |
See the corresponding protected static method.
Shortcut for the corresponding (protected) static method propertyIdRegistered(const QString&, int). The property name space is automatically detected.
Definition at line 272 of file klfpobj.cpp.
Referenced by setProperty().
|
staticprotected |
propId
exists (=has been registered) in the property name space propNameSpace
.Subclasses may prefer to use the more convenient function propertyIdRegistered(int) const, which automatically uses the correct property name space.
Definition at line 332 of file klfpobj.cpp.
References propertyNameForId().
int KLFPropertizedObject::propertyMaxId | ( | ) | const |
See the corresponding protected static method.
Shortcut for the corresponding (protected) static method propertyMaxId(const QString&). The property name space is automatically detected.
Definition at line 268 of file klfpobj.cpp.
Referenced by setProperty().
|
staticprotected |
Returns a number that is guaranteed higher or equal to all registered property IDs in the given property name space.
Subclasses may prefer to use the more convenient function propertyMaxId() const, which automatically uses the correct property name space.
Definition at line 323 of file klfpobj.cpp.
References QMap::contains(), and KLF_FUNC_NAME.
QString KLFPropertizedObject::propertyNameForId | ( | int | propId | ) | const |
See the corresponding protected static method.
Shortcut for the corresponding (protected) static method propertyNameForId(const QString&, int); the property name space is automatically detected.
Definition at line 284 of file klfpobj.cpp.
Referenced by allProperties(), propertyIdRegistered(), propertyNameList(), and toString().
|
staticprotected |
Reverse operation of propertyIdForName(), with similar behavior.
This function silently returns QString()
on failure.
Subclasses may prefer to use the more convenient function propertyNameForId(int) const, which automatically uses the correct property name space.
Definition at line 353 of file klfpobj.cpp.
References QMap::contains(), QList::isEmpty(), QMap::keys(), KLF_FUNC_NAME, and QList::size().
QStringList KLFPropertizedObject::propertyNameList | ( | ) | const |
A list of properties that have been set.
Similar to propertyIdList() but returns property names.
Definition at line 138 of file klfpobj.cpp.
References propertyNameForId(), and QVector::size().
bool KLFPropertizedObject::propertyNameRegistered | ( | const QString & | propertyName | ) | const |
See the corresponding protected static method.
Shortcut for the corresponding (protected) static method propertyNameRegistered(const QString&, const QString&). The property name space is automatically detected.
Definition at line 276 of file klfpobj.cpp.
Referenced by setProperty().
|
staticprotected |
propertyName
exists (=has been registered) in the property name space propNameSpace
.Subclasses may prefer to use the more convenient function propertyNameRegistered(const QString&) const, which automatically uses the correct property name space.
Definition at line 336 of file klfpobj.cpp.
References propertyIdForName().
|
inlineprotected |
|
protectedvirtual |
This method is called whenever the value of a given property changes.
Subclasses may reimplement to watch the properties for changes. The default implementation does nothing.
propId | the property ID that changed |
oldValue | the previous value of the property |
newValue | the new value of the property |
Definition at line 68 of file klfpobj.cpp.
Referenced by setProperty().
Definition at line 398 of file klfpobj.h.
References operator<<(), operator==(), and operator>>().
|
protected |
shortcut for the corresponding static method. Detects the correct property name space and calls registerBuiltInProperty(const QString&, int, const QString&)
Definition at line 303 of file klfpobj.cpp.
|
staticprotected |
Registers the property named name
with the fixed ID propId
.
If the property is already registered with the exact same name and ID, then this function does nothing.
If the given property name or the given property ID is already registered, but the name or the ID doesn't match exactly, then a warning is printed and the property is not registered.
The property name has to be non-empty (QString::isEmpty()), or a warning is printed and the property is not registered.
Subclasses should call this function once per built-in property they want to register. For example this could be achieved with the following code:
Subclasses may prefer to use the more convenient function registerBuiltInProperty(int propId, const QString& propName), which automatically uses the correct property name space.
Definition at line 314 of file klfpobj.cpp.
See the corresponding protected static method.
Shortcut for the corresponding (protected) static method registeredProperties(const QString&); the property name space is automatically detected.
Definition at line 296 of file klfpobj.cpp.
|
staticprotected |
Returns a map of all registered properties, with the property names as map keys and the property IDs as map values, in the given property name space.
Subclasses may prefer to use the more convenient function registeredProperties(), which automatically uses the correct property name space.
Definition at line 391 of file klfpobj.cpp.
References QMap::contains(), QString::isEmpty(), QMap::keys(), KLF_FUNC_NAME, and propId.
QList< int > KLFPropertizedObject::registeredPropertyIdList | ( | ) | const |
See the corresponding protected static method.
Shortcut for the corresponding (protected) static method registeredPropertyIdList(const QString&); the property name space is automatically detected.
Definition at line 292 of file klfpobj.cpp.
Referenced by operator==(), and toString().
|
staticprotected |
Returns a list of all registered property IDs in the given property name space.
Subclasses may prefer to use the more convenient function registeredPropertyIdList(), which automatically uses the correct property name space.
Definition at line 380 of file klfpobj.cpp.
References QMap::contains(), KLF_FUNC_NAME, and QMap::values().
QStringList KLFPropertizedObject::registeredPropertyNameList | ( | ) | const |
See the corresponding protected static method.
Shortcut for the corresponding (protected) static method registeredPropertyNameList(const QString); the property name space is automatically detected.
Definition at line 288 of file klfpobj.cpp.
|
staticprotected |
Returns a list of all registered property names in the given property name space.
Subclasses may prefer to use the more convenient function registeredPropertyNameList(), which automatically uses the correct property name space.
Definition at line 370 of file klfpobj.cpp.
References QMap::contains(), QMap::keys(), and KLF_FUNC_NAME.
|
protected |
shortcut for the corresponding static method. Detects the correct property name space and calls registerProperty(const QString& propNameSpace, const QString& propName).
Definition at line 307 of file klfpobj.cpp.
Referenced by loadProperty().
|
staticprotected |
Registers the property propertyName
and assigns a new unused ID for that property, and returns the newly assigned ID.
If the property name is already registered, this function prints a warning and returns -1
.
The property name must be non-empty (see QString::isEmpty()), or this function will print a warning and return -1
.
Subclasses may prefer to use the more convenient function registerProperty(const QString&) const, which automatically uses the correct property name space.
Definition at line 319 of file klfpobj.cpp.
Initializes properties to given values.
Clears all properties that have been set and replaces them with those given in argument. Any property name in propValues
that doesn't exist in registered properties, is registered.
Definition at line 165 of file klfpobj.cpp.
References QMap::keys(), and loadProperty().
Referenced by operator>>().
void KLFPropertizedObject::setAllPropertiesFromByteArray | ( | const QByteArray & | data | ) |
Loads all properties saved by allPropertiesToByteArray()
Reads the properties from data
and calls setAllProperties().
Definition at line 186 of file klfpobj.cpp.
|
protectedvirtual |
Sets the given property to value
. If propname is not registered, this function fails.
Definition at line 74 of file klfpobj.cpp.
References KLF_FUNC_NAME, propertyIdForName(), and propertyNameRegistered().
Referenced by loadProperty().
|
protectedvirtual |
Sets the property identified by propId to the value value
. Fails if the property propId
is not registered.
Definition at line 83 of file klfpobj.cpp.
References KLF_FUNC_NAME, propertyIdRegistered(), propertyMaxId(), propertyValueChanged(), propId, QVector::resize(), and QVector::size().
|
virtual |
Formats the property contents in a (human and/or parsable) string.
toStringFlags | is a binary OR value of flags defined in ToStringFlag. |
Definition at line 194 of file klfpobj.cpp.
References QVariant::canConvert(), QVariant::isValid(), property(), propertyIdList(), propertyNameForId(), registeredPropertyIdList(), QString::replace(), QList::size(), QVariant::toString(), ToStringAllProperties, ToStringQuoteValues, ToStringUseHtml, ToStringUseHtmlDiv, and QVariant::typeName().
Referenced by operator<<().
|
friend |
Definition at line 459 of file klfpobj.cpp.