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

5 files changed, 1087 insertions, 0 deletions

diff --git a/doc/src/objectmodel/metaobjects.qdoc b/doc/src/objectmodel/metaobjects.qdoc
new file mode 100644
index 0000000000..099a6a9942
--- /dev/null
+++ b/doc/src/objectmodel/metaobjects.qdoc
@@ -0,0 +1,137 @@
+/****************************************************************************
+**
+** 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 metaobjects.html
+    \title The Meta-Object System
+    \brief An overview of Qt's meta-object system and introspection capabilities.
+
+    \ingroup qt-basic-concepts
+    \keyword meta-object
+    \target Meta-Object System
+
+    Qt's meta-object system provides the signals and slots mechanism for
+    inter-object communication, run-time type information, and the dynamic
+    property system.
+
+    The meta-object system is based on three things:
+
+    \list 1
+    \o The \l QObject class provides a base class for objects that can
+       take advantage of the meta-object system.
+    \o The Q_OBJECT macro inside the private section of the class
+       declaration is used to enable meta-object features, such as
+       dynamic properties, signals, and slots.
+    \o The \l{moc}{Meta-Object Compiler} (\c moc) supplies each
+       QObject subclass with the necessary code to implement
+       meta-object features.
+    \endlist
+
+    The \c moc tool reads a C++ source file. If it finds one or more
+    class declarations that contain the Q_OBJECT macro, it
+    produces another C++ source file which contains the meta-object
+    code for each of those classes. This generated source file is
+    either \c{#include}'d into the class's source file or, more
+    usually, compiled and linked with the class's implementation.
+
+    In addition to providing the \l{signals and slots} mechanism for
+    communication between objects (the main reason for introducing
+    the system), the meta-object code provides the following
+    additional features:
+
+    \list
+    \o QObject::metaObject() returns the associated
+       \l{QMetaObject}{meta-object} for the class.
+    \o QMetaObject::className() returns the class name as a
+       string at run-time, without requiring native run-time type information
+       (RTTI) support through the C++ compiler.
+    \o QObject::inherits() function returns whether an object is an
+       instance of a class that inherits a specified class within the
+       QObject inheritance tree.
+    \o QObject::tr() and QObject::trUtf8() translate strings for
+       \l{Internationalization with Qt}{internationalization}.
+    \o QObject::setProperty() and QObject::property()
+       dynamically set and get properties by name.
+    \o QMetaObject::newInstance() constructs a new instance of the class.
+    \endlist
+
+    \target qobjectcast
+    It is also possible to perform dynamic casts using qobject_cast()
+    on QObject classes. The qobject_cast() function behaves similarly
+    to the standard C++ \c dynamic_cast(), with the advantages
+    that it doesn't require RTTI support and it works across dynamic
+    library boundaries. It attempts to cast its argument to the pointer
+    type specified in angle-brackets, returning a non-zero pointer if the
+    object is of the correct type (determined at run-time), or 0
+    if the object's type is incompatible.
+
+    For example, let's assume \c MyWidget inherits from QWidget and
+    is declared with the Q_OBJECT macro:
+
+    \snippet doc/src/snippets/qtcast/qtcast.cpp 0
+
+    The \c obj variable, of type \c{QObject *}, actually refers to a
+    \c MyWidget object, so we can cast it appropriately:
+
+    \snippet doc/src/snippets/qtcast/qtcast.cpp 1
+
+    The cast from QObject to QWidget is successful, because the
+    object is actually a \c MyWidget, which is a subclass of QWidget.
+    Since we know that \c obj is a \c MyWidget, we can also cast it to
+    \c{MyWidget *}:
+
+    \snippet doc/src/snippets/qtcast/qtcast.cpp 2
+
+    The cast to \c MyWidget is successful because qobject_cast()
+    makes no distinction between built-in Qt types and custom types.
+
+    \snippet doc/src/snippets/qtcast/qtcast.cpp 3
+    \snippet doc/src/snippets/qtcast/qtcast.cpp 4
+
+    The cast to QLabel, on the other hand, fails. The pointer is then
+    set to 0. This makes it possible to handle objects of different
+    types differently at run-time, based on the type:
+
+    \snippet doc/src/snippets/qtcast/qtcast.cpp 5
+    \snippet doc/src/snippets/qtcast/qtcast.cpp 6
+
+    While it is possible to use QObject as a base class without the
+    Q_OBJECT macro and without meta-object code, neither signals
+    and slots nor the other features described here will be available
+    if the Q_OBJECT macro is not used. From the meta-object
+    system's point of view, a QObject subclass without meta code is
+    equivalent to its closest ancestor with meta-object code. This
+    means for example, that QMetaObject::className() will not return
+    the actual name of your class, but the class name of this
+    ancestor.
+
+    Therefore, we strongly recommend that all subclasses of QObject
+    use the Q_OBJECT macro regardless of whether or not they
+    actually use signals, slots, and properties.
+
+    \sa QMetaObject, {Qt's Property System}, {Signals and Slots}
+*/
diff --git a/doc/src/objectmodel/object.qdoc b/doc/src/objectmodel/object.qdoc
new file mode 100644
index 0000000000..2112b10aa4
--- /dev/null
+++ b/doc/src/objectmodel/object.qdoc
@@ -0,0 +1,124 @@
+/****************************************************************************
+**
+** 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 object.html
+    \title Object Model
+    \ingroup qt-basic-concepts
+    \brief A description of the powerful features made possible by Qt's dynamic object model.
+
+    The standard C++ object model provides very efficient runtime
+    support for the object paradigm. But its static nature is
+    inflexibile in certain problem domains. Graphical user interface
+    programming is a domain that requires both runtime efficiency and
+    a high level of flexibility. Qt provides this, by combining the
+    speed of C++ with the flexibility of the Qt Object Model.
+
+    Qt adds these features to C++:
+
+    \list
+    \o a very powerful mechanism for seamless object
+       communication called \l{signals and slots}
+    \o queryable and designable \l{Qt's Property System}{object
+       properties}
+    \o powerful \l{The Event System}{events and event filters}
+    \o contextual \l{i18n}{string translation for internationalization}
+    \o sophisticated interval driven \l timers that make it possible
+       to elegantly integrate many tasks in an event-driven GUI
+    \o hierarchical and queryable \l{Object Trees & Ownership}{object
+       trees} that organize object ownership in a natural way
+    \o guarded pointers (QPointer) that are automatically
+       set to 0 when the referenced object is destroyed, unlike normal C++
+       pointers which become dangling pointers when their objects are destroyed
+    \o a \l{metaobjects.html#qobjectcast}{dynamic cast} that works across
+       library boundaries.
+    \endlist
+
+    Many of these Qt features are implemented with standard C++
+    techniques, based on inheritance from QObject. Others, like the
+    object communication mechanism and the dynamic property system,
+    require the \l{Meta-Object System} provided
+    by Qt's own \l{moc}{Meta-Object Compiler (moc)}.
+
+    The meta-object system is a C++ extension that makes the language
+    better suited to true component GUI programming. Although
+    templates can be used to extend C++, the meta-object system
+    provides benefits using standard C++ that cannot be achieved with
+    templates; see \l{Why Doesn't Qt Use Templates for Signals and
+    Slots?}
+
+    \section1 Important Classes
+
+    These classes form the basis of the Qt Object Model.
+    
+    \annotatedlist objectmodel
+
+    \target Identity vs Value
+    \section1 Qt Objects: Identity vs Value
+
+    Some of the added features listed above for the Qt Object Model,
+    require that we think of Qt Objects as identities, not values.
+    Values are copied or assigned; identities are cloned. Cloning
+    means to create a new identity, not an exact copy of the old
+    one. For example, twins have different identities. They may look
+    identical, but they have different names, different locations, and
+    may have completely different social networks.
+
+    Then cloning an identity is a more complex operation than copying
+    or assigning a value. We can see what this means in the Qt Object
+    Model.
+
+    \bold{A Qt Object...}
+
+    \list
+
+    \o might have a unique \l{QObject::objectName()}.  If we copy a Qt
+    Object, what name should we give the copy?
+
+    \o has a location in an \l{Object Trees & Ownership}
+    {object hierarchy}. If we copy a Qt Object, where should the copy
+    be located?
+
+    \o can be connected to other Qt Objects to emit signals to them or
+    to receive signals emitted by them. If we copy a Qt Object, how
+    should we transfer these connections to the copy?
+
+    \o can have \l{Qt's Property System} {new properties} added to it
+    at runtime that are not declared in the C++ class. If we copy a Qt
+    Object, should the copy include the properties that were added to
+    the original?
+    
+    \endlist
+
+    For these reasons, Qt Objects should be treated as identities, not
+    as values. Identities are cloned, not copied or assigned, and
+    cloning an identity is a more complex operation than copying or
+    assigning a value. Therefore, QObject and all subclasses of
+    QObject (direct or indirect) have their \l{No copy constructor}
+    {copy constructor and assignment operator} disabled.
+
+  */
diff --git a/doc/src/objectmodel/objecttrees.qdoc b/doc/src/objectmodel/objecttrees.qdoc
new file mode 100644
index 0000000000..cb63c17ab1
--- /dev/null
+++ b/doc/src/objectmodel/objecttrees.qdoc
@@ -0,0 +1,102 @@
+/****************************************************************************
+**
+** 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 objecttrees.html
+    \title Object Trees & Ownership
+    \ingroup qt-basic-concepts
+    \brief Information about the parent-child pattern used to describe
+    object ownership in Qt.
+
+    \section1 Overview
+
+    \link QObject QObjects\endlink organize themselves in object trees.
+    When you create a QObject with another object as parent, it's added to
+    the parent's \link QObject::children() children() \endlink list, and
+    is deleted when the parent is. It turns out that this approach fits
+    the needs of GUI objects very well. For example, a \l QShortcut
+    (keyboard shortcut) is a child of the relevant window, so when the
+    user closes that window, the shorcut is deleted too.
+
+    \l QWidget, the base class of everything that appears on the screen,
+    extends the parent-child relationship. A child normally also becomes a
+    child widget, i.e. it is displayed in its parent's coordinate system
+    and is graphically clipped by its parent's boundaries. For example,
+    when the application deletes a message box after it has been
+    closed, the message box's buttons and label are also deleted, just as
+    we'd want, because the buttons and label are children of the message
+    box.
+
+    You can also delete child objects yourself, and they will remove
+    themselves from their parents. For example, when the user removes a
+    toolbar it may lead to the application deleting one of its \l QToolBar
+    objects, in which case the tool bar's \l QMainWindow parent would
+    detect the change and reconfigure its screen space accordingly.
+
+    The debugging functions \l QObject::dumpObjectTree() and \l
+    QObject::dumpObjectInfo() are often useful when an application looks or
+    acts strangely.
+
+    \target note on the order of construction/destruction of QObjects
+    \section1 Construction/Destruction Order of QObjects
+
+    When \l {QObject} {QObjects} are created on the heap (i.e., created
+    with \e new), a tree can be constructed from them in any order, and
+    later, the objects in the tree can be destroyed in any order. When any
+    QObject in the tree is deleted, if the object has a parent, the
+    destructor automatically removes the object from its parent. If the
+    object has children, the destructor automatically deletes each
+    child. No QObject is deleted twice, regardless of the order of
+    destruction.
+
+    When \l {QObject} {QObjects} are created on the stack, the same
+    behavior applies. Normally, the order of destruction still doesn't
+    present a problem. Consider the following snippet:
+
+    \snippet doc/src/snippets/code/doc_src_objecttrees.cpp 0
+
+    The parent, \c window, and the child, \c quit, are both \l {QObject}
+    {QObjects} because QPushButton inherits QWidget, and QWidget inherits
+    QObject. This code is correct: the destructor of \c quit is \e not
+    called twice because the C++ language standard \e {(ISO/IEC 14882:2003)}
+    specifies that destructors of local objects are called in the reverse
+    order of their constructors. Therefore, the destructor of
+    the child, \c quit, is called first, and it removes itself from its
+    parent, \c window, before the destructor of \c window is called.
+
+    But now consider what happens if we swap the order of construction, as
+    shown in this second snippet:
+
+    \snippet doc/src/snippets/code/doc_src_objecttrees.cpp 1
+
+    In this case, the order of destruction causes a problem. The parent's
+    destructor is called first because it was created last. It then calls
+    the destructor of its child, \c quit, which is incorrect because \c
+    quit is a local variable. When \c quit subsequently goes out of scope,
+    its destructor is called again, this time correctly, but the damage has
+    already been done.
+*/
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.
+*/
diff --git a/doc/src/objectmodel/signalsandslots.qdoc b/doc/src/objectmodel/signalsandslots.qdoc
new file mode 100644
index 0000000000..8b52df5b1a
--- /dev/null
+++ b/doc/src/objectmodel/signalsandslots.qdoc
@@ -0,0 +1,451 @@
+/****************************************************************************
+**
+** 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 signalsandslots.html
+    \title Signals & Slots
+    \ingroup qt-basic-concepts
+    \brief An overview of Qt's signals and slots inter-object
+    communication mechanism.
+
+    Signals and slots are used for communication between objects. The
+    signals and slots mechanism is a central feature of Qt and
+    probably the part that differs most from the features provided by
+    other frameworks.
+
+    \tableofcontents
+
+    \section1 Introduction
+
+    In GUI programming, when we change one widget, we often want
+    another widget to be notified. More generally, we want objects of
+    any kind to be able to communicate with one another. For example,
+    if a user clicks a \gui{Close} button, we probably want the
+    window's \l{QWidget::close()}{close()} function to be called.
+
+    Older toolkits achieve this kind of communication using
+    callbacks. A callback is a pointer to a function, so if you want
+    a processing function to notify you about some event you pass a
+    pointer to another function (the callback) to the processing
+    function. The processing function then calls the callback when
+    appropriate. Callbacks have two fundamental flaws: Firstly, they
+    are not type-safe. We can never be certain that the processing
+    function will call the callback with the correct arguments.
+    Secondly, the callback is strongly coupled to the processing
+    function since the processing function must know which callback
+    to call.
+
+    \section1 Signals and Slots
+
+    In Qt, we have an alternative to the callback technique: We use
+    signals and slots. A signal is emitted when a particular event
+    occurs. Qt's widgets have many predefined signals, but we can
+    always subclass widgets to add our own signals to them. A slot
+    is a function that is called in response to a particular signal.
+    Qt's widgets have many pre-defined slots, but it is common
+    practice to subclass widgets and add your own slots so that you
+    can handle the signals that you are interested in.
+
+    \img abstract-connections.png
+    \omit
+    \caption An abstract view of some signals and slots connections
+    \endomit
+
+    The signals and slots mechanism is type safe: The signature of a
+    signal must match the signature of the receiving slot. (In fact a
+    slot may have a shorter signature than the signal it receives
+    because it can ignore extra arguments.) Since the signatures are
+    compatible, the compiler can help us detect type mismatches.
+    Signals and slots are loosely coupled: A class which emits a
+    signal neither knows nor cares which slots receive the signal.
+    Qt's signals and slots mechanism ensures that if you connect a
+    signal to a slot, the slot will be called with the signal's
+    parameters at the right time. Signals and slots can take any
+    number of arguments of any type. They are completely type safe.
+
+    All classes that inherit from QObject or one of its subclasses
+    (e.g., QWidget) can contain signals and slots. Signals are emitted by
+    objects when they change their state in a way that may be interesting
+    to other objects. This is all the object does to communicate. It
+    does not know or care whether anything is receiving the signals it
+    emits. This is true information encapsulation, and ensures that the
+    object can be used as a software component.
+
+    Slots can be used for receiving signals, but they are also normal
+    member functions. Just as an object does not know if anything receives
+    its signals, a slot does not know if it has any signals connected to
+    it. This ensures that truly independent components can be created with
+    Qt.
+
+    You can connect as many signals as you want to a single slot, and a
+    signal can be connected to as many slots as you need. It is even
+    possible to connect a signal directly to another signal. (This will
+    emit the second signal immediately whenever the first is emitted.)
+
+    Together, signals and slots make up a powerful component programming
+    mechanism.
+
+    \section1 A Small Example
+
+    A minimal C++ class declaration might read:
+
+    \snippet doc/src/snippets/signalsandslots/signalsandslots.h 0
+
+    A small QObject-based class might read:
+
+    \snippet doc/src/snippets/signalsandslots/signalsandslots.h 1
+    \codeline
+    \snippet doc/src/snippets/signalsandslots/signalsandslots.h 2
+    \snippet doc/src/snippets/signalsandslots/signalsandslots.h 3
+
+    The QObject-based version has the same internal state, and provides
+    public methods to access the state, but in addition it has support
+    for component programming using signals and slots. This class can
+    tell the outside world that its state has changed by emitting a
+    signal, \c{valueChanged()}, and it has a slot which other objects
+    can send signals to.
+
+    All classes that contain signals or slots must mention
+    Q_OBJECT at the top of their declaration. They must also derive
+    (directly or indirectly) from QObject.
+
+    Slots are implemented by the application programmer.
+    Here is a possible implementation of the \c{Counter::setValue()}
+    slot:
+
+    \snippet doc/src/snippets/signalsandslots/signalsandslots.cpp 0
+
+    The \c{emit} line emits the signal \c valueChanged() from the
+    object, with the new value as argument.
+
+    In the following code snippet, we create two \c Counter objects
+    and connect the first object's \c valueChanged() signal to the
+    second object's \c setValue() slot using QObject::connect():
+
+    \snippet doc/src/snippets/signalsandslots/signalsandslots.cpp 1
+    \snippet doc/src/snippets/signalsandslots/signalsandslots.cpp 2
+    \codeline
+    \snippet doc/src/snippets/signalsandslots/signalsandslots.cpp 3
+    \snippet doc/src/snippets/signalsandslots/signalsandslots.cpp 4
+
+    Calling \c{a.setValue(12)} makes \c{a} emit a
+    \c{valueChanged(12)} signal, which \c{b} will receive in its
+    \c{setValue()} slot, i.e. \c{b.setValue(12)} is called. Then
+    \c{b} emits the same \c{valueChanged()} signal, but since no slot
+    has been connected to \c{b}'s \c{valueChanged()} signal, the
+    signal is ignored.
+
+    Note that the \c{setValue()} function sets the value and emits
+    the signal only if \c{value != m_value}. This prevents infinite
+    looping in the case of cyclic connections (e.g., if
+    \c{b.valueChanged()} were connected to \c{a.setValue()}).
+
+    By default, for every connection you make, a signal is emitted;
+    two signals are emitted for duplicate connections. You can break
+    all of these connections with a single disconnect() call.
+    If you pass the Qt::UniqueConnection \a type, the connection will only
+    be made if it is not a duplicate. If there is already a duplicate
+    (exact same signal to the exact same slot on the same objects),
+    the connection will fail and connect will return false
+
+    This example illustrates that objects can work together without needing to
+    know any information about each other. To enable this, the objects only
+    need to be connected together, and this can be achieved with some simple
+    QObject::connect() function calls, or with \c{uic}'s
+    \l{Using a Designer UI File in Your Application#Automatic Connections}
+    {automatic connections} feature.
+
+    \section1 Building the Example
+
+    The C++ preprocessor changes or removes the \c{signals},
+    \c{slots}, and \c{emit} keywords so that the compiler is
+    presented with standard C++.
+
+    By running the \l moc on class definitions that contain signals
+    or slots, a C++ source file is produced which should be compiled
+    and linked with the other object files for the application. If
+    you use \l qmake, the makefile rules to automatically invoke \c
+    moc will be added to your project's makefile.
+
+    \section1 Signals
+
+    Signals are emitted by an object when its internal state has changed
+    in some way that might be interesting to the object's client or owner.
+    Only the class that defines a signal and its subclasses can emit the
+    signal.
+
+    When a signal is emitted, the slots connected to it are usually
+    executed immediately, just like a normal function call. When this
+    happens, the signals and slots mechanism is totally independent of
+    any GUI event loop. Execution of the code following the \c emit
+    statement will occur once all slots have returned. The situation is
+    slightly different when using \l{Qt::ConnectionType}{queued
+    connections}; in such a case, the code following the \c emit keyword
+    will continue immediately, and the slots will be executed later.
+
+    If several slots are connected to one signal, the slots will be
+    executed one after the other, in the order they have been connected,
+    when the signal is emitted.
+
+    Signals are automatically generated by the \l moc and must not be
+    implemented in the \c .cpp file. They can never have return types
+    (i.e. use \c void).
+
+    A note about arguments: Our experience shows that signals and slots
+    are more reusable if they do not use special types. If
+    QScrollBar::valueChanged() were to use a special type such as the
+    hypothetical QScrollBar::Range, it could only be connected to
+    slots designed specifically for QScrollBar. Connecting different
+    input widgets together would be impossible.
+
+    \section1 Slots
+
+    A slot is called when a signal connected to it is emitted. Slots are
+    normal C++ functions and can be called normally; their only special
+    feature is that signals can be connected to them.
+
+    Since slots are normal member functions, they follow the normal C++
+    rules when called directly. However, as slots, they can be invoked
+    by any component, regardless of its access level, via a signal-slot
+    connection. This means that a signal emitted from an instance of an
+    arbitrary class can cause a private slot to be invoked in an instance
+    of an unrelated class.
+
+    You can also define slots to be virtual, which we have found quite
+    useful in practice.
+
+    Compared to callbacks, signals and slots are slightly slower
+    because of the increased flexibility they provide, although the
+    difference for real applications is insignificant. In general,
+    emitting a signal that is connected to some slots, is
+    approximately ten times slower than calling the receivers
+    directly, with non-virtual function calls. This is the overhead
+    required to locate the connection object, to safely iterate over
+    all connections (i.e. checking that subsequent receivers have not
+    been destroyed during the emission), and to marshall any
+    parameters in a generic fashion. While ten non-virtual function
+    calls may sound like a lot, it's much less overhead than any \c
+    new or \c delete operation, for example. As soon as you perform a
+    string, vector or list operation that behind the scene requires
+    \c new or \c delete, the signals and slots overhead is only
+    responsible for a very small proportion of the complete function
+    call costs.
+
+    The same is true whenever you do a system call in a slot; or
+    indirectly call more than ten functions. On an i586-500, you can
+    emit around 2,000,000 signals per second connected to one
+    receiver, or around 1,200,000 per second connected to two
+    receivers. The simplicity and flexibility of the signals and
+    slots mechanism is well worth the overhead, which your users
+    won't even notice.
+
+    Note that other libraries that define variables called \c signals
+    or \c slots may cause compiler warnings and errors when compiled
+    alongside a Qt-based application. To solve this problem, \c
+    #undef the offending preprocessor symbol.
+
+    \section1 Meta-Object Information
+
+    The meta-object compiler (\l moc) parses the class declaration in
+    a C++ file and generates C++ code that initializes the
+    meta-object. The meta-object contains the names of all the signal
+    and slot members, as well as pointers to these functions.
+
+    The meta-object contains additional information such as the
+    object's \link QObject::className() class name\endlink. You can
+    also check if an object \link QObject::inherits()
+    inherits\endlink a specific class, for example:
+
+    \snippet doc/src/snippets/signalsandslots/signalsandslots.cpp 5
+    \snippet doc/src/snippets/signalsandslots/signalsandslots.cpp 6
+
+    The meta-object information is also used by qobject_cast<T>(), which
+    is similar to QObject::inherits() but is less error-prone:
+
+    \snippet doc/src/snippets/signalsandslots/signalsandslots.cpp 7
+
+    See \l{Meta-Object System} for more information.
+
+    \section1 A Real Example
+
+    Here is a simple commented example of a widget.
+
+    \snippet doc/src/snippets/signalsandslots/lcdnumber.h 0
+    \snippet doc/src/snippets/signalsandslots/lcdnumber.h 1
+    \codeline
+    \snippet doc/src/snippets/signalsandslots/lcdnumber.h 2
+    \codeline
+    \snippet doc/src/snippets/signalsandslots/lcdnumber.h 3
+    \snippet doc/src/snippets/signalsandslots/lcdnumber.h 4
+    \snippet doc/src/snippets/signalsandslots/lcdnumber.h 5
+
+    \c LcdNumber inherits QObject, which has most of the signal-slot
+    knowledge, via QFrame and QWidget. It is somewhat similar to the
+    built-in QLCDNumber widget.
+
+    The Q_OBJECT macro is expanded by the preprocessor to declare
+    several member functions that are implemented by the \c{moc}; if
+    you get compiler errors along the lines of "undefined reference
+    to vtable for \c{LcdNumber}", you have probably forgotten to
+    \l{moc}{run the moc} or to include the moc output in the link
+    command.
+
+    \snippet doc/src/snippets/signalsandslots/lcdnumber.h 6
+    \snippet doc/src/snippets/signalsandslots/lcdnumber.h 7
+
+    It's not obviously relevant to the moc, but if you inherit
+    QWidget you almost certainly want to have the \c parent argument
+    in your constructor and pass it to the base class's constructor.
+
+    Some destructors and member functions are omitted here; the \c
+    moc ignores member functions.
+
+    \snippet doc/src/snippets/signalsandslots/lcdnumber.h 8
+    \snippet doc/src/snippets/signalsandslots/lcdnumber.h 9
+
+    \c LcdNumber emits a signal when it is asked to show an impossible
+    value.
+
+    If you don't care about overflow, or you know that overflow
+    cannot occur, you can ignore the \c overflow() signal, i.e. don't
+    connect it to any slot.
+
+    If on the other hand you want to call two different error
+    functions when the number overflows, simply connect the signal to
+    two different slots. Qt will call both (in the order they were connected).
+
+    \snippet doc/src/snippets/signalsandslots/lcdnumber.h 10
+    \snippet doc/src/snippets/signalsandslots/lcdnumber.h 11
+    \snippet doc/src/snippets/signalsandslots/lcdnumber.h 12
+    \codeline
+    \snippet doc/src/snippets/signalsandslots/lcdnumber.h 13
+
+    A slot is a receiving function used to get information about
+    state changes in other widgets. \c LcdNumber uses it, as the code
+    above indicates, to set the displayed number. Since \c{display()}
+    is part of the class's interface with the rest of the program,
+    the slot is public.
+
+    Several of the example programs connect the
+    \l{QScrollBar::valueChanged()}{valueChanged()} signal of a
+    QScrollBar to the \c display() slot, so the LCD number
+    continuously shows the value of the scroll bar.
+
+    Note that \c display() is overloaded; Qt will select the
+    appropriate version when you connect a signal to the slot. With
+    callbacks, you'd have to find five different names and keep track
+    of the types yourself.
+
+    Some irrelevant member functions have been omitted from this
+    example.
+
+    \section1 Signals And Slots With Default Arguments
+
+    The signatures of signals and slots may contain arguments, and the
+    arguments can have default values. Consider QObject::destroyed():
+
+    \code
+    void destroyed(QObject* = 0); 
+    \endcode
+
+    When a QObject is deleted, it emits this QObject::destroyed()
+    signal. We want to catch this signal, wherever we might have a
+    dangling reference to the deleted QObject, so we can clean it up.
+    A suitable slot signature might be:
+
+    \code
+    void objectDestroyed(QObject* obj = 0);
+    \endcode
+
+    To connect the signal to the slot, we use QObject::connect() and
+    the \c{SIGNAL()} and \c{SLOT()} macros. The rule about whether to
+    include arguments or not in the \c{SIGNAL()} and \c{SLOT()}
+    macros, if the arguments have default values, is that the
+    signature passed to the \c{SIGNAL()} macro must \e not have fewer
+    arguments than the signature passed to the \c{SLOT()} macro.
+
+    All of these would work:
+    \code
+    connect(sender, SIGNAL(destroyed(QObject*)), this, SLOT(objectDestroyed(Qbject*)));
+    connect(sender, SIGNAL(destroyed(QObject*)), this, SLOT(objectDestroyed()));
+    connect(sender, SIGNAL(destroyed()), this, SLOT(objectDestroyed()));
+    \endcode
+    But this one won't work:
+    \code
+    connect(sender, SIGNAL(destroyed()), this, SLOT(objectDestroyed(QObject*)));
+    \endcode
+
+    ...because the slot will be expecting a QObject that the signal
+    will not send. This connection will report a runtime error.
+
+    \section1 Advanced Signals and Slots Usage
+
+    For cases where you may require information on the sender of the
+    signal, Qt provides the QObject::sender() function, which returns
+    a pointer to the object that sent the signal.
+
+    The QSignalMapper class is provided for situations where many
+    signals are connected to the same slot and the slot needs to
+    handle each signal differently.
+
+    Suppose you have three push buttons that determine which file you
+    will open: "Tax File", "Accounts File", or "Report File". 
+
+    In order to open the correct file, you use QSignalMapper::setMapping() to
+    map all the clicked() signals to a QSignalMapper object. Then you connect
+    the file's QPushButton::clicked() signal to the QSignalMapper::map() slot.
+
+    \snippet doc/src/snippets/signalmapper/filereader.cpp 0
+
+    Then, you connect the \l{QSignalMapper::}{mapped()} signal to
+    \c{readFile()} where a different file will be opened, depending on
+    which push button is pressed.
+
+    \snippet doc/src/snippets/signalmapper/filereader.cpp 1
+
+    \note The following code will compile and run, but due to signature normalization, the code will be slower.
+
+    \snippet doc/src/snippets/signalmapper/filereader.cpp 2
+
+    \sa {Meta-Object System}, {Qt's Property System}
+
+    \target 3rd Party Signals and Slots
+    \section2 Using Qt with 3rd Party Signals and Slots
+
+    It is possible to use Qt with a 3rd party signal/slot mechanism.
+    You can even use both mechanisms in the same project. Just add the
+    following line to your qmake project (.pro) file.
+
+    \snippet doc/src/snippets/code/doc_src_containers.cpp 22
+
+    It tells Qt not to define the moc keywords \c{signals}, \c{slots},
+    and \c{emit}, because these names will be used by a 3rd party
+    library, e.g. Boost. Then to continue using Qt signals and slots
+    with the \c{no_keywords} flag, simply replace all uses of the Qt
+    moc keywords in your sources with the corresponding Qt macros
+    Q_SIGNALS (or Q_SIGNAL), Q_SLOTS (or Q_SLOT), and Q_EMIT.
+*/