Doc

2 files changed, 213 insertions, 3 deletions

diff --git a/doc/src/declarative/extending-examples.qdoc b/doc/src/declarative/extending-examples.qdoc
index 09239c1..4fc1bee 100644
--- a/doc/src/declarative/extending-examples.qdoc
+++ b/doc/src/declarative/extending-examples.qdoc
@@ -256,3 +256,54 @@ This example builds on:
 \endlist
 
 */
+
+/*!
+\example declarative/extending/signal
+\title Extending QML - Signal Support Example
+
+This example builds on:
+\list
+\o \l {Extending QML - Attached Properties Example}
+\o \l {Extending QML - Grouped Properties Example}
+\o \l {Extending QML - Default Property Example}
+\o \l {Extending QML - Inheritance and Coercion Example}
+\o \l {Extending QML - Object and List Property Types Example}
+\o \l {Extending QML - Adding Types Example}
+\endlist
+
+*/
+
+/*!
+\example declarative/extending/valuesource
+\title Extending QML - Property Value Source Example
+
+This example builds on:
+\list
+\o \l {Extending QML - Signal Support Example}
+\o \l {Extending QML - Attached Properties Example}
+\o \l {Extending QML - Grouped Properties Example}
+\o \l {Extending QML - Default Property Example}
+\o \l {Extending QML - Inheritance and Coercion Example}
+\o \l {Extending QML - Object and List Property Types Example}
+\o \l {Extending QML - Adding Types Example}
+\endlist
+
+*/
+
+/*!
+\example declarative/extending/binding
+\title Extending QML - Binding Example
+
+This example builds on:
+\list
+\o \l {Extending QML - Property Value Source Example}
+\o \l {Extending QML - Signal Support Example}
+\o \l {Extending QML - Attached Properties Example}
+\o \l {Extending QML - Grouped Properties Example}
+\o \l {Extending QML - Default Property Example}
+\o \l {Extending QML - Inheritance and Coercion Example}
+\o \l {Extending QML - Object and List Property Types Example}
+\o \l {Extending QML - Adding Types Example}
+\endlist
+
+*/
diff --git a/doc/src/declarative/extending.qdoc b/doc/src/declarative/extending.qdoc
index 0f9148a..ac3dc41 100644
--- a/doc/src/declarative/extending.qdoc
+++ b/doc/src/declarative/extending.qdoc
@@ -359,15 +359,174 @@ object will only be returned if it has previously been created.
 \l {Extending QML - Attached Properties Example} shows the complete code used to
 implement the rsvp attached property.
 
-\section1 Signal support
+\section1 Signal Support
 
-\section1 Property Binding
+\snippet examples/declarative/extending/signal/example.qml 0
+\snippet examples/declarative/extending/signal/example.qml 1
+
+The QML snippet shown above associates the evaluation of a ECMAScript expression
+with the emission of a Qt signal.
+
+All Qt signals on a registered class become available as special "signal 
+propeties" within QML to which the user can assign a single ECMAScript 
+expression.  The signal property's name is a transformed version of the Qt
+signal name: "on" is prepended, and the first letter of the signal name upper
+cased.  For example, the signal used in the example above has the following
+C++ signature:
+
+\snippet examples/declarative/extending/signal/birthdayparty.h 0
+
+In classes with multiple signals with the same name, only the final signal
+is accessible as a signal property.  Although QML provides an element, 
+\l Connection, for accessing the other signals it is less elegant.  For the best
+QML API, class developers should avoid overloading signal names.
+
+Signal parameters become accessible by name to the assigned script.  An
+unnamed parameter cannot be accessed, so care should be taken to name all the
+signal parameters in the C++ class declaration.  The intrinsic types
+listed in \l {Adding Types}, as well registered object types are permitted as 
+signal parameter types.  Using other types is not an error, but the parameter
+value will not be accessible from script.
+
+\l {Extending QML - Signal Support Example} shows the complete code used to
+implement the onPartyStarted signal property.
 
 \section1 Property Value Sources
 
