Add 'Writing New Components' docs, and document the connect() function.

The 'Writing QML Components' is mainly a restructuring of the
'Extending types from QML' page. It also documents the signal
connect() function that was previously undocumented.

Task-number: QTBUG-15718, QTBUG-15138

9 files changed, 342 insertions, 315 deletions

diff --git a/doc/src/declarative/basictypes.qdoc b/doc/src/declarative/basictypes.qdoc
index 71192bf..034b7d1 100644
--- a/doc/src/declarative/basictypes.qdoc
+++ b/doc/src/declarative/basictypes.qdoc
@@ -33,7 +33,7 @@
     the \l {QML Elements}.
 
     Some of these types can also be used for defining 
-    \c property values in QML. See \l{Extending types from QML} for the
+    \c property values in QML. See \l{Writing QML Components: Properties, Methods and Signals} for the
     list of types that can be used for \c property values.
 
     \annotatedlist qmlbasictypes
@@ -380,7 +380,7 @@
     \c child1, \c child2 and \c child3 will be added to the children list
     in the order in which they appear.
 
-    List \l {Adding new properties}{properties} can be created as a
+    List \l {Adding Properties}{properties} can be created as a
     \c variant type, or as a \c list<Type> type, where \c Type is the
     type of the object in the list:
 
diff --git a/doc/src/declarative/declarativeui.qdoc b/doc/src/declarative/declarativeui.qdoc
index 01e1302..5d9eaaf 100644
--- a/doc/src/declarative/declarativeui.qdoc
+++ b/doc/src/declarative/declarativeui.qdoc
@@ -91,9 +91,10 @@ Module.
 \list
 \o \l{QML Documents}
 \o \l{Property Binding}
+\o \l{Anchor-based Layout in QML}
+\o \l{Writing QML Components: Properties, Methods and Signals}
 \o \l{QML Scope}
 \o \l{QML Modules}
-\o \l{Anchor-based Layout in QML}
 \endlist
 
 \section1 User Interaction
@@ -118,7 +119,6 @@ Module.
 \list
 \o \l{Qt Declarative UI Runtime}
 \o \l{Integrating JavaScript}
-\o \l{Extending types from QML}
 \o \l{Dynamic Object Management in QML}
 \endlist
 
diff --git a/doc/src/declarative/dynamicobjects.qdoc b/doc/src/declarative/dynamicobjects.qdoc
index daf2ae1..fcc9fd4 100644
--- a/doc/src/declarative/dynamicobjects.qdoc
+++ b/doc/src/declarative/dynamicobjects.qdoc
@@ -102,6 +102,9 @@ Notice in both instances, \l {Component::createObject()}{createObject()} is call
 When using files with relative paths, the path should
 be relative to the file where \l {QML:Qt::createComponent()}{Qt.createComponent()} is executed.
 
+To connect signals to (or receive signals from) dynamically created objects, use the signal
+\c connect() method. See \l {Connecting signals to methods and other signals} for more information.
+
 
 \section2 Creating an object from a string of QML
 
diff --git a/doc/src/declarative/extending-tutorial.qdoc b/doc/src/declarative/extending-tutorial.qdoc
index dff1d9c..c998c5c 100644
--- a/doc/src/declarative/extending-tutorial.qdoc
+++ b/doc/src/declarative/extending-tutorial.qdoc
@@ -285,8 +285,8 @@ int-type property to store an identifier for each chart:
     }
 \endcode
 
-We can also use various other property types. QML has built-in support for the following
-types listed in the \l{Extending Types from QML} document, including the following:
+We can also use various other property types. QML has built-in support for the types
+listed in the \l{Adding Properties} documentation, which includes the following:
 
 \list
 \o bool, unsigned int, int, float, double, qreal
diff --git a/doc/src/declarative/extending.qdoc b/doc/src/declarative/extending.qdoc
index 740f7d1..fc5c586 100644
--- a/doc/src/declarative/extending.qdoc
+++ b/doc/src/declarative/extending.qdoc
@@ -82,8 +82,8 @@ Types can be registered by libraries, application code, or by plugins
 
 Once registered, all \l {Qt's Property System}{properties} of the
 supported types are available in QML.  QML has intrinsic support for
-properties of the types listed in the \l{Extending Types from QML}
-document, including the following:
+properties of the types listed in the \l{Adding Properties}
+document, which includes the following:
 
 \list
 \o bool, unsigned int, int, float, double, qreal
@@ -429,7 +429,7 @@ 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}.
+See also \l {Writing QML Components: Properties, Methods and Signals}
 
 \section1 Methods
 
