Viadeo Twitter Google Bookmarks ! Facebook Digg del.icio.us MySpace Yahoo MyWeb Blinklist Netvouz Reddit Simpy StumbleUpon Bookmarks Windows Live Favorites 
Logo Documentation Qt ·  Page d'accueil  ·  Toutes les classes  ·  Classes principales  ·  Annotées  ·  Classes groupées  ·  Fonctions  · 

Properties

Qt provides a sophisticated property system similar to those supplied by some compiler vendors. However, as a compiler- and platform-independent 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 some aspects of an inherited property in a subclass. (See Q_OVERRIDE.)

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

  • A read function. This always exists.

  • A write function. This is optional: read-only properties like QWidget::isDesktop() do not have one.

  • An attribute "stored" that indicates persistence. Most properties are stored, but a few virtual properties are not. For example, QWidget::minimumWidth() isn't stored, since it's just a view of QWidget::minimumSize(), and has no data of its own.

  • A reset function to set a property back to its context specific default value. This is very rare, but for example, QWidget::font() needs this, since no call to QWidget::setFont() can mean 'reset to the context specific font'.

  • An attribute "designable" that indicates whether it makes sense to make the property available in a GUI builder (e.g. Qt Designer). For most properties this makes sense, but not for all, e.g. QButton::isDown(). The user can press buttons, and the application programmer can make the program press its own buttons, but a GUI design tool can't press buttons.

The read, write and reset functions can be just about any member functions, inherited or not, virtual or not. The only exception is that member functions must be inherited from the first inherited class in the case of multiple inheritance.

Properties can be read and written through generic functions in QObject without knowing anything about the class in use. These two function calls are equivalent:

    // QButton *b and QObject *o point to the same button
    b->setDown( TRUE );
    o->setProperty( "down", TRUE );

Equivalent, that is, except that the first is faster, and provides much better diagnostics at compile time. When practical, the first is better. However, since you can get a list of all available properties for any QObject through its QMetaObject, QObject::setProperty() can give you control over classes that weren't available at compile time.

As well as QObject::setProperty(), there is a corresponding QObject::property() function. QMetaObject::propertyNames() returns the names of all available properties. QMetaObject::property() returns the property data for a named property: a QMetaProperty object.

Here's a simple example that shows the most important property functions in use:

    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 must declare it with the Q_PROPERTY macro. The syntax is as follows:

Q_PROPERTY( type name READ getFunction [WRITE setFunction]
            [RESET resetFunction] [DESIGNABLE bool] 
            [SCRIPTABLE bool] [STORED bool] )

For the declaration to be valid, the get function must be const and to return either the type itself, a pointer to it, or a reference to it. The optional write function must return void and must take exactly one argument, either the type itself, a pointer or a const reference to it. The meta object compiler enforces this.

The type of a property can be any QVariant supported type or an enumeration type declared in the class itself. Since MyClass uses the enumeration type Priority for the property, this type must be registered with the property system as well.

There are two exceptions to the above: The type of a property can also be either QValueList<QVariant> or QMap<QString,QVariant>. In these cases the type must be specified as QValueList or as QMap (i.e. without their template parameters).

It is possible to set a value by name, like this:

    obj->setProperty( "priority", "VeryHigh" );
In the case of QValueList and QMap properties the value passes is a QVariant whose value is the entire list or map.

Enumeration types are registered with the Q_ENUMS macro. Here's the final class declaration including the property related declarations:

    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 similar macro is Q_SETS. Like Q_ENUMS, it registers an enumeration type but marks it in addition as a "set", i.e. the enumeration values can be OR-ed together. An I/O class might have enumeration values "Read" and "Write" and accept "Read|Write": such an enum is best handled with Q_SETS, rather than Q_ENUMS.

The remaining keywords in the Q_PROPERTY section are RESET, DESIGNABLE, SCRIPTABLE and STORED.

RESET names a function that will set the property to its default state (which may have changed since initialization). The function must return void and take no arguments.

DESIGNABLE declares whether this property is suitable for modification by a GUI design tool. The default is TRUE for writable properties; otherwise FALSE. Instead of TRUE or FALSE, you can specify a boolean member function.

