diff options
author | Olivier Goffart <olivier.goffart@nokia.com> | 2011-03-31 13:54:58 (GMT) |
---|---|---|
committer | Olivier Goffart <olivier.goffart@nokia.com> | 2011-03-31 13:54:58 (GMT) |
commit | 37feac98c573a099502fddfb5703c2359711b4c4 (patch) | |
tree | 33d74f9650065de4564bc0d749ca50bd65b13a2c /doc/src/declarative/qmlevents.qdoc | |
parent | 7b18baf23b1e8c663872b2b25b1323798b1d09df (diff) | |
parent | b764d3e6cb114988394e7500236ba087a3385a50 (diff) | |
download | Qt-37feac98c573a099502fddfb5703c2359711b4c4.zip Qt-37feac98c573a099502fddfb5703c2359711b4c4.tar.gz Qt-37feac98c573a099502fddfb5703c2359711b4c4.tar.bz2 |
Merge remote-tracking branch 'origin/4.7' into qt-master-from-4.7
Conflicts:
doc/src/declarative/example-slideswitch.qdoc
doc/src/development/qmake-manual.qdoc
doc/src/snippets/code/doc_src_qmake-manual.pro
doc/src/snippets/code/doc_src_qtscript.qdoc
src/corelib/animation/qabstractanimation.cpp
src/s60installs/bwins/QtOpenGLu.def
src/s60installs/eabi/QtOpenGLu.def
src/s60installs/eabi/QtOpenVGu.def
tests/auto/qdir/qdir.pro
tests/auto/qsslsocket/tst_qsslsocket.cpp
tools/qdoc3/doc/qdoc-manual.qdocconf
Diffstat (limited to 'doc/src/declarative/qmlevents.qdoc')
-rw-r--r-- | doc/src/declarative/qmlevents.qdoc | 127 |
1 files changed, 127 insertions, 0 deletions
diff --git a/doc/src/declarative/qmlevents.qdoc b/doc/src/declarative/qmlevents.qdoc new file mode 100644 index 0000000..566f71c --- /dev/null +++ b/doc/src/declarative/qmlevents.qdoc @@ -0,0 +1,127 @@ +/**************************************************************************** +** +** 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 qmlevents.html +\ingroup qml-features +\contentspage QML Features +\previouspage {Keyboard Focus in QML}{Keyboard Focus} +\nextpage Importing Reusable Components + +\title QML Signal and Handler Event System + +QML utilizes Qt's \l{The Meta-Object System}{meta-object} and +\l{Signals & Slots}{signals} systems. Signals and slots created using Qt in C++ +are inheritely valid in QML. + +\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 \e{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. (In Qt terminology, the +method is a \e slot that is connected to the \e signal; all methods defined in +QML are created as \l{Signals & Slots}{Qt slots}.) This 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 C++ Additions + +Because QML uses Qt, a signal defined in C++ also works as a QML signal. The +signal may be emitted in QML code or called as a method. In addition, the QML +runtime automatically creates signal handlers for the C++ signals. For more +signal control, the \c connect() method and the \l Connections element may connect +a C++ signal to another signal or method. + +For complete information on how to call C++ functions in QML, read the +\l{Extending QML - Signal Support Example}. + + +*/ |