1 /****************************************************************************

     2 **

     3 ** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).

     4 ** All rights reserved.

     5 ** Contact: Nokia Corporation (qt-info@nokia.com)

     6 **

     7 ** This file is part of the documentation of the Qt Toolkit.

     8 **

     9 ** $QT_BEGIN_LICENSE:LGPL$

    10 ** No Commercial Usage

    11 ** This file contains pre-release code and may not be distributed.

    12 ** You may use this file in accordance with the terms and conditions

    13 ** contained in the Technology Preview License Agreement accompanying

    14 ** this package.

    15 **

    16 ** GNU Lesser General Public License Usage

    17 ** Alternatively, this file may be used under the terms of the GNU Lesser

    18 ** General Public License version 2.1 as published by the Free Software

    19 ** Foundation and appearing in the file LICENSE.LGPL included in the

    20 ** packaging of this file.  Please review the following information to

    21 ** ensure the GNU Lesser General Public License version 2.1 requirements

    22 ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.

    23 **

    24 ** In addition, as a special exception, Nokia gives you certain additional

    25 ** rights.  These rights are described in the Nokia Qt LGPL Exception

    26 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.

    27 **

    28 ** If you have questions regarding the use of this file, please contact

    29 ** Nokia at qt-info@nokia.com.

    30 **

    31 **

    32 **

    33 **

    34 **

    35 **

    36 **

    37 **

    38 ** $QT_END_LICENSE$

    39 **

    40 ****************************************************************************/

    41 

    42 /*!

    43     \page properties.html

    44     \title Qt's Property System

    45     \brief An overview of Qt's property system.

    46 

    47     Qt provides a sophisticated property system similar to the ones

    48     supplied by some compiler vendors. However, as a compiler- and

    49     platform-independent library, Qt does not rely on non-standard

    50     compiler features like \c __property or \c [property]. The Qt

    51     solution works with \e any standard C++ compiler on every platform

    52     Qt supports. It is based on the \l {Meta-Object System} that also

    53     provides inter-object communication via \l{signals and slots}.

    54 

    55     \section1 Requirements for Declaring Properties

    56 

    57     To declare a property, use the \l {Q_PROPERTY()} {Q_PROPERTY()}

    58     macro in a class that inherits QObject.

    59 

    60     \snippet doc/src/snippets/code/doc_src_properties.qdoc 0

    61 

    62     Here are some typical examples of property declarations taken from

    63     class QWidget.

    64 

    65     \snippet doc/src/snippets/code/doc_src_properties.qdoc 1

    66 

    67     A property behaves like a class data member, but it has additional

    68     features accessible through the \l {Meta-Object System}.

    69 

    70     \list 

    71 

    72     \o A \c READ accessor function is required. It is for reading the

    73     property value. Ideally, a const function is used for this purpose,

    74     and it must return either the property's type or a pointer or

    75     reference to that type. e.g., QWidget::focus is a read-only property

    76     with \c READ function, QWidget::hasFocus().

    77 

    78     \o A \c WRITE accessor function is optional. It is for setting the

    79     property value. It must return void and must take exactly one

    80     argument, either of the property's type or a pointer or reference

    81     to that type. e.g., QWidget::enabled has the \c WRITE function

    82     QWidget::setEnabled().  Read-only properties do not need \c WRITE

    83     functions. e.g., QWidget::focus has no \c WRITE function.

    84 

    85     \o A \c RESET function is optional. It is for setting the property

    86     back to its context specific default value. e.g., QWidget::cursor

    87     has the typical \c READ and \c WRITE functions, QWidget::cursor()

    88     and QWidget::setCursor(), and it also has a \c RESET function,

    89     QWidget::unsetCursor(), since no call to QWidget::setCursor() can

    90     mean \e {reset to the context specific cursor}. The \c RESET

    91     function must return void and take no parameters.

    92 

    93     \o A \c NOTIFY signal is optional. If defined, the signal will be

    94     emitted whenever the value of the property changes. The signal must

    95     take one parameter, which must be of the same type as the property; the

    96     parameter will take the new value of the property.

    97 

    98     \o The \c DESIGNABLE attribute indicates whether the property

    99     should be visible in the property editor of GUI design tool (e.g.,

   100     \l {Qt Designer}). Most properties are \c DESIGNABLE (default

   101     true). Instead of true or false, you can specify a boolean

   102     member function.

   103 

   104     \o The \c SCRIPTABLE attribute indicates whether this property

   105     should be accessible by a scripting engine (default true).

   106     Instead of true or false, you can specify a boolean member

   107     function.

   108 

   109     \o The \c STORED attribute indicates whether the property should

   110     be thought of as existing on its own or as depending on other

   111     values. It also indicates whether the property value must be saved

   112     when storing the object's state. Most properties are \c STORED

   113     (default true), but e.g., QWidget::minimumWidth() has \c STORED

   114     false, because its value is just taken from the width component

   115     of property QWidget::minimumSize(), which is a QSize.

   116 

   117     \o The \c USER attribute indicates whether the property is

   118     designated as the user-facing or user-editable property for the

   119     class. Normally, there is only one \c USER property per class

   120     (default false). e.g., QAbstractButton::checked is the user

   121     editable property for (checkable) buttons. Note that QItemDelegate

   122     gets and sets a widget's \c USER property.

   123 

   124     \o The presence of the \c CONSTANT attibute indicates that the property 

   125     value is constant.  For a given object instance, the READ method of a 

   126     constant property must return the same value every time it is called.  This

   127     constant value may be different for different instances of the object.  A

   128     constant property cannot have a WRITE method or a NOTIFY signal.

   129 

   130     \o The presence of the \c FINAL attribute indicates that the property

   131     will not be overridden by a derived class.  This can be used for performance

   132     optimizations in some cases, but is not enforced by moc.  Care must be taken

   133     never to override a \c FINAL property.

   134 

   135     \endlist

   136 

   137     The \c READ, \c WRITE, and \c RESET functions can be inherited.

   138     They can also be virtual. When they are inherited in classes where

   139     multiple inheritance is used, they must come from the first

   140     inherited class.

   141 

   142     The property type can be any type supported by QVariant, or it can

   143     be a user-defined type. In this example, class QDate is considered

   144     to be a user-defined type.

   145 

   146     \snippet doc/src/snippets/code/doc_src_properties.qdoc 2

   147 

   148     Because QDate is user-defined, you must include the \c{<QDate>}

   149     header file with the property declaration.

   150 

   151     For QMap, QList, and QValueList properties, the property value is

   152     a QVariant whose value is the entire list or map.  Note that the

   153     Q_PROPERTY string cannot contain commas, because commas separate

   154     macro arguments. Therefore, you must use \c QMap as the property

   155     type instead of \c QMap<QString,QVariant>. For consistency, also

   156     use \c QList and \c QValueList instead of \c QList<QVariant> and

   157     \c QValueList<QVariant>.

   158 

   159     \section1 Reading and Writing Properties with the Meta-Object System

   160 

   161     A property can be read and written using the generic functions

   162     QObject::property() and QObject::setProperty(), without knowing

   163     anything about the owning class except the property's name.  In

   164     the code snippet below, the call to QAbstractButton::setDown() and

   165     the call to QObject::setProperty() both set property "down".

   166 

   167     \snippet doc/src/snippets/code/doc_src_properties.qdoc 3

   168 

   169     Accessing a property through its \c WRITE accessor is the better

   170     of the two, because it is faster and gives better diagnostics at

   171     compile time, but setting the property this way requires that you

   172     know about the class at compile time. Accessing properties by name

   173     lets you access classes you don't know about at compile time. You

   174     can \e discover a class's properties at run time by querying its

   175     QObject, QMetaObject, and \l {QMetaProperty} {QMetaProperties}.

   176 

   177     \snippet doc/src/snippets/code/doc_src_properties.qdoc 4

   178 

   179     In the above snippet, QMetaObject::property() is used to get \l

   180     {QMetaProperty} {metadata} about each property defined in some

   181     unknown class. The property name is fetched from the metadata and

   182     passed to QObject::property() to get the \l {QVariant} {value} of

   183     the property in the current \l {QObject}{object}.

   184 

   185     \section1 A Simple Example

   186 

   187     Suppose we have a class MyClass, which is derived from QObject and

   188     which uses the Q_OBJECT macro in its private section. We want to

   189     declare a property in MyClass to keep track of a priorty

   190     value. The name of the property will be \e priority, and its type

   191     will be an enumeration type named \e Priority, which is defined in

   192     MyClass.

   193 

   194     We declare the property with the Q_PROPERTY() macro in the private

   195     section of the class. The required \c READ function is named \c

   196     priority, and we include a \c WRITE function named \c setPriority.

   197     The enumeration type must be registered with the \l {Meta-Object

   198     System} using the Q_ENUMS() macro. Registering an enumeration type

   199     makes the enumerator names available for use in calls to

   200     QObject::setProperty(). We must also provide our own declarations

   201     for the \c READ and \c WRITE functions. The declaration of MyClass

   202     then might look like this:

   203 

   204     \snippet doc/src/snippets/code/doc_src_properties.qdoc 5

   205 

   206     The \c READ function is const and returns the property type. The

   207     \c WRITE function returns void and has exactly one parameter of

   208     the property type. The meta-object compiler enforces these

   209     requirements.

   210 

   211     Given a pointer to an instance of MyClass or a pointer to an

   212     instance of QObject that happens to be an instance of MyClass, we

   213     have two ways to set its priority property.

   214 

   215     \snippet doc/src/snippets/code/doc_src_properties.qdoc 6

   216 

   217     In the example, the enumeration type used for the property type

   218     was locally declared in MyClass. Had it been declared in another

   219     class, its fully qualified name (i.e., OtherClass::Priority) would

   220     be required.  In addition, that other class must also inherit

   221     QObject and register the enum type using Q_ENUMS().

   222 

   223     A similar macro, Q_FLAGS(), is also available. Like Q_ENUMS(), it

   224     registers an enumeration type, but it marks the type as being a

   225     set of \e flags, i.e. values that can be OR'd together. An I/O

   226     class might have enumeration values \c Read and \c Write and then

   227     QObject::setProperty() could accept \c{Read | Write}. Q_FLAGS()

   228     should be used to register this enumeration type.

   229 

   230     \section1 Dynamic Properties

   231 

   232     QObject::setProperty() can also be used to add \e new properties

   233     to an instance of a class at runtime. When it is called with a

   234     name and a value, if a property with the given name exists in the

   235     QObject, and if the given value is compatible with the property's

   236     type, the value is stored in the property, and true is returned.

   237     If the value is \e not compatible with the property's type, the

   238     property is \e not changed, and false is returned. But if the

   239     property with the given name doesn't exist in the QObject (i.e.,

   240     if it wasn't declared with Q_PROPERTY(), a new property with the

   241     given name and value is automatically added to the QObject, but

   242     false is still returned. This means that a return of false can't

   243     be used to determine whether a particular property was actually

   244     set, unless you know in advance that the property already exists

   245     in the QObject.

   246 

   247     Note that \e dynamic properties are added on a per instance basis,

   248     i.e., they are added to QObject, not QMetaObject. A property can

   249     be removed from an instance by passing the property name and an

   250     invalid QVariant value to QObject::setProperty(). The default

   251     constructor for QVariant constructs an invalid QVariant.

   252 

   253     Dynamic properties can be queried with QObject::property(), just

   254     like properties declared at compile time with Q_PROPERTY().

   255 

   256     \sa {Meta-Object System}, {Signals and Slots}

   257 

   258     \section1 Properties and Custom Types

   259 

   260     Custom types used by properties need to be registered using the

   261     Q_DECLARE_METATYPE() macro so that their values can be stored in

   262     QVariant objects. This makes them suitable for use with both

   263     static properties declared using the Q_PROPERTY() macro in class

   264     definitions and dynamic properties created at run-time. 

   265 

   266     \sa Q_DECLARE_METATYPE(), QMetaType, QVariant

   267 

   268     \section1 Adding Additional Information to a Class

   269 

   270     Connected to the property system is an additional macro,

   271     Q_CLASSINFO(), that can be used to attach additional

   272     \e{name}--\e{value} pairs to a class's meta-object, for example:

   273 

   274     \snippet doc/src/snippets/code/doc_src_properties.qdoc 7

   275 

   276     Like other meta-data, class information is accessible at run-time

   277     through the meta-object; see QMetaObject::classInfo() for details.

   278 */