SCRIPTABLE declares whether this property is suited for access by a scripting engine. The default is TRUE. Instead of TRUE or FALSE, you can specify a boolean member function.

STORED declares whether the property's value must be remembered when storing an object's state. Stored makes only sense for writable properties. The default value is TRUE. Technically superfluous properties (like QPoint pos if QRect geometry is already a property) define this to be FALSE.

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

    Q_CLASSINFO( "Version", "3.0.0" )

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

Q_OVERRIDE

When you inherit a QObject subclass you may wish to override some aspects of some of the class's properties.

For example, in QWidget we have the autoMask property defined like this:

    Q_PROPERTY( bool autoMask READ autoMask WRITE setAutoMask DESIGNABLE false SCRIPTABLE false )

But we need to make the auto mask property designable in some QWidget subclasses. Similarly some classes will need this property to be scriptable (e.g. for QSA). This is achieved by overriding these features of the property in a subclass. In QCheckBox, for example, we achieve this using the following code:

    Q_OVERRIDE( bool autoMask DESIGNABLE true SCRIPTABLE true )

Another example is QToolButton. By default QToolButton has a read-only "toggleButton" property, because that's what it inherits from QButton:

    Q_PROPERTY( bool toggleButton READ isToggleButton )

But we want to make our tool buttons able to be toggled, so we write a WRITE function in QToolButton, and use the following property override to make it acessible:

    Q_OVERRIDE( bool toggleButton WRITE setToggleButton )
The result is read-write (and scriptable and designable, since we now have a WRITE function) boolean property "toggleButton" for tool buttons.

Publicité

Best Of

Actualités les plus lues

Semaine
Mois
Année
  1. « Quelque chose ne va vraiment pas avec les développeurs "modernes" », un développeur à "l'ancienne" critique la multiplication des bibliothèques 64
  2. Apercevoir la troisième dimension ou l'utilisation multithreadée d'OpenGL dans Qt, un article des Qt Quarterly traduit par Guillaume Belz 0
  3. Les développeurs ignorent-ils trop les failles découvertes dans leur code ? Prenez-vous en compte les remarques des autres ? 17
  4. BlackBerry 10 : premières images du prochain OS de RIM qui devrait intégrer des widgets et des tuiles inspirées de Windows Phone 0
  5. Quelles nouveautés de C++11 Visual C++ doit-il rapidement intégrer ? Donnez-nous votre avis 10
  6. Adieu qmake, bienvenue qbs : Qt Building Suite, un outil déclaratif et extensible pour la compilation de projets Qt 17
  7. La rubrique Qt a besoin de vous ! 1
Page suivante

Le Qt Quarterly au hasard

Logo

Réordonner les boutons

Qt Quarterly est la revue trimestrielle proposée par Nokia et à destination des développeurs Qt. Ces articles d'une grande qualité technique sont rédigés par des experts Qt. Lire l'article.

Communauté

Ressources

Liens utiles

Contact

  • Vous souhaitez rejoindre la rédaction ou proposer un tutoriel, une traduction, une question... ? Postez dans le forum Contribuez ou contactez-nous par MP ou par email (voir en bas de page).

Qt dans le magazine

Cette page est une traduction d'une page de la documentation de Qt, écrite par Nokia Corporation and/or its subsidiary(-ies). Les éventuels problèmes résultant d'une mauvaise traduction ne sont pas imputables à Nokia. Qt 3.2
Copyright © 2012 Developpez LLC. Tous droits réservés Developpez LLC. Aucune reproduction, même partielle, ne peut être faite de ce site et de l'ensemble de son contenu : textes, documents et images sans l'autorisation expresse de Developpez LLC. Sinon, vous encourez selon la loi jusqu'à 3 ans de prison et jusqu'à 300 000 E de dommages et intérêts. Cette page est déposée à la SACD.
Vous avez déniché une erreur ? Un bug ? Une redirection cassée ? Ou tout autre problème, quel qu'il soit ? Ou bien vous désirez participer à ce projet de traduction ? N'hésitez pas à nous contacter ou par MP !
 
 
 
 
Partenaires

Hébergement Web