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 |
virtual QVariant | property (const QString &propName, const QVariant &defaultValue) const |
Get value of a property, with default value. More... | |
virtual bool | hasPropertyValue (const QString &propName) const |
Tests if a property was set. More... | |
virtual bool | hasPropertyValue (int propId) const |
Tests if a property was set. More... | |
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... | |
virtual bool | setProperty (const QString &propname, const QVariant &value) |
Sets the given property to the given value. More... | |
virtual bool | setProperty (int propId, const QVariant &value) |
Sets the given property to the given value. More... | |
virtual bool | setAllProperties (const QMap< QString, QVariant > &propValues) |
Initializes properties to given values. More... | |
QDataStream & | streamInto (QDataStream &stream) const |
Explicit function name for the simple "operator<<" . More... | |
QDataStream & | streamFrom (QDataStream &stream) |
Explicit function name for the simple "operator>>" . 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... | |
virtual QString | objectKind () const |
![]() | |
KLFAbstractPropertizedObject () | |
virtual | ~KLFAbstractPropertizedObject () |
virtual bool | hasFixedTypes () const |
virtual QByteArray | typeNameFor (const QString &property) const |
Corresonding type for the given property. More... | |
virtual QByteArray | typeSpecificationFor (const QString &property) const |
A type specification for the given property. More... | |
Protected Member Functions | |
virtual void | propertyValueChanged (int propId, const QVariant &oldValue, const QVariant &newValue) |
virtual bool | doSetProperty (const QString &propname, const QVariant &value) |
virtual bool | doSetProperty (int propId, const QVariant &value) |
virtual int | doLoadProperty (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 should override setProperty() to add checks as to whether the user is indeed allowed to set the given property to the given value, and then calling the protected doSetProperty() or doLoadProperty() functions. Subclasses may also provide their own public API for setting and/or registering property values, which could directly call setProperty() with the relevant property name.
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 KLFPropertizedObject(const QString&) constructor, then they can forget about it. Other classes than the direct subclass don't have to know about property name spaces.
propId
is just an index in that vector. Keep that in mind before defining static high property IDs. Since property IDs are not fixed, it is better to have the static property IDs defined contiguously in an enum. 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 98 of file klfpobj.cpp.
References QMap::contains(), and KLFPropertizedObject().
Referenced by KLFPropertizedObject().
|
virtual |
Definition at line 108 of file klfpobj.cpp.
Returns all properties that have been set.
Reimplemented from KLFAbstractPropertizedObject.
Definition at line 251 of file klfpobj.cpp.
References property(), propertyIdList(), propertyNameForId(), and QList::size().
Referenced by operator<<(), and streamInto().
QByteArray KLFPropertizedObject::allPropertiesToByteArray | ( | ) | const |
Saves all the properties in binary form.
Basically flushes the output of allProperties() into a QByteArray.
For more advanced saving/loading techniques, see klfLoad() and klfSave().
Definition at line 297 of file klfpobj.cpp.
|
protectedvirtual |
Like doSetProperty()
, except the property name propname
is registered with registerProperty() if it is not registered.
Definition at line 210 of file klfpobj.cpp.
Referenced by setAllProperties(), and setProperty().
|
protectedvirtual |
Sets the given property to value
. If propname is not registered, this function fails.
Definition at line 170 of file klfpobj.cpp.
References KLF_FUNC_NAME, propertyIdForName(), and propertyNameRegistered().
|
protectedvirtual |
Sets the property identified by propId to the value value
. Fails if the property propId
is not registered.
Definition at line 179 of file klfpobj.cpp.
|
virtual |
Tests if a property was set.
Returns TRUE if the property propName
was registered and a non-invalid value set; returns FALSE otherwise.
This function does not fail or emit warnings. This function calls property(const QString&, const QVariant&).
Definition at line 150 of file klfpobj.cpp.
References QVariant::isValid(), and property().
Referenced by hasPropertyValue().
|
virtual |
Tests if a property was set.
Returns TRUE if the property propId
was registered and a non-invalid value set; returns FALSE otherwise.
This function does not fail or emit warnings. This function calls hasPropertyValue(const QString&).
Definition at line 155 of file klfpobj.cpp.
References hasPropertyValue(), propertyIdRegistered(), propertyNameForId(), and propId.
|
inlinevirtual |
Implements KLFAbstractPropertizedObject.
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.
Implements KLFAbstractPropertizedObject.
Definition at line 113 of file klfpobj.cpp.
References KLF_FUNC_NAME, propertyIdForName(), and propId.
Referenced by allProperties(), hasPropertyValue(), operator==(), property(), and toString().
|
virtual |
Get value of a property, with default value.
Returns the value of the property propName
, if this property name has been registered and a value set.
If the property name has not been registered, or if the property value is not valid (see QVariant::isValid()), then the value defaultValue
is returned as is.
This function does not fail or emit warnings.
Definition at line 138 of file klfpobj.cpp.
References QVariant::isValid(), property(), propertyIdForName(), and propId.
|
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 123 of file klfpobj.cpp.
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 419 of file klfpobj.cpp.
Referenced by doSetProperty(), and property().
|
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 480 of file klfpobj.cpp.
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 224 of file klfpobj.cpp.
References QVector::size().
Referenced by allProperties(), and toString().
|
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 471 of file klfpobj.cpp.
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 411 of file klfpobj.cpp.
Referenced by hasPropertyValue(), and setProperty().
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 407 of file klfpobj.cpp.
|
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 462 of file klfpobj.cpp.
|
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 492 of file klfpobj.cpp.
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 423 of file klfpobj.cpp.
Referenced by allProperties(), hasPropertyValue(), propertyNameList(), setProperty(), and toString().
|
virtual |
A list of properties that have been set.
Similar to propertyIdList() but returns property names.
Implements KLFAbstractPropertizedObject.
Definition at line 236 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 415 of file klfpobj.cpp.
Referenced by doSetProperty().
|
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 475 of file klfpobj.cpp.
|
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 164 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 453 of file klfpobj.cpp.
References propId.
|
protected |
shortcut for the corresponding static method. Detects the correct property name space and calls registerBuiltInProperty(const QString&, int, const QString&)
Definition at line 442 of file klfpobj.cpp.
References propId.
Referenced by KLFPObjPropRefHelper::registerbuiltinprop().
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 435 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 530 of file klfpobj.cpp.
References QMap::contains(), and KLF_FUNC_NAME.
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 431 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 519 of file klfpobj.cpp.
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 427 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 509 of file klfpobj.cpp.
|
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 446 of file klfpobj.cpp.
|
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 458 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.
This function bypasses all checks by calling loadProperty() directly. Reimplement this function for property name and value checking.
Reimplemented from KLFAbstractPropertizedObject.
Definition at line 277 of file klfpobj.cpp.
References doLoadProperty(), QMap::keys(), KLF_DEBUG_BLOCK, KLF_FUNC_NAME, klfDbg, and QList::size().
void KLFPropertizedObject::setAllPropertiesFromByteArray | ( | const QByteArray & | data | ) |
Loads all properties saved by allPropertiesToByteArray()
Reads the properties from data
and calls setAllProperties().
For more advanced saving/loading techniques, see klfLoad() and klfSave().
Definition at line 308 of file klfpobj.cpp.
Sets the given property to the given value.
If propname is not registered, this function tries to register the property.
Subclasses should reimplement this function to provide tests as to whether the user is allowed to modify the given property with the given value, and then actually set the property and register it if needed.
The default implementation just calls doLoadProperty() without any checks.
This function is an implementation of the KLFAbstractPropertizedObject::setProperty() pure virtual function.
Implements KLFAbstractPropertizedObject.
Definition at line 263 of file klfpobj.cpp.
References doLoadProperty().
Referenced by setProperty().
|
virtual |
Sets the given property to the given value.
Calls setProperty(const QString&, const QVariant&) with the relevant property name. Thus, in principle, subclasses only need to reimplement the other method.
Definition at line 268 of file klfpobj.cpp.
References KLF_ASSERT_CONDITION, propertyIdRegistered(), propertyNameForId(), propId, and setProperty().
QDataStream & KLFPropertizedObject::streamFrom | ( | QDataStream & | stream | ) |
Explicit function name for the simple "operator>>"
.
Somewhat the opposite of streamInto().
For more advanced saving/loading techniques, see klfLoad() and klfSave().
Definition at line 623 of file klfpobj.cpp.
QDataStream & KLFPropertizedObject::streamInto | ( | QDataStream & | stream | ) | const |
Explicit function name for the simple "operator<<"
.
For more advanced saving/loading techniques, see klfLoad() and klfSave().
Definition at line 618 of file klfpobj.cpp.
References allProperties().
|
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 333 of file klfpobj.cpp.
References QString::arg(), QVariant::canConvert(), QVariant::isValid(), property(), propertyIdList(), propertyNameForId(), registeredPropertyIdList(), QString::replace(), QList::size(), QString::toHtmlEscaped(), QVariant::toString(), ToStringAllProperties, ToStringQuoteValues, ToStringUseHtml, ToStringUseHtmlDiv, and QVariant::typeName().
Referenced by operator<<().
|
friend |
Definition at line 603 of file klfpobj.cpp.