@@ -637,147 +637,177 @@ public:
 
 /*!
 \page qml-extending-types.html
-\title Extending Types from QML
+\title Writing QML Components: Properties, Methods and Signals
 
-Many of the elements available for use in QML are implemented in
-\l {Extending QML in C++}{C++}.  These types are know as "core types".  QML
-allows programmers to build new, fully functional elements without using C++.
-Existing core types can be extended, and new types defined entirely in the QML
-language.
+One of the key concepts in QML is the ability to define your own QML components that suit
+the purposes of your application. The standard \l {QML Elements} provide the essential components
+for creating a QML application; beyond these, you can write your own custom components that can
+be created and reused, without the use of C++.
 
-\tableofcontents
+Components are the building blocks of a QML project. When writing a QML application, whether
+large or small, it is best to separate QML code into smaller components that perform specific
+sets of operations, instead of creating mammoth QML files with large, combined functionality
+that is more difficult to manage and may contain duplicated code.
+
+
+\section1 Defining New Components
 
-\section1 Adding new properties
+A component is a reusable type with a well-defined interface, built entirely in QML.
+Any snippet of QML code can become a component, by placing the code in a file "<Name>.qml" where
+<Name> is the new component name, beginning with an uppercase letter. These QML files automatically
+become available as new QML element types to other QML components and applications in the same directory.
 
-New properties can be added to an existing type using the \c property keyword.
-These new properties are
-available for use within QML, and also appear as regular Qt properties on the
-C++ object, accessible through the regular property access mechanisms.
+For example, one of the simplest and most common components you can build in QML is a
+button-type component. Below, we implement this component as a \l Rectangle with a clickable
+\l MouseArea, in a file named \c Button.qml:
 
-Like all properties in QML, custom properties are typed.  The type is used to
-define the property's behavior, and also determines the C++ type of the created
-Qt property.  The following table shows the list of types available when
-declaring a new property, and the corresponding C++ type.
+\snippet doc/src/snippets/declarative/qml-extending-types/components/Button.qml 0
+
+Now this component can be reused by another file within the same directory. Since the file is
+named \c Button.qml, the component is referred to as \c Button:
 
 \table
-\header \o QML Type Name \o C++ Type Name
-\row \o int \o int
-\row \o bool \o bool
-\row \o double \o double
-\row \o real \o double
-\row \o string \o QString
-\row \o url \o QUrl
-\row \o color \o QColor
-\row \o date \o QDateTime
-\row \o variant \o QVariant
+\row
+\o \snippet doc/src/snippets/declarative/qml-extending-types/components/application.qml 0
+\o \image qml-extending-types.png
 \endtable
 
-From QML you can also declare object and list properties using any element name
-like this:
+The root object in \c Button.qml defines the attributes that are available to users of the
+\c Button component. In this case, the root object is a \l Rectangle, so any properties, methods
+and signals of \l Rectangle are made available, allowing \c application.qml to
+customize the \c width, \c height, \c radius and \c color properties of \c Button objects.
 
-\code
-    property QtObject objectProperty
-    property Item itemProperty
-    property MyCustomType customProperty
-    property list<Item> listOfItemsProperty
-\endcode
 
-Custom types must be registered with qmlRegisterType() to be usable as a property
-type. Also note that list properties cannot be modified like ordinary JavaScript
-arrays; see the \l {list}{list type documentation} for details.
+If \c Button.qml was not in the same directory, \c application.qml would need to load it as a
+\l {Modules}{module} from a specific filesystem path or \l{QDeclarativeExtensionPlugin}{plugin}.
+Also, note the letter case of the component file name is significant on some (notably UNIX)
+filesystems. It is recommended the file name case matches the case of the QML component name
+exactly - for example, \c Box.qml and not \c BoX.qml - regardless of the platform to which the
+QML component will be deployed.
+
+To write a useful component, it is generally necessary to provide it with custom attributes that store and
+communicate specific data. This is achieved by adding the following attributes to your components:
+
+\list
+\o \bold Properties that can be accessed externally to modify an object (for example, \l Item has
+   \l {Item::}{width} and \l {Item::}{height} properties) and used in \l {Property Binding}
+\o \bold Methods of JavaScript code can be invoked internally or externally (for example,
+   \l Animation has a \l {Animation::}{start()} method)
+\o \bold Signals to notify other objects when an event has occurred (for example, MouseArea has a
+   \c clicked signal)
+\endlist
+
+The following sections show how these attributes can be added to QML components.
 
-QML supports two methods for adding a new property to a type: a new property
-definition, and a property alias. These are shown below.
 
-\section2 Property definitions
+\section1 Adding Properties
 
-Property definitions add a new property to an existing type.  The storage of the
-property is managed by QML.  The defined property may be read, written and bound
-to and from.
+A property is a value of a QML component that can be read and modified by other objects. For
+example, a \l Rectangle component has \l {Item::}{width}, \l {Item::}{height} and \l
+{Rectangle::}{color} properties. Significantly, properties be used with \l {Property Binding}, where
+a property value is automatically updated using the value of another property.
 
 The syntax for defining a new property is:
+
 \code
-    [default] property <type> <name>[: defaultValue]
+[default] property <type> <name>[: defaultValue]
 \endcode
 
-This declaration may appear anywhere within a type body, but it is customary to
-include it at the top.  Attempting to declare two properties with the same name
-in the same type block is an error.  However, a new property may reuse the name
-of an existing property on the type.  This should be done with caution, as the
-existing property will be hidden, and become inaccessible.
+A \c property declaration can appear anywhere within a QML component definition, but it is customary
+to place it at the top. A component cannot declare more than one property with the same name. (It is
+possible to have a property name that is the same as an existing property in a type, but this is not
+recommended as the existing property becomes hidden and inaccessible.)
 
-The <type> must be one of the QML type names shown in the above table.
-Additionally, an optional default value of the property can be provided.  The
-default value is a convenient shortcut, but is behaviorally identical to doing
-it in two steps, like this:
+Below is an example. The \c ImageViewer component has defined a \c string type property named
+\c currentImage, and its initial value is "default-image.png". This property is used to set the image
+displayed in the child \l Image object. Another file, \c application.qml, can create
+an \c ImageViewer object and read or modify the \c currentImage value:
 
-\code
-    // Use default value
-    property int myProperty: 10
+\table
+\row
+\o \snippet doc/src/snippets/declarative/qml-extending-types/properties/ImageViewer.qml 0
+\o \snippet doc/src/snippets/declarative/qml-extending-types/properties/application.qml 0
+\endtable
 
-    // Longer, but behaviorally identical
-    property int myProperty
-    myProperty: 10
-\endcode
+It is optional for a property to have a default value. The default value is a convenient shortcut, and is
+behaviorally identical to doing it in two steps, like this:
+
+\qml
+// Use default value
+property int myProperty: 10
+
+// Longer, but behaviorally identical
+property int myProperty
+myProperty: 10
+\endqml
 
-If a default value is not supplied or set later in the file, each type has a
-default value for when none is explicitly set. Below are the default values
-of some of the types. For the remaining types the default values are undefined.
+
+\section2 Supported property types
+
+All QML properties are typed. The examples above show properties with \c int and \c string types;
+notice that the type of the property must be declared. The type is used to determine the property
+behavior, and how the property is defined in C++.
+
+A number of property types are supported by default. These are listed in the table below,
+with their default values and the corresponding C++ type:
 
 \table
-\header \o QML Type \o Default Value
-\row \o bool \o false
-\row \o int \o 0
-\row \o double, real \o 0.0
-\row \o string, url \o "" (an empty string)
-\row \o color \o #000000 (black)
+\header \o QML Type Name \o Default value \o C++ Type Name
+\row \o int \o 0 \o int
+\row \o bool \o \c false \o bool
+\row \o double \o 0.0 \o double
+\row \o real \o 0.0 \o double
+\row \o string \o "" (empty string) \o QString
+\row \o url \o "" (empty url) \o QUrl
+\row \o color \o #000000 (black) \o QColor
+\row \o date \o \c undefined \o QDateTime
+\row \o variant \o \c undefined \o QVariant
 \endtable
 
-The following example shows how to declare a new "innerColor" property that
-controls the color of the inner rectangle.
+QML object types can also be used as property types. This includes
+\l {Defining new QML elements}{custom QML types} implemented in C++. Such properties are
+defined like this:
 
-\code
-    Rectangle {
-        property color innerColor: "black"
-
-        color: "red"; width: 100; height: 100
-        Rectangle {
-            anchors.centerIn: parent
-            width: parent.width - 10
-            height: parent.height - 10
-            color: innerColor
-        }
-    }
-\endcode
+\qml
+property Item itemProperty
+property QtObject objectProperty
+property MyCustomType customProperty
+\endqml
 
+Such object-type properties default to an \c undefined value.
 
-\section3 Property signal handlers
+\l{list}{List properties} are created with the \c list<Type> syntax, and default to an empty
+list:
 
-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.
+\qml
+property list<Item> listOfItems
+\endqml
 
-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.
+Note that list properties cannot be modified like ordinary JavaScript
+arrays. See the \l {list}{list type documentation} for details.
 
-\code
-    Rectangle {
-        id: rect
-        property color innerColor: "black"
+For details about accessing and manipulating QML properties from C++, see \l {Using QML with C++}.
 
-        onInnerColorChanged: { console.log(rect.innerColor); }
-    }
-\endcode
 
+\section2 Property change signals
+
+Adding a \c property to an item automatically adds a \e {value changed}
+signal handler to the item. To connect to this signal, use a \l {Signal Handlers}{signal handler}
+named with the \c on<Property>Changed syntax, using upper case for the first letter of the
+property name.
+
+For example, the following \c onMyNumberChanged signal handler is automatically called whenever the
+\c myNumber property changes:
+
+\snippet doc/src/snippets/declarative/qml-extending-types/properties/property-signals.qml 0
 
-\section3 Setting default properties
+
+\section2 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 
+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
@@ -787,7 +817,7 @@ Item {
 }
 \endqml
 
-If the \l{Item::children}{children} property was not the default property for 
+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
@@ -804,21 +834,20 @@ 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.
+\c default attribute twice in the same type block is an error.
 
 
-\target qml-property-aliases
 \section2 Property aliases
 
 Property aliases are a more advanced form of property declaration.  Unlike a
-property definition, that allocates a new, unique storage space for the
+property definition, which allocates a new, unique storage space for the
 property, a property alias connects the newly declared property (called the
-aliasing property) to an existing property (the aliased property).  Read
+aliasing property) as a direct reference to an existing property (the aliased property).  Read
 operations on the aliasing property act as read operations on the aliased
 property, and write operations on the aliasing property as write operations on
 the aliased property.
 
-A property alias declaration looks a lot like a property definition:
+A property alias declaration looks a lot like an ordinary property definition:
 \code
     [default] property alias <name>: <alias reference>
 \endcode
@@ -829,7 +858,7 @@ value, a property alias includes a compulsory alias reference.  The alias
 reference is used to locate the aliased property.  While similar to a property
 binding, the alias reference syntax is highly restricted.
 
-An alias reference takes one of the following forms
+An alias reference takes one of the following forms:
 \code
     <id>.<property>
     <id>
@@ -838,61 +867,58 @@ An alias reference takes one of the following forms
 where <id> must refer to an object id within the same component as the type
 declaring the alias, and, optionally, <property> refers to a property on that object.
 
-Here is the property definition example rewritten to use property aliases.
-\code
-Rectangle {
-    property alias innerColor: innerRect.color
-
-    color: "red"; width: 100; height: 100
-    Rectangle {
-        id: innerRect
-        anchors.centerIn: parent
-        width: parent.width - 10
-        height: parent.height - 10
-        color: "black"
-    }
-}
-\endcode
+For example, below is a \c Button.qml component with a \c buttonText aliased property which is
+connected to the child Text object's \c text property:
+
+\snippet doc/src/snippets/declarative/qml-extending-types/properties/alias.qml 0
+
+The following code would create a \c Button with a defined text string for the
+child \l Text object:
 
-Aliases are most useful when \l {Defining new Components}.  Consequently
-they have several apparent limitations that only make sense in this context.
+\qml
+Button { buttonText: "This is a button" }
+\endqml
+
+Here, modifying \c buttonText directly modifies the \c textItem.text value; it does not
+change some other value that then updates \c textItem.text.
+
+In this case, the use of aliased properties is essential. If \c buttonText was not an alias,
+changing its value would not actually change the displayed text at all, as
+\l {Property Binding}{property bindings} are not bi-directional: the \c buttonText value would
+change when \c textItem.text changes, but not the other way around.
+
+Aliased properties are also useful for allowing external objects to directly modify and
+access child objects in a component. For example, here is a modified version of the \c ImageViewer
+component shown \l {Adding Properties}{earlier} on this page. The \c currentImage property has
+been changed to an alias to the child \l Image object:
+
+\table
+\row
+\o \snippet doc/src/snippets/declarative/qml-extending-types/properties/alias/ImageViewer.qml 0
+\o \snippet doc/src/snippets/declarative/qml-extending-types/properties/alias/application.qml 0
+\endtable
+
+Instead of being limited to setting the \l Image source, \c application.qml can now directly
+access and modify the child \l Image object and its properties.
+
+Obviously, exposing child objects in this manner should be done with care, as it allows external
+objects to modify them freely. However, this use of aliased properties can be quite useful in
+particular situations, such as for the \l {declarative/ui-components/tabwidget}{TabWidget}
+example, where new tab items are actually parented to a child object that displays the current tab.
+
+
+\section3 Considerations for property aliases
 
 Aliases are only activated once the component specifying them is completed.  The
 most obvious consequence of this is that the component itself cannot generally
-use the aliased property directly.  For example, this will not work:
+use the aliased property directly during creation.  For example, this will not work:
 
 \code
     // Does NOT work
-    property alias innerColor: innerRect.color
-    innerColor: "black"
+    property alias buttonText: textItem.text
+    buttonText: "Some text" // buttonText is not yet defined when this value is set
 \endcode
 
-This behavior is required to allow type developers to redefine the behavior
-of existing property names while continuing to use the existing behavior within
-the type they are building, something that is not possible with property
-definitions.  In the example used so far, this could allows the developer to fix
-the external rectangle's color as "red" and redefine the "color" property to
-refer to the inner rectangle, like this:
-
-\code
-Rectangle {
-    property alias color: innerRect.color
-
-    color: "red"; width: 100; height: 100
-    Rectangle {
-        id: innerRect
-        anchors.centerIn: parent
-        width: parent.width - 10
-        height: parent.height - 10
-        color: "black"
-    }
-}
-\endcode
-
-Users of this type would not be able to affect the color of the red rectangle,
-but would find using the "color" property, rather than the strange new
-"innerColor" property, much more familiar.
-
 A second, much less significant, consequence of the delayed activation of
 aliases is that an alias reference cannot refer to another aliasing property
 declared within the same component.  This will not work:
@@ -900,198 +926,177 @@ declared within the same component.  This will not work:
 \code
     // Does NOT work
     id: root
-    property alias innerColor: innerRect.color
-    property alias innerColor2: root.innerColor
+    property alias buttonText: textItem.text
+    property alias buttonText2: root.buttonText
 \endcode
 
-From outside the component, aliasing properties appear as regular Qt properties
-and consequently can be used in alias references.
+At the time the component is created, the \c buttonText value has not yet been assigned,
+so \c root.buttonText would refer to an undefined value. (From outside the component,
+however, aliasing properties appear as regular Qt properties and consequently can be
+used in alias references.)
 
-\section1 Adding new signals
+It is possible for an aliased property to have the same name as an existing property. For example,
+the following component has a \c color alias property, named the same as the built-in
+\l {Rectangle::color} property:
 
-New signals can be added to an existing type.  These new signals are available
-for use within QML, and also appear as regular Qt signals on the C++ object that
-can be used in Qt signal/slot connections.
+\snippet doc/src/snippets/declarative/qml-extending-types/properties/alias-override.qml 0
+
+Any objects that use this component and refer to its \c color property will be
+referring to the alias rather than the ordinary \l {Rectangle::color} property. Internally,
+however, the rectangle can correctly set this property to "red" and refer to the actual defined
+property rather than the alias.
+
+
+\section1 Adding Methods
+
+A QML component can define methods of JavaScript code. These methods can be invoked
+either internally or by other objects.
+
+The syntax for defining a method is:
 
-The syntax for defining a new signal is:
 \code
-signal <name>[([<type> <parameter name>[, ...]])]
+function <name>([<parameter name>[, ...]]) { <body> }
 \endcode
 
 This declaration may appear anywhere within a type body, but it is customary to
-include it at the top.  Attempting to declare two signals or methods with the
-same name in the same type block is an error.  However, a new signal may reuse
-the name of an existing signal on the type.  This should be done with caution,
-as the existing signal may be hidden and become inaccessible.
+include it at the top.  Attempting to declare two methods or signals with the
+same name in the same type block is an error.  However, a new method may reuse
+the name of an existing method on the type.  (This should be done with caution,
+as the existing method may be hidden and become inaccessible.)
 
-The options for parameter types are the same as for property types (see
-\l {Adding new properties}.  If this signal has no parameters, the parameter
-list may be omitted entirely.
+Unlike \l{Adding Signals}{signals}, method parameter types do not have to be declared as they
+default to the \c variant type. The body of the method is written in JavaScript and may access
+the parameters by name.
 
-Here are three examples of signal declarations:
-\code
-    Item {
-        signal clicked
-        signal hovered()
-        signal performAction(string action, variant actionArgument)
-    }
-\endcode
+Here is an example of a component with a \c say() method that accepts a single \c text argument:
 
-Adding a signal to an item automatically adds a signal handler to it.
-The signal hander is named on<Signal name>, with the first letter of the
-signal name being upper cased. The above example item would now have the
-following signal handlers:
+\snippet doc/src/snippets/declarative/qml-extending-types/methods/app.qml 0
 
-\list
-   \o onClicked
-   \o onHovered
-   \o onPerformAction
-\endlist
+A method can be connected to a signal so that it is automatically invoked whenever the signal
+is emitted. See \l {Connecting signals to methods and other signals} below.
+
+Also see \l {Integrating JavaScript} for more information on using JavaScript with QML.
 
-\section1 Adding new methods
 
-New methods can be added to an existing type.  These new methods are available
-for use within QML, and also appear as regular Qt slots on the C++ object that
-can be used in Qt signal/slot connections.
+\section1 Adding Signals
+
+Signals provide a way to notify other objects when an event has occurred. For example, the MouseArea
+\c clicked signal notifies other objects that the mouse has been clicked within the area.
+
+The syntax for defining a new signal is:
 
 \code
-function <name>([<parameter name>[, ...]]) { <body> }
+signal <name>[([<type> <parameter name>[, ...]])]
 \endcode
 
 This declaration may appear anywhere within a type body, but it is customary to
-include it at the top.  Attempting to declare two methods or signals with the
-same name in the same type block is an error.  However, a new method may reuse
-the name of an existing method on the type.  This should be done with caution,
-as the existing method may be hidden and become inaccessible.
+include it at the top.  Attempting to declare two signals or methods with the
+same name in the same type block is an error.  However, a new signal may reuse
+the name of an existing signal on the type. (This should be done with caution,
+as the existing signal may be hidden and become inaccessible.)
 
-Methods parameters are not typed.  In C++ these parameters are of type QVariant.
-The body of the method is written in JavaScript and may access the parameters by
-name.
+Here are three examples of signal declarations:
 
-This example adds a new method that behaves like a child:
 \code
 Item {
-    function say(text) {
-        console.log("You said " + text);
-    }
+    signal clicked
+    signal hovered()
+    signal performAction(string action, variant actionArgument)
 }
 \endcode
 
-This may be connected to via QObject::connect() or called directly from C++ using
-QMetaObject::invokeMethod():
+If the signal has no parameters, the "()" brackets are optional. If parameters are used, the
+parameter types must be declared, as for the \c string and \c variant arguments for the \c
+performAction signal above; the allowed parameter types are the same as those listed in the \l
+{Adding Properties} section on this page.
 
-\code
-    QDeclarativeEngine engine;
-    QDeclarativeContext *context = new QDeclarativeContext(engine.rootContext());
-    QDeclarativeComponent component(&engine, QUrl::fromLocalFile("main.qml"));
-    QObject *object = component.create(context);
-    QVariant str("Hello");
-    QMetaObject::invokeMethod(object, "say", Q_ARG(QVariant, str));
-\endcode
-
-Return values of type QVariant are also supported via Q_RETURN_ARG.
-
-\section1 Defining new Components
-\target components
+Adding a signal to an item automatically adds a \l {Signal Handlers}{signal handler} as well.
+The signal hander is named \c on<SignalName>, with the first letter of the signal being upper
+cased. The above example item would now have the following signal handlers:
 
-A component is a reusable type with a well-defined interface built entirely in
-QML.  Components appear as regular QML elements, and can be used interchangeably
-with core types.  Components allow developers to create new types to be reused
-in other projects without the use of C++.  Components can also help to reduce
-duplication inside one project by limiting the need for large numbers of
-copy-and-pasted blocks.
+\list
+\o onClicked
+\o onHovered
+\o onPerformAction
+\endlist
 
-Any snippet of QML code can become a component, just by placing it in the file "<Name>.qml" 
-where <Name> is the new element name, and begins with an uppercase letter.  Note that
-the case of all characters in the <Name> are significant on some filesystems, notably
-UNIX filesystems.  It is recommended that the case of the filename matches the case of
-the component name in QML exactly, regardless of the platform the QML will be deployed to.
+To emit a signal, simply invoke it in the same way as a method. Below left, when the \l MouseArea is
+clicked, it emits the parent \c buttonClicked signal by invoking \c rect.buttonClicked(). The
+signal is received by \c application.qml through an \c onButtonClicked signal handler:
 
-These QML files automatically become available as new QML element types
-to other QML components and applications in the same directory.
+\table
+\row
+\o \snippet doc/src/snippets/declarative/qml-extending-types/signals/basic.qml 0
+\o \snippet doc/src/snippets/declarative/qml-extending-types/signals/no-parameters.qml 0
+\endtable
 
-For example, here we show how a component named "Box" is defined and used
-multiple times by an application.
+If the signal has parameters, they are accessible by parameter name in the signal handler.
+In the example below, \c buttonClicked is emitted with \c xPos and \c yPos parameters instead:
 
 \table
 \row
-\o application.qml
-\code
-Rectangle {
-    width: 100; height: 400;
-    Box { x: 0; y: 0 }
-    Box { x: 0; y: 150 }
-    Box { x: 0; y: 300 }
-}
-\endcode
-\o Box.qml
-\code
-Rectangle {
-    width: 100; height: 100;
-    color: "blue"
-}
-\endcode
+\o \snippet doc/src/snippets/declarative/qml-extending-types/signals/Button.qml 0
+\o \snippet doc/src/snippets/declarative/qml-extending-types/signals/parameters.qml 0
 \endtable
 
-Components may be collected into \l {Modules} that gives the
-developer more freedom than just putting files in the same directory.
 
-\section2 Building reusable components
+\section2 Connecting signals to methods and other signals
 
-A component type built to be reused by others must have a well defined
-interface.  In QML, an interface consists of a defined collection of
-properties, signals and methods.  Users of a component have access to all the
-properties, signals and methods defined on the root element of the component.
+Signal objects have a \c connect() method that can be used to a connect a signal to a method or
+another signal. When a signal is connected to a method, the method is automatically invoked
+whenever the signal is emitted. (In Qt terminology, the method is a \e slot that is connected
+to the \e signal; all methods defined in QML are created as Qt slots.) This enables a signal
+to be received by a method instead of a \l {Signal Handlers}{signal handler}.
 
-In the component example above, the root element of the "Box" component is a
-Rect.  As the Rect type has a "color" property, this property is accessible to
-users of the Box component.  For example, the application.qml can be modified
-to show three different colored boxes like this:
-\code
-Rectangle {
-    width: 100; height: 400;
-    Box { x: 0; y: 0; color: "red"; }
-    Box { x: 0; y: 150; color: "yellow";  }
-    Box { x: 0; y: 300; color: "green"; }
-}
-\endcode
+For example, the \c application.qml above could be rewritten as:
 
-As expected, adding additional properties to the root element of Box, makes them
-available externally.  Here we add a "text" property:
+\snippet doc/src/snippets/declarative/qml-extending-types/signals/connectslots.qml 0
 
-\table
-\row
-\o application.qml
-\code
-Rectangle {
-    width: 100; height: 400;
-    Box { x: 0; y: 0; color: "red"; text: "stop" }
-    Box { x: 0; y: 150; color: "yellow"; text: "slow" }
-    Box { x: 0; y: 300; color: "green"; text: "go" }
-}
-\endcode
-\o Box.qml
-\code
-Rectangle {
-    property alias text: myText.text
-    width: 100; height: 100;
-    color: "blue"
-    Text {
-        id: myText
-        anchors.centerIn: parent
+The \c myMethod() method will be called whenever the \c buttonClicked signal is received.
+
+In many cases it is sufficient to receive signals through signal handlers rather than using
+the \c connect() function; the above example does not provide any improvements over using a
+simple \c onButtonClicked handler. However, if you are \l{Dynamic Object Management in QML}{creating objects dynamically},
+or \l {Integrating JavaScript}{integrating JavaScript code}, then you will find the
+\c connect() method useful. For example, the component below creates three \c Button
+objects dynamically, and connects the \c buttonClicked signal of each object to the
+\c myMethod() function:
+
+\snippet doc/src/snippets/declarative/qml-extending-types/signals/connectdynamic.qml 0
+
+In the same way, you could connect a signal to methods defined in a dynamically
+created object, or \l {Receiving QML Signals in JavaScript}{connect a signal to a JavaScript method}.
+
+There is also a corresponding \c disconnect() method for removing connected signals. The following
+code removes the connection created in \c application.qml above:
+
+\qml
+// application.qml
+Item {
+    ...
+
+    function removeSignal() {
+        button.clicked.disconnect(item.myMethod)
     }
 }
-\endcode
-\endtable
+\endqml
+
+
+\section3 Forwarding signals
+
+The \c connect() method can also connect a signal to other signals. This has the effect
+of "forwarding" a signal: it is automatically emitted whenever the relevant signal is emitted. For
+example, the MouseArea \c onClicked handler in \c Button.qml above could have been replaced with
+a call to \c connect():
+
+\qml
+MouseArea {
+    anchors.fill: parent
+    Component.onCompleted: clicked.connect(item.buttonClicked)
+}
+\endqml
 
-Methods and signals may be added in the same way.
+Whenever the \l MouseArea \c clicked signal is emitted, the \c rect.buttonClicked signal will
+automatically be emitted as well.
 
-As all external methods, signals and properties are accessible to external
-users, developers should ensure that setting these properties does not have
-any undesirable side-effects.  For most resilience, root level properties should
-only be used for literal default values.  When a root level property must be
-used inside the component - such as the children property - property aliases
-can be used to redirect this property to a "safe" location for external users.
-Try to think of the root level properties as being "owned" by the components
-user, rather than the component itself.
 */
