1 files changed, 130 insertions, 0 deletions
diff --git a/doc/src/qml/qmlevents.qdoc b/doc/src/qml/qmlevents.qdoc
new file mode 100644
index 0000000000..f29b2f260b
--- /dev/null
+++ b/doc/src/qml/qmlevents.qdoc
@@ -0,0 +1,130 @@
+/****************************************************************************
+**
+** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** 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.
+**
+** Other Usage
+** Alternatively, this file may be used in accordance with the terms
+** and conditions contained in a signed written agreement between you
+** and Nokia.
+**
+**
+**
+**
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+\page qmlevents.html
+\ingroup qml-features
+
+\title QML Signal and Handler Event System
+\brief the event sytem in QML
+
+Application and user interface components communicate with each other. For
+example, a button component needs to know that the user is clicking on it.
+The button may change colors to indicate its state or perform some logic. As
+well, application needs to know whether the user is clicking the button. The
+application may need to relay this clicking event to other applications.
+
+QML has a signal and handler mechanism, where the \i signal is the event
+and the component responds to the event through the \i handler. The signal
+is emitted and the handler is invoked. Placing logic such as scripts or other
+operations in the handler allows the component to respond to the event.
+
+\keyword qml-signals-and-handlers
+\section1 Signals and Handlers
+
+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:
+
+\tt{signal <name>[([<type> <parameter name>[, ...]])]}
+
+Attempting to declare two signals or methods with the same name in the same type
+block generates 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.)
+
+Here are various examples of signal declarations:
+\snippet doc/src/snippets/declarative/events.qml parent begin
+\snippet doc/src/snippets/declarative/events.qml signal declaration
+\snippet doc/src/snippets/declarative/events.qml parent end
+
+If the signal has no parameters, the "\c{()}" brackets are optional. If
+parameters are used, the parameter types must be declared, as for the \c string
+and \c variant arguments of the \c perform signal.
+
+Adding a signal to an item automatically adds a \i{signal handler} as well. The
+signal hander is named \c on<SignalName>, with the first letter of the signal in
+uppercase.  The previous signals have the following signal handlers:
+\snippet doc/src/snippets/declarative/events.qml signal handler declaration
+
+Further, each QML properties have a \c{<property_name>Changed} signal and its
+corresponding \c{on<property_name>Changed} signal handler. As a result, property
+changes may notify other components for any changes.
+\snippet doc/src/snippets/declarative/events.qml automatic signals
+
+To emit a signal, invoke it as a method. The signal handler binding is similar
+to a property binding and it is invoked when the signal is emitted. Use the
+defined argument names to access the respective arguments.
+\snippet doc/src/snippets/declarative/events.qml signal emit
+Note that the \c Component.onCompleted is an
+\l{attached-signalhandlers}{attached signal handler}; it is invoked when the
+\l Component initialization is complete.
+
+\keyword qml-connect-signals-to-method
+\section2 Connecting Signals to Methods and Signals
+
+Signal objects have a \c connect() method to a connect a signal either to a
+method or another signal. When a signal is connected to a method, the method is
+automatically invoked whenever the signal is emitted. This mechanism enables a
+signal to be received by a method instead of a
+\l {Signal Handlers}{signal handler}.
+
+\snippet doc/src/snippets/declarative/events.qml connect method
+The \c {connect()} method is appropriate when connecting a JavaScript method to
+a signal.
+
+There is a corresponding \c disconnect() method for removing connected
+signals.
+
+\section3 Signal to Signal Connect
+
+By connecting signals to other signals, the \c connect() method can form different
+signal chains.
+\snippet doc/src/snippets/declarative/events.qml forward signal
+
+
+Whenever the \l MouseArea \c clicked signal is emitted, the \c send
+signal will automatically be emitted as well.
+
+\code
+output:
+    MouseArea clicked
+    Send clicked
+\endcode
+
+\section1 Events from the Declarative Runtime
+
+There maybe cases where a signal comes from the \l{The QML Engine}{declarative
+runtime}. For example, it is possible to receive events from \l{QML Plugins}{QML
+plugins}. For more signal control, the \c connect() method and the \l
+Connections element may connect a signal from the runtime to another signal or
+method.
+
+For complete information on events from the runtime or creating signals from the
+runtime, read the \l{The QML Engine} and the \l{Creating QML Types} articles.
+
+*/