[KLF Backend][KLF Tools][KLF Home]
KLatexFormula Project
Public Types | Public Member Functions | Protected Member Functions | Static Protected Member Functions | Friends
KLFPropertizedObject Class Reference

A class that holds properties. More...

#include <klfpobj.h>

Inheritance diagram for KLFPropertizedObject:
Inheritance graph
[legend]
Collaboration diagram for KLFPropertizedObject:
Collaboration graph
[legend]

List of all members.

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, QVariantallProperties () 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.
QDataStreamstreamInto (QDataStream &stream) const
 Explicit function name for the simple "operator<<".
QDataStreamstreamFrom (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< QVariantpropertyVector () 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)

Detailed Description

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().

Warning:
the IDs may not be conserved between two instances or versions of KLatexFormula, because they may be attributed dynamically, or values in a static enum may change from one version of, say a KLFLibEntry, to another. When exporting property values, always use the string identifier (see for example allProperties())

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.

Note:
For fast access, the property values are stored in a QVector<QVariant>. The 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.

Definition at line 277 of file klfpobj.h.


Member Enumeration Documentation

Flags for tuning the toString() method.

Enumerator:
ToStringUseHtml 

Encapsulates output in an HTML <table> and escapes strings.

ToStringUseHtmlDiv 

Uses <div> with CSS classes instead of a table (HTML only)

ToStringQuoteValues 

Ensures that non-html output is machine parsable.

ToStringAllProperties 

Include also all non-explicitely-set properties.

Definition at line 457 of file klfpobj.h.


Constructor & Destructor Documentation

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().

Definition at line 109 of file klfpobj.cpp.


Member Function Documentation

Returns all properties that have been set.

Returns:
a QMap of all properties (and their values) that have been set on this object, values stored by property name.

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.

Returns:
The property ID that was set or -1 for failure.

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.

Returns:
TRUE for success.

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.

Returns:
TRUE for success.

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.

Definition at line 509 of file klfpobj.h.

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]
Returns:
the ID corresponding to property name 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().

A list of properties that have been set.

Returns:
list of the IDs of all properties that have been set on this object. The values of these properties are NOT included in the returned list.

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]
Returns:
true if a property with ID 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().

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.

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().

A list of properties that have been set.

Similar to propertyIdList() but returns property names.

Returns:
list of the names of all properties that have been set on this object. values of these properties are not included in the list...

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]
Returns:
true if a property of name 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.

Parameters:
propIdthe property ID that changed
oldValuethe previous value of the property
newValuethe new value of the property

Definition at line 165 of file klfpobj.cpp.

Referenced by doSetProperty().

QVector<QVariant> KLFPropertizedObject::propertyVector ( ) const [inline, protected]

Definition at line 699 of file klfpobj.h.

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
Note:
If property name space does not exist, it is created.

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.

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.

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().

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().

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>>().

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.

Parameters:
toStringFlagsis 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<<().


Friends And Related Function Documentation

bool operator== ( const KLFPropertizedObject a,
const KLFPropertizedObject b 
) [friend]
Returns:
TRUE if all values for all registered properties of this object are equal.

Definition at line 604 of file klfpobj.cpp.


The documentation for this class was generated from the following files:

Generated by doxygen 1.7.6.1. The KLatexFormula website is hosted on sourceforge.net