+\snippet examples/declarative/extending/valuesource/example.qml 0
+\snippet examples/declarative/extending/valuesource/example.qml 1
+
+The QML snippet shown above assigns a property value to the speaker property.
+A property value source generates a value for a property that changes over time.
+
+Property value sources are most commonly used to do animation.  Rather than 
+constructing an animation object and manually setting the animation's "target"
+property, a property value source can be assigned directly to a property of any
+type and automatically set up this association.
+
+The example shown here is rather contrived: the speaker property of the 
+BirthdayParty object is a string that is printed every time it is assigned and
+the HappyBirthday value source generates the lyrics of the song 
+"Happy Birthday".
+
+\snippet examples/declarative/extending/valuesource/birthdayparty.h 0
+
+Normally, assigning an object to a string property would not be allowed.  In
+the case of a property value source, rather than assigning the object instance
+itself, the QML engine sets up an association between the value source and
+the property.
+
+Property value sources are special types that derive from the 
+QmlPropertyValueSource base class.  This base class contains a single method,
+QmlPropertyValueSource::setTarget(), that the QML engine invokes when 
+associating the property value source with a property.  The relevant part of
+the HappyBirthday type declaration looks like this:
+
+\snippet examples/declarative/extending/valuesource/happybirthday.h 0
+\snippet examples/declarative/extending/valuesource/happybirthday.h 1
+\snippet examples/declarative/extending/valuesource/happybirthday.h 2
+
+In all other respects, property value sources are regular QML types.  They must
+be registered with the QML engine using the same macros as other types, and can
+contain properties, signals and methods just like other types.  
+
+When a property value source object is assigned to a property, QML first tries
+to assign it normally, as though it were a regular QML type.  Only if this 
+assignment fails does the engine call the setTarget() method.  This allows
+the type to also be used in contexts other than just as a value source.
+
+\l {Extending QML -  Property Value Source Example} shows the complete code used
+implement the HappyBirthday property value source.
+
+\section1 Property Binding
+
+\snippet examples/declarative/extending/binding/example.qml 0
+\snippet examples/declarative/extending/binding/example.qml 1
+
+The QML snippet shown above uses a property binding to ensure the 
+HappyBirthday's name property remains up to date with the celebrant.
+
+Property binding is a core feature of QML.  In addition to assigning literal
+values, property bindings allow the developer to assign an arbitrarily complex 
+ECMAScript expression that may include dependencies on other property values.
+Whenever the expression's result changes - through a change in one of its 
+constituent values - the expression is automatically reevaluated and
+the new result assigned to the property.
+
+All properties on custom types automatically support property binding.  However,
+for binding to work correctly, QML must be able to reliably determine when a 
+property has changed so that it knows to reevaluate any bindings that depend on
+the property's value.  QML relies on the presence of a 
+\c {Qt's Property System}{NOTIFY signal} for this determination.
+
+Here is the celebrant property declaration:
+
+\snippet examples/declarative/extending/binding/birthdayparty.h 0
+
+The NOTIFY attribute is followed by a signal name.  It is the responsibility of
+the class implementer to ensure that whenever the property's value changes, the
+NOTIFY signal is emitted.  The signature of the NOTIFY signal is not important to QML.
+
+To prevent loops or excessive evaluation, developers should ensure that the 
+signal is only emitted whenever the property's value is actually changed.  If
+a property, or group of properties, is infrequently used it is permitted to use
+the same NOTIFY signal for several properties.  This should be done with care to
+ensure that performance doesn't suffer.
+
+To keep QML reliable, if a property does not have a NOTIFY signal, it cannot be
+used in a binding expression.  However, the property can still be assigned
+a binding as QML does not need to monitor the property for change in that 
+scenario.
+
+Consider a custom type, \c TestElement, that has two properties, "a" and "b".  
+Property "a" does not have a NOTIFY signal, and property "b" does have a NOTIFY
+signal.
+
+\code
+TestElement {
+    // This is OK
+    a: b
+}
+TestElement {
+    // Will NOT work
+    b: a
+}
+\endcode
+
+The presence of a NOTIFY signal does incur a small overhead.  There are cases
+where a property's value is set at object construction time, and does not 
+subsequently change.  The most common case of this is when a type uses
+\l {Grouped Properties}, and the grouped property object is allocated once, and
+only freed when the object is deleted.  In these cases, the CONSTANT attribute
+may be added to the property declaration instead of a NOTIFY signal.
+
+\snippet examples/declarative/extending/binding/person.h 0
+
+Extreme care must be taken here or applications using your type may misbehave.
+The CONSTANT attribute should only be used for properties whose value is set,
+and finalized, only in the class constructor.  All other properties that want
+to be used in bindings should have a NOTIFY signal instead.
+
+\l {Extending QML -  Binding Example} shows the BirthdayParty example updated to
+include NOTIFY signals for use in binding.
+
 \section1 Extension Objects
 
-\section1 Parser Status
+\snippet examples/declarative/extending/extended/example.qml 0
+
+The QML snippet shown above adds a new property to an existing C++ type without
+modifying its source code.
+
+When integrating existing classes and technology into QML, their APIs will often
+need to be tweaked to fit better into the declarative environment.  Although
+the best results are usually obtained by modifying the original classes 
+directly, if this is either not possible or is complicated by some other 
+concerns extension objects allow limited extension possibilities without 
+direct modifications.
+
+Extension objects can only add properties.
+
+\section1 Optimization
 
 */