1 files changed, 89 insertions, 16 deletions
diff --git a/doc/src/declarative/extending.qdoc b/doc/src/declarative/extending.qdoc
index 6476dfb..3acfbdf 100644
--- a/doc/src/declarative/extending.qdoc
+++ b/doc/src/declarative/extending.qdoc
@@ -65,20 +65,22 @@ template<typename T>
 int qmlRegisterType(const char *uri, int versionMajor, int versionMinor, const char *qmlName)
 \endcode
 
-Calling qmlRegisterType() registers the C++ type \a T with the QML system, and makes it available in QML
-under the name \a qmlName in library \a uri version \a versionMajor.versionMinor.
-The \a qmlName can be the same as the C++ type name.
+Calling qmlRegisterType() registers the C++ type \a T with the QML
+system, and makes it available in QML under the name \a qmlName in
+library \a uri version \a versionMajor.versionMinor.  The \a qmlName
+can be the same as the C++ type name.
 
 Type \a T must be a concrete type that inherits QObject and has a default
 constructor.
+
 \endquotation
 
-Types can be registered by libraries (such as Qt does), application code,
-or by plugins (see QDeclarativeExtensionPlugin).
+Types can be registered by libraries, application code, or by plugins
+(see QDeclarativeExtensionPlugin).
 
-Once registered, all of the \l {Qt's Property System}{properties} of a supported
-type are available for use within QML.  QML has intrinsic support for properties
-of these types:
+Once registered, all \l {Qt's Property System}{properties} of the
+supported types are available in QML.  QML has intrinsic support for
+properties of these types:
 
 \list
 \o bool
@@ -94,9 +96,14 @@ of these types:
 \o QVariant
 \endlist
 
-QML is typesafe.  Attempting to assign an invalid value to a property will
-generate an error.  For example, assuming the name property of the \c Person
-element had a type of QString, this would cause an error:
+When a property of a supported type is added to a C++ class, in a QML
+element based on the C++ class, a \e{value-changed} signal handler
+will be available. See \l{Signal Support} below.
+
+QML is typesafe.  Attempting to assign an invalid value to a property
+will generate an error.  For example, assuming the \e{name} property
+of the \c Person element had a type of QString, this would cause an
+error:
 
 \code
 Person {
@@ -412,7 +419,20 @@ value will not be accessible from script.
 implement the onPartyStarted signal property.
 
 If you want to use signals from items not created in QML, you can access their
-signals with the \l {Connections} element.
+signals with the \l {Connections} element.
+
+Additionally, if a property is added to a C++ class, all QML elements
+based on that C++ class will have a \e{value-changed} signal handler
+for that property. The name of the signal handler is
+\e{on<Property-name>Changed}, with the first letter of the property
+name being upper case.
+
+\note The QML signal handler will always be named
+on<Property-name>Changed, regardless of the name used for the NOTIFY
+signal in C++. We recommend using <property-name>Changed() for the
+NOTIFY signal in C++.
+
+See also \l {Extending types from QML}.
 
 \section1 Property Value Sources
 
@@ -684,10 +704,6 @@ of some of the types. For the remaining types the default values are undefined.
 \row \o color \o #000000 (black)
 \endtable
 
-If specified, the optional "default" attribute marks the new property as the
-types default property, overriding any existing default property.  Using the
-default attribute twice in the same type block is an error.
-
 The following example shows how to declare a new "innerColor" property that
 controls the color of the inner rectangle.
 
@@ -705,6 +721,63 @@ controls the color of the inner rectangle.
     }
 \endcode
 
+
+\section3 Property signal handlers
+
+Adding a property to an item automatically adds a \e{value-changed}
+signal handler to the item. The signal hander is named
+\c{on<Property_name>Changed}, with the first letter of the property
+name being upper case.
+
+Signal handlers can have arbitrary JavaScript code assigned. The following 
+example shows how to output to a text console a new value of property 
+\c{innerColor} whenever the value of this property changes.
+
+\code
+    Rectangle {
+        id: rect
+        property color innerColor: "black"
+
+        onInnerColorChanged: { console.log(rect.innerColor); }
+    }
+\endcode
+
+
+\section3 Setting default properties
+
+The optional \c default attribute for a property marks it as the \e {default property}
+for a type. This allows other items to specify the default property's value
+as child elements. For example, the \l Item element's default property is its 
+\l{Item::children}{children} property. This allows the children of an \l Item 
+to be set like this:
+
+\qml
+Item {
+    Rectangle {}
+    Rectangle {}
+}
+\endqml
+
+If the \l{Item::children}{children} property was not the default property for 
+\l Item, its value would have to be set like this instead:
+
+\qml
+Item {
+    children: [
+        Rectangle {}
+        Rectangle {}
+    ]
+}
+\endqml
+
+See the \l{declarative/ui-components/tabwidget}{TabWidget} example for a
+demonstration of using default properties.
+
+Specifying a default property overrides any existing default property (for
+example, any default property inherited from a parent item). Using the
+default attribute twice in the same type block is an error.
+
+
 \target qml-property-aliases
 \section2 Property aliases