[KLF Application][KLF Tools][KLF Backend][KLF Home]
KLatexFormula Project
Public Types | Public Member Functions | Protected Member Functions | Static Protected Member Functions | Friends | List of all members
KLFPropertizedObject Class Reference

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

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 86 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 162 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 32 of file klfpobj.cpp.

References KLFPropertizedObject().

Referenced by KLFPropertizedObject().

KLFPropertizedObject::~KLFPropertizedObject ( )
virtual

Definition at line 37 of file klfpobj.cpp.

Member Function Documentation

QMap< QString, QVariant > KLFPropertizedObject::allProperties ( ) const

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.

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.

int KLFPropertizedObject::loadProperty ( const QString propname,
const QVariant value 
)
protectedvirtual

Like setProperty(), 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 113 of file klfpobj.cpp.

References propertyIdForName(), propId, registerProperty(), and setProperty().

Referenced by setAllProperties().

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.

Definition at line 42 of file klfpobj.cpp.

References KLF_FUNC_NAME, propertyIdForName(), and propId.

Referenced by allProperties(), operator==(), 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 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().

int KLFPropertizedObject::propertyIdForName ( const QString propNameSpace,
const QString propertyName 
)
staticprotected
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 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.

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

bool KLFPropertizedObject::propertyIdRegistered ( const QString propNameSpace,
int  propId 
)
staticprotected
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 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().

int KLFPropertizedObject::propertyMaxId ( const QString propNameSpace)
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().

QString KLFPropertizedObject::propertyNameForId ( const QString propNameSpace,
int  propId 
)
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.

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

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

bool KLFPropertizedObject::propertyNameRegistered ( const QString propNameSpace,
const QString propertyName 
)
staticprotected
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 336 of file klfpobj.cpp.

References propertyIdForName().

QString KLFPropertizedObject::propertyNameSpace ( ) const
inlineprotected

Definition at line 396 of file klfpobj.h.

void KLFPropertizedObject::propertyValueChanged ( int  propId,
const QVariant oldValue,
const QVariant newValue 
)
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.

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

Definition at line 68 of file klfpobj.cpp.

Referenced by setProperty().

QVector<QVariant> KLFPropertizedObject::propertyVector ( ) const
inlineprotected

Definition at line 398 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 303 of file klfpobj.cpp.

void KLFPropertizedObject::registerBuiltInProperty ( const QString propNameSpace,
int  propId,
const QString name 
)
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:

* // 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() {
*
* 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 314 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 296 of file klfpobj.cpp.

QMap< QString, int > KLFPropertizedObject::registeredProperties ( const QString propNameSpace)
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(), 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 292 of file klfpobj.cpp.

Referenced by operator==(), and toString().

QList< int > KLFPropertizedObject::registeredPropertyIdList ( const QString propNameSpace)
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.

QStringList KLFPropertizedObject::registeredPropertyNameList ( const QString propNameSpace)
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.

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 307 of file klfpobj.cpp.

Referenced by loadProperty().

int KLFPropertizedObject::registerProperty ( const QString propNameSpace,
const QString propertyName 
)
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.

void KLFPropertizedObject::setAllProperties ( const QMap< QString, QVariant > &  propValues)

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.

void KLFPropertizedObject::setProperty ( const QString propname,
const QVariant value 
)
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().

void KLFPropertizedObject::setProperty ( int  propId,
const QVariant value 
)
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().

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 194 of file klfpobj.cpp.

References QString::arg(), QVariant::canConvert(), QVariant::isValid(), property(), propertyIdList(), propertyNameForId(), registeredPropertyIdList(), QString::replace(), QList::size(), 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 459 of file klfpobj.cpp.


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

Generated by doxygen 1.8.5