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. | |
virtual bool | hasPropertyValue (const QString &propName) const |
Tests if a property was set. | |
virtual bool | hasPropertyValue (int propId) const |
Tests if a property was set. | |
QList< int > | propertyIdList () const |
A list of properties that have been set. | |
QStringList | propertyNameList () const |
A list of properties that have been set. | |
QMap< QString, QVariant > | allProperties () const |
Returns all properties that have been set. | |
virtual bool | setProperty (const QString &propname, const QVariant &value) |
Sets the given property to the given value. | |
virtual bool | setProperty (int propId, const QVariant &value) |
Sets the given property to the given value. | |
virtual bool | setAllProperties (const QMap< QString, QVariant > &propValues) |
Initializes properties to given values. | |
QDataStream & | streamInto (QDataStream &stream) const |
Explicit function name for the simple "operator<<" . | |
QDataStream & | streamFrom (QDataStream &stream) |
Explicit function name for the simple "operator>>" . | |
QByteArray | allPropertiesToByteArray () const |
Saves all the properties in binary form. | |
void | setAllPropertiesFromByteArray (const QByteArray &data) |
Loads all properties saved by allPropertiesToByteArray() | |
virtual QString | toString (uint toStringFlags=0) const |
Formats the property contents in a (human and/or parsable) string. | |
int | propertyMaxId () const |
See the corresponding protected static method. | |
bool | propertyIdRegistered (int propId) const |
See the corresponding protected static method. | |
bool | propertyNameRegistered (const QString &propertyName) const |
See the corresponding protected static method. | |
int | propertyIdForName (const QString &propertyName) const |
See the corresponding protected static method. | |
QString | propertyNameForId (int propId) const |
See the corresponding protected static method. | |
QList< int > | registeredPropertyIdList () const |
See the corresponding protected static method. | |
QStringList | registeredPropertyNameList () const |
See the corresponding protected static method. | |
QMap< QString, int > | registeredProperties () const |
See the corresponding protected static method. | |
virtual QString | objectKind () const |
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.
Flags for tuning the toString() method.
KLFPropertizedObject::KLFPropertizedObject | ( | const QString & | propertyNameSpace | ) | [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 99 of file klfpobj.cpp.
References QMap::contains(), and KLFPropertizedObject().
Referenced by KLFPropertizedObject().
KLFPropertizedObject::~KLFPropertizedObject | ( | ) | [virtual] |
Definition at line 109 of file klfpobj.cpp.
QMap< QString, QVariant > KLFPropertizedObject::allProperties | ( | ) | const [virtual] |
Returns all properties that have been set.
Reimplemented from KLFAbstractPropertizedObject.
Definition at line 252 of file klfpobj.cpp.
References property(), propertyIdList(), propertyNameForId(), and QList::size().
Referenced by operator<<(), and streamInto().
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 298 of file klfpobj.cpp.
int KLFPropertizedObject::doLoadProperty | ( | const QString & | propname, |
const QVariant & | value | ||
) | [protected, virtual] |
Like doSetProperty()
, except the property name propname
is registered with registerProperty() if it is not registered.
Definition at line 211 of file klfpobj.cpp.
References doSetProperty(), klfDbg, propertyIdForName(), propId, and registerProperty().
Referenced by setAllProperties(), and setProperty().
bool KLFPropertizedObject::doSetProperty | ( | const QString & | propname, |
const QVariant & | value | ||
) | [protected, virtual] |
Sets the given property to value
. If propname is not registered, this function fails.
Definition at line 171 of file klfpobj.cpp.
References KLF_FUNC_NAME, propertyIdForName(), and propertyNameRegistered().
Referenced by doLoadProperty().
bool KLFPropertizedObject::doSetProperty | ( | int | propId, |
const QVariant & | value | ||
) | [protected, virtual] |
Sets the property identified by propId to the value value
. Fails if the property propId
is not registered.
Definition at line 180 of file klfpobj.cpp.
References KLF_FUNC_NAME, propertyIdRegistered(), propertyMaxId(), propertyValueChanged(), propId, QVector::resize(), and QVector::size().
bool KLFPropertizedObject::hasPropertyValue | ( | const QString & | propName | ) | const [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 151 of file klfpobj.cpp.
References QVariant::isValid(), and property().
Referenced by hasPropertyValue().
bool KLFPropertizedObject::hasPropertyValue | ( | int | propId | ) | const [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 156 of file klfpobj.cpp.
References hasPropertyValue(), propertyIdRegistered(), and propertyNameForId().
virtual QString KLFPropertizedObject::objectKind | ( | ) | const [inline, virtual] |
Implements KLFAbstractPropertizedObject.
QVariant KLFPropertizedObject::property | ( | const QString & | propName | ) | const [virtual] |
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 114 of file klfpobj.cpp.
References KLF_FUNC_NAME, propertyIdForName(), and propId.
Referenced by allProperties(), hasPropertyValue(), operator==(), property(), and toString().
QVariant KLFPropertizedObject::property | ( | int | propId | ) | const [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 124 of file klfpobj.cpp.
References KLF_FUNC_NAME, propId, and QVector::size().
QVariant KLFPropertizedObject::property | ( | const QString & | propName, |
const QVariant & | defaultValue | ||
) | const [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 139 of file klfpobj.cpp.
References QVariant::isValid(), property(), propertyIdForName(), and propId.
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 420 of file klfpobj.cpp.
Referenced by doLoadProperty(), doSetProperty(), property(), and propertyNameRegistered().
int KLFPropertizedObject::propertyIdForName | ( | const QString & | propNameSpace, |
const QString & | propertyName | ||
) | [static, protected] |
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 481 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 225 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 412 of file klfpobj.cpp.
Referenced by doSetProperty(), hasPropertyValue(), and setProperty().
bool KLFPropertizedObject::propertyIdRegistered | ( | const QString & | propNameSpace, |
int | propId | ||
) | [static, protected] |
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 472 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 408 of file klfpobj.cpp.
Referenced by doSetProperty().
int KLFPropertizedObject::propertyMaxId | ( | const QString & | propNameSpace | ) | [static, protected] |
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 463 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 424 of file klfpobj.cpp.
Referenced by allProperties(), hasPropertyValue(), propertyIdRegistered(), propertyNameList(), setProperty(), and toString().
QString KLFPropertizedObject::propertyNameForId | ( | const QString & | propNameSpace, |
int | propId | ||
) | [static, protected] |
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 493 of file klfpobj.cpp.
References QMap::contains(), QList::isEmpty(), QMap::keys(), KLF_FUNC_NAME, and QList::size().
QStringList KLFPropertizedObject::propertyNameList | ( | ) | const [virtual] |
A list of properties that have been set.
Similar to propertyIdList() but returns property names.
Implements KLFAbstractPropertizedObject.
Definition at line 237 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 416 of file klfpobj.cpp.
Referenced by doSetProperty().
bool KLFPropertizedObject::propertyNameRegistered | ( | const QString & | propNameSpace, |
const QString & | propertyName | ||
) | [static, protected] |
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 476 of file klfpobj.cpp.
References propertyIdForName().
QString KLFPropertizedObject::propertyNameSpace | ( | ) | const [inline, protected] |
Definition at line 697 of file klfpobj.h.
Referenced by KLFPObjPropRefHelper::propertyNameSpace().
void KLFPropertizedObject::propertyValueChanged | ( | int | propId, |
const QVariant & | oldValue, | ||
const QVariant & | newValue | ||
) | [protected, virtual] |
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 165 of file klfpobj.cpp.
Referenced by doSetProperty().
QVector<QVariant> KLFPropertizedObject::propertyVector | ( | ) | const [inline, protected] |
void KLFPropertizedObject::registerBuiltInProperty | ( | int | propId, |
const QString & | propName | ||
) | const [protected] |
shortcut for the corresponding static method. Detects the correct property name space and calls registerBuiltInProperty(const QString&, int, const QString&)
Definition at line 443 of file klfpobj.cpp.
Referenced by KLFPObjPropRefHelper::registerbuiltinprop().
void KLFPropertizedObject::registerBuiltInProperty | ( | const QString & | propNameSpace, |
int | propId, | ||
const QString & | name | ||
) | [static, protected] |
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:
// mybook.h class MyBook : public KLFPropertizedObject { public: enum { PropTitle, PropAuthor, PropEditor, PropYear }; MyBook(); ... // API to access/write properties private: static void initBuiltInProperties(); }; MyBook::MyBook() : KLFPropertizedObject("MyBook") { initBuiltInProperties(); } void MyBook::initBuiltInProperties() { KLF_FUNC_SINGLE_RUN ; registerBuiltInProperty(PropTitle, "Title"); registerBuiltInProperty(PropAuthor, "Author"); registerBuiltInProperty(PropEditor, "Editor"); registerBuiltInProperty(PropYear, "Year"); } ... // other function definitions
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 454 of file klfpobj.cpp.
QMap< QString, int > KLFPropertizedObject::registeredProperties | ( | ) | const |
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 436 of file klfpobj.cpp.
QMap< QString, int > KLFPropertizedObject::registeredProperties | ( | const QString & | propNameSpace | ) | [static, protected] |
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 531 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 432 of file klfpobj.cpp.
Referenced by operator==(), and toString().
QList< int > KLFPropertizedObject::registeredPropertyIdList | ( | const QString & | propNameSpace | ) | [static, protected] |
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 520 of file klfpobj.cpp.
References QMap::contains(), KLF_FUNC_NAME, and QMap::values().
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 428 of file klfpobj.cpp.
QStringList KLFPropertizedObject::registeredPropertyNameList | ( | const QString & | propNameSpace | ) | [static, protected] |
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 510 of file klfpobj.cpp.
References QMap::contains(), QMap::keys(), and KLF_FUNC_NAME.
int KLFPropertizedObject::registerProperty | ( | const QString & | propertyName | ) | const [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 447 of file klfpobj.cpp.
Referenced by doLoadProperty().
int KLFPropertizedObject::registerProperty | ( | const QString & | propNameSpace, |
const QString & | propertyName | ||
) | [static, protected] |
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 459 of file klfpobj.cpp.
bool KLFPropertizedObject::setAllProperties | ( | const QMap< QString, QVariant > & | propValues | ) | [virtual] |
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 278 of file klfpobj.cpp.
References doLoadProperty(), QMap::keys(), KLF_DEBUG_BLOCK, KLF_FUNC_NAME, klfDbg, and QList::size().
Referenced by streamFrom().
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 309 of file klfpobj.cpp.
bool KLFPropertizedObject::setProperty | ( | const QString & | propname, |
const QVariant & | value | ||
) | [virtual] |
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 264 of file klfpobj.cpp.
References doLoadProperty().
Referenced by setProperty().
bool KLFPropertizedObject::setProperty | ( | int | propId, |
const QVariant & | value | ||
) | [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 269 of file klfpobj.cpp.
References KLF_ASSERT_CONDITION, propertyIdRegistered(), propertyNameForId(), 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 624 of file klfpobj.cpp.
References setAllProperties().
Referenced by operator>>().
QDataStream & KLFPropertizedObject::streamInto | ( | QDataStream & | stream | ) | const |
Explicit function name for the simple "operator<<"
.
QDataStream stream(...); pobj.streamInto(stream); // is equivalent to: stream << pobj;
For more advanced saving/loading techniques, see klfLoad() and klfSave().
Definition at line 619 of file klfpobj.cpp.
References allProperties().
Referenced by operator<<().
QString KLFPropertizedObject::toString | ( | uint | toStringFlags = 0 | ) | const [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 334 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<<().
bool operator== | ( | const KLFPropertizedObject & | a, |
const KLFPropertizedObject & | b | ||
) | [friend] |
Definition at line 604 of file klfpobj.cpp.