Initial import from the monolithic Qt.

This is the beginning of revision history for this module. If you
want to look at revision history older than this, please refer to the
Qt Git wiki for how to use Git history grafting. At the time of
writing, this wiki is located here:

http://qt.gitorious.org/qt/pages/GitIntroductionWithQt

If you have already performed the grafting and you don't see any
history beyond this commit, try running "git log" with the "--follow"
argument.

Branched from the monolithic repo, Qt master branch, at commit
896db169ea224deb96c59ce8af800d019de63f12

1 files changed, 273 insertions, 0 deletions

diff --git a/doc/src/objectmodel/properties.qdoc b/doc/src/objectmodel/properties.qdoc
new file mode 100644
index 0000000000..92c182e0b9
--- /dev/null
+++ b/doc/src/objectmodel/properties.qdoc
@@ -0,0 +1,273 @@
+/****************************************************************************
+**
+** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
+** All rights reserved.
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** No Commercial Usage
+** This file contains pre-release code and may not be distributed.
+** You may use this file in accordance with the terms and conditions
+** contained in the Technology Preview License Agreement accompanying
+** this package.
+**
+** GNU Free Documentation License
+** Alternatively, this file may be used under the terms of the GNU Free
+** Documentation License version 1.3 as published by the Free Software
+** Foundation and appearing in the file included in the packaging of this
+** file.
+**
+** If you have questions regarding the use of this file, please contact
+** Nokia at qt-info@nokia.com.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+    \page properties.html
+    \title The Property System
+    \brief An overview of Qt's property system.
+
+    \ingroup qt-basic-concepts
+    \target Qt's Property System
+
+    Qt provides a sophisticated property system similar to the ones
+    supplied by some compiler vendors. However, as a compiler- and
+    platform-independent library, Qt does not rely on non-standard
+    compiler features like \c __property or \c [property]. The Qt
+    solution works with \e any standard C++ compiler on every platform
+    Qt supports. It is based on the \l {Meta-Object System} that also
+    provides inter-object communication via \l{signals and slots}.
+
+    \section1 Requirements for Declaring Properties
+
+    To declare a property, use the \l {Q_PROPERTY()} {Q_PROPERTY()}
+    macro in a class that inherits QObject.
+
+    \snippet doc/src/snippets/code/doc_src_properties.cpp 0
+
+    Here are some typical examples of property declarations taken from
+    class QWidget.
+
+    \snippet doc/src/snippets/code/doc_src_properties.cpp 1
+
+    A property behaves like a class data member, but it has additional
+    features accessible through the \l {Meta-Object System}.
+
+    \list 
+
+    \o A \c READ accessor function is required. It is for reading the
+    property value. Ideally, a const function is used for this purpose,
+    and it must return either the property's type or a pointer or
+    reference to that type. e.g., QWidget::focus is a read-only property
+    with \c READ function, QWidget::hasFocus().
+
+    \o A \c WRITE accessor function is optional. It is for setting the
+    property value. It must return void and must take exactly one
+    argument, either of the property's type or a pointer or reference
+    to that type. e.g., QWidget::enabled has the \c WRITE function
+    QWidget::setEnabled().  Read-only properties do not need \c WRITE
+    functions. e.g., QWidget::focus has no \c WRITE function.
+
+    \o A \c RESET function is optional. It is for setting the property
+    back to its context specific default value. e.g., QWidget::cursor
+    has the typical \c READ and \c WRITE functions, QWidget::cursor()
+    and QWidget::setCursor(), and it also has a \c RESET function,
+    QWidget::unsetCursor(), since no call to QWidget::setCursor() can
+    mean \e {reset to the context specific cursor}. The \c RESET
+    function must return void and take no parameters.
+
+    \o A \c NOTIFY signal is optional. If defined, it should specify one
+    existing signal in that class that is emitted whenever the value
+    of the property changes.
+
+    \o A \c REVISION number is optional. If included, it defines the
+    the property and its notifier signal to be used in a particular
+    revision of the API that is exposed to QML.
+
+    \o The \c DESIGNABLE attribute indicates whether the property
+    should be visible in the property editor of GUI design tool (e.g.,
+    \l {Qt Designer}). Most properties are \c DESIGNABLE (default
+    true). Instead of true or false, you can specify a boolean
+    member function.
+
+    \o The \c SCRIPTABLE attribute indicates whether this property
+    should be accessible by a scripting engine (default true).
+    Instead of true or false, you can specify a boolean member
+    function.
+
+    \o The \c STORED attribute indicates whether the property should
+    be thought of as existing on its own or as depending on other
+    values. It also indicates whether the property value must be saved
+    when storing the object's state. Most properties are \c STORED
+    (default true), but e.g., QWidget::minimumWidth() has \c STORED
+    false, because its value is just taken from the width component
+    of property QWidget::minimumSize(), which is a QSize.
+
+    \o The \c USER attribute indicates whether the property is
+    designated as the user-facing or user-editable property for the
+    class. Normally, there is only one \c USER property per class
+    (default false). e.g., QAbstractButton::checked is the user
+    editable property for (checkable) buttons. Note that QItemDelegate
+    gets and sets a widget's \c USER property.
+
+    \o The presence of the \c CONSTANT attibute indicates that the property 
+    value is constant.  For a given object instance, the READ method of a 
+    constant property must return the same value every time it is called.  This
+    constant value may be different for different instances of the object.  A
+    constant property cannot have a WRITE method or a NOTIFY signal.
+
+    \o The presence of the \c FINAL attribute indicates that the property
+    will not be overridden by a derived class.  This can be used for performance
+    optimizations in some cases, but is not enforced by moc.  Care must be taken
+    never to override a \c FINAL property.
+
+    \endlist
+
+    The \c READ, \c WRITE, and \c RESET functions can be inherited.
+    They can also be virtual. When they are inherited in classes where
+    multiple inheritance is used, they must come from the first
+    inherited class.
+
+    The property type can be any type supported by QVariant, or it can
+    be a user-defined type. In this example, class QDate is considered
+    to be a user-defined type.
+
+    \snippet doc/src/snippets/code/doc_src_properties.cpp 2
+
+    Because QDate is user-defined, you must include the \c{<QDate>}
+    header file with the property declaration.
+
+    For QMap, QList, and QValueList properties, the property value is
+    a QVariant whose value is the entire list or map.  Note that the
+    Q_PROPERTY string cannot contain commas, because commas separate
+    macro arguments. Therefore, you must use \c QMap as the property
+    type instead of \c QMap<QString,QVariant>. For consistency, also
+    use \c QList and \c QValueList instead of \c QList<QVariant> and
+    \c QValueList<QVariant>.
+
+    \section1 Reading and Writing Properties with the Meta-Object System
+
+    A property can be read and written using the generic functions
+    QObject::property() and QObject::setProperty(), without knowing
+    anything about the owning class except the property's name.  In
+    the code snippet below, the call to QAbstractButton::setDown() and
+    the call to QObject::setProperty() both set property "down".
+
+    \snippet doc/src/snippets/code/doc_src_properties.cpp 3
+
+    Accessing a property through its \c WRITE accessor is the better
+    of the two, because it is faster and gives better diagnostics at
+    compile time, but setting the property this way requires that you
+    know about the class at compile time. Accessing properties by name
+    lets you access classes you don't know about at compile time. You
+    can \e discover a class's properties at run time by querying its
+    QObject, QMetaObject, and \l {QMetaProperty} {QMetaProperties}.
+
+    \snippet doc/src/snippets/code/doc_src_properties.cpp 4
+
+    In the above snippet, QMetaObject::property() is used to get \l
+    {QMetaProperty} {metadata} about each property defined in some
+    unknown class. The property name is fetched from the metadata and
+    passed to QObject::property() to get the \l {QVariant} {value} of
+    the property in the current \l {QObject}{object}.
+
+    \section1 A Simple Example
+
+    Suppose we have a class MyClass, which is derived from QObject and
+    which uses the Q_OBJECT macro in its private section. We want to
+    declare a property in MyClass to keep track of a priorty
+    value. The name of the property will be \e priority, and its type
+    will be an enumeration type named \e Priority, which is defined in
+    MyClass.
+
+    We declare the property with the Q_PROPERTY() macro in the private
+    section of the class. The required \c READ function is named \c
+    priority, and we include a \c WRITE function named \c setPriority.
+    The enumeration type must be registered with the \l {Meta-Object
+    System} using the Q_ENUMS() macro. Registering an enumeration type
+    makes the enumerator names available for use in calls to
+    QObject::setProperty(). We must also provide our own declarations
+    for the \c READ and \c WRITE functions. The declaration of MyClass
+    then might look like this:
+
+    \snippet doc/src/snippets/code/doc_src_properties.cpp 5
+
+    The \c READ function is const and returns the property type. The
+    \c WRITE function returns void and has exactly one parameter of
+    the property type. The meta-object compiler enforces these
+    requirements.
+
+    Given a pointer to an instance of MyClass or a pointer to a
+    QObject that is an instance of MyClass, we have two ways to set
+    its priority property:
+
+    \snippet doc/src/snippets/code/doc_src_properties.cpp 6
+
+    In the example, the enumeration type that is the property type is
+    declared in MyClass and registered with the \l{Meta-Object System}
+    using the Q_ENUMS() macro. This makes the enumeration values
+    available as strings for use as in the call to setProperty(). Had
+    the enumeration type been declared in another class, its fully
+    qualified name (i.e., OtherClass::Priority) would be required, and
+    that other class would also have to inherit QObject and register
+    the enumeration type there using the Q_ENUMS() macro.
+
+    A similar macro, Q_FLAGS(), is also available. Like Q_ENUMS(), it
+    registers an enumeration type, but it marks the type as being a
+    set of \e flags, i.e. values that can be OR'd together. An I/O
+    class might have enumeration values \c Read and \c Write and then
+    QObject::setProperty() could accept \c{Read | Write}. Q_FLAGS()
+    should be used to register this enumeration type.
+
+    \section1 Dynamic Properties
+
+    QObject::setProperty() can also be used to add \e new properties
+    to an instance of a class at runtime. When it is called with a
+    name and a value, if a property with the given name exists in the
+    QObject, and if the given value is compatible with the property's
+    type, the value is stored in the property, and true is returned.
+    If the value is \e not compatible with the property's type, the
+    property is \e not changed, and false is returned. But if the
+    property with the given name doesn't exist in the QObject (i.e.,
+    if it wasn't declared with Q_PROPERTY(), a new property with the
+    given name and value is automatically added to the QObject, but
+    false is still returned. This means that a return of false can't
+    be used to determine whether a particular property was actually
+    set, unless you know in advance that the property already exists
+    in the QObject.
+
+    Note that \e dynamic properties are added on a per instance basis,
+    i.e., they are added to QObject, not QMetaObject. A property can
+    be removed from an instance by passing the property name and an
+    invalid QVariant value to QObject::setProperty(). The default
+    constructor for QVariant constructs an invalid QVariant.
+
+    Dynamic properties can be queried with QObject::property(), just
+    like properties declared at compile time with Q_PROPERTY().
+
+    \sa {Meta-Object System}, {Signals and Slots}
+
+    \section1 Properties and Custom Types
+
+    Custom types used by properties need to be registered using the
+    Q_DECLARE_METATYPE() macro so that their values can be stored in
+    QVariant objects. This makes them suitable for use with both
+    static properties declared using the Q_PROPERTY() macro in class
+    definitions and dynamic properties created at run-time. 
+
+    \sa Q_DECLARE_METATYPE(), QMetaType, QVariant
+
+    \section1 Adding Additional Information to a Class
+
+    Connected to the property system is an additional macro,
+    Q_CLASSINFO(), that can be used to attach additional
+    \e{name}--\e{value} pairs to a class's meta-object, for example:
+
+    \snippet doc/src/snippets/code/doc_src_properties.cpp 7
+
+    Like other meta-data, class information is accessible at run-time
+    through the meta-object; see QMetaObject::classInfo() for details.
+*/