diff --git a/doc/src/declarative/javascriptblocks.qdoc b/doc/src/declarative/javascriptblocks.qdoc
index b6fad5b..16d0633 100644
--- a/doc/src/declarative/javascriptblocks.qdoc
+++ b/doc/src/declarative/javascriptblocks.qdoc
@@ -207,6 +207,25 @@ changes.
 See \l {Property Binding} for more information.
 
 
+\section1 Receiving QML Signals in JavaScript
+
+To receive a QML signal, use the signal's \c connect() method to connect it to a JavaScript
+function.
+
+For example, the following code connects the MouseArea \c clicked signal to the \c jsFunction()
+in \c script.js:
+
+\table
+\row
+\o \snippet doc/src/snippets/declarative/integrating-javascript/connectjs.qml 0
+\o \snippet doc/src/snippets/declarative/integrating-javascript/script.js 0
+\endtable
+
+The \c jsFunction() will now be called whenever MouseArea's \c clicked signal is emitted.
+
+See \l {Connecting signals to methods and other signals} for more information.
+
+
 \section1 QML JavaScript Restrictions
 
 QML executes standard JavaScript code, with the following restrictions:
diff --git a/doc/src/declarative/pics/qml-extending-types.png b/doc/src/declarative/pics/qml-extending-types.png
new file mode 100644
index 0000000..6990d7c
--- /dev/null
+++ b/doc/src/declarative/pics/qml-extending-types.png
diff --git a/doc/src/declarative/qtbinding.qdoc b/doc/src/declarative/qtbinding.qdoc
index c3ce6d0..71f41bc 100644
--- a/doc/src/declarative/qtbinding.qdoc
+++ b/doc/src/declarative/qtbinding.qdoc
@@ -230,7 +230,7 @@ Also see the QDeclarativeContext documentation for more information.
 
 \section2 Defining new QML elements
 
-While new QML elements can be \l {Defining new Components}{defined in QML}, they can also be
+While new QML elements can be \l {Defining New Components}{defined in QML}, they can also be
 defined by C++ classes; in fact, many of the core \l {QML Elements} are implemented through
 C++ classes. When you create a QML object using one of these elements, you are simply creating an
 instance of a QObject-based C++ class and setting its properties.
diff --git a/doc/src/declarative/tutorial.qdoc b/doc/src/declarative/tutorial.qdoc
index 8467478..d8139b4 100644
--- a/doc/src/declarative/tutorial.qdoc
+++ b/doc/src/declarative/tutorial.qdoc
@@ -124,7 +124,7 @@ Our color picker is made of six cells with different colors.
 To avoid writing the same code multiple times for each cell, we create a new \c Cell component.
 A component provides a way of defining a new type that we can re-use in other QML files.
 A QML component is like a black-box and interacts with the outside world through properties, signals and functions and is generally
-defined in its own QML file. (For more details, see \l {Defining new Components}).
+defined in its own QML file. (For more details, see \l {Defining New Components}).
 The component's filename must always start with a capital letter.
 
 Here is the QML code for \c Cell.qml:
@@ -144,7 +144,7 @@ An \l Item is the most basic visual element in QML and is often used as a contai
 
 We declare a \c cellColor property. This property is accessible from  \e outside our component, this allows us
 to instantiate the cells with different colors.
-This property is just an alias to an existing property - the color of the rectangle that compose the cell (see \l{Adding new properties}).
+This property is just an alias to an existing property - the color of the rectangle that compose the cell (see \l{Adding Properties}).
 
 \snippet examples/declarative/tutorials/helloworld/Cell.qml 5