Home


ClassesAnnotated - TreeFunctionsHomeStructure

Properties


Qt provides a sophisticated property system similar to those of other application development frameworks shipped by certain compiler vendors. However, as a compiler-independent multi-platform library, Qt cannot rely on non-standard compiler features like "__property" or "[property]". Our solution works with any standard C++ compiler on every platform we support. It's based on the Meta Object System that also provides object communication through signals and slots.

The "Q_PROPERTY" macro in a class declaration declares a property. Properties can only be declared in classes that inherit QObject. A second macro "Q_OVERRIDE" can be used to override certain aspects of an inherited property in a subclass.

To the outer world, a property appears quite similar to a data member. However, properties have several features that distinguish them from data members:

In addition, properties can be read and written through generic functions in QObject without knowing anything about the actual class. Through the Meta Object of a class, it is possible to query all available properties of a given instance of a class, again without knowing anything about the class apart from the fact that it inherits QObject.

Here's an example:

    class MyClass : public QObject
    {
        Q_OBJECT
    public:
        MyClass( QObject * parent=0, const char * name=0 );
        ~MyClass();

        enum Priority { High, Low, VeryHigh, VeryLow };
        void setPriority( Priority );
        Priority priority() const;
    };

The class has a property "priority" that is not yet known to the meta object system. In order to make the property known, you have to declare it with the "Q_PROPERTY" macro. The syntax is as follows:

Q_PROPERTY( type name READ getFunction [ WRITE setFunction] )

For the declaration to be valid, the get function has to return either the type itself or a pointer respectively a reference to it. The optional write function has to return void and to take exactly one argument, either the type itself or a pointer respectively a const reference to it. For obvious reasons, get functions have to be declared const. The meta object compiler will ensure all these constraints. Invalid properties, i.e. properties with an invalid type or illegal get function, will not show up in the property system.

The type of a property can be everything QVariant provides or an enumeration type declared in the class itself. Since MyClass uses the enumeration type Priority for the property, this type has to be registered with the property system as well. This way it will be possible to set any value just by its textual name, simply with

   obj->setProperty( "priority", "VeryHigh" );

Enumeration types are registered with the "Q_ENUMS" macro.

Here's the final class declaration including the property declaration:

    class MyClass : public QObject
    {
        Q_OBJECT
        Q_PROPERTY( Priority priority READ priority WRITE setPriority )
        Q_ENUMS( Priority )
    public:
        MyClass( QObject * parent=0, const char * name=0 );
        ~MyClass();

        enum Priority { High, Low, VeryHigh, VeryLow };
        void setPriority( Priority );
        Priority priority() const;
    };

Another macro similar to "Q_ENUMS" is "Q_SETS". It also registers an enumeration type but marks it in addition as "set", i.e. the single enumeration values can be or'ed together

Other keywords in the "Q_PROPERTY" section are:

Properties of an object can be read and set through QObject::property() and QObject::setProperty(). All properties available for a given object can be queried through the object's meta object. The meta object is accessible through QObject::metaObject(). See QMetaObject::propertyNames(), QMetaObject::property() and QMetaProperty for details.

Connected to the property system is an additional macro, "Q_CLASSINFO", that can be used to attach additional name/value-pairs to a classes' meta object, for example:

Q_CLASSINFO( "Status", "Very nice class")

Like other meta data, class information is accessible at runtime through the meta object, see QMetaObject::classInfo() for details.


Copyright © 2000 Troll TechTrademarks
Qt version 2.1.0