doc/src/declarative/qmlevents.qdoc

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
   4 ** All rights reserved.
   5 ** Contact: Nokia Corporation (qt-info@nokia.com)
   6 **
   7 ** This file is part of the documentation of the Qt Toolkit.
   8 **
   9 ** $QT_BEGIN_LICENSE:FDL$
  10 ** No Commercial Usage
  11 ** This file contains pre-release code and may not be distributed.
  12 ** You may use this file in accordance with the terms and conditions
  13 ** contained in the Technology Preview License Agreement accompanying
  14 ** this package.
  15 **
  16 ** GNU Free Documentation License
  17 ** Alternatively, this file may be used under the terms of the GNU Free
  18 ** Documentation License version 1.3 as published by the Free Software
  19 ** Foundation and appearing in the file included in the packaging of this
  20 ** file.
  21 **
  22 ** If you have questions regarding the use of this file, please contact
  23 ** Nokia at qt-info@nokia.com.
  24 ** $QT_END_LICENSE$
  25 **
  26 ****************************************************************************/
  27
  28 /*!
  29 \page qmlevents.html
  30 \ingroup qml-features
  31 \contentspage QML Features
  32 \previouspage {Keyboard Focus in QML}{Keyboard Focus}
  33 \nextpage Importing Reusable Components
  34
  35 \title QML Signal and Handler Event System
  36
  37 QML utilizes Qt's \l{The Meta-Object System}{meta-object} and
  38 \l{Signals & Slots}{signals} systems. Signals and slots created using Qt in C++
  39 are inheritely valid in QML.
  40
  41 \keyword qml-signals-and-handlers
  42 \section1 Signals and Handlers
  43
  44 Signals provide a way to notify other objects when an event has occurred. For
  45 example, the MouseArea \c clicked signal notifies other objects that the mouse
  46 has been clicked within the area.
  47
  48 The syntax for defining a new signal is:
  49
  50 \tt{signal <name>[([<type> <parameter name>[, ...]])]}
  51
  52 Attempting to declare two signals or methods with the same name in the same type
  53 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.)
  54
  55 Here are various examples of signal declarations:
  56 \snippet doc/src/snippets/declarative/events.qml parent begin
  57 \snippet doc/src/snippets/declarative/events.qml signal declaration
  58 \snippet doc/src/snippets/declarative/events.qml parent end
  59
  60 If the signal has no parameters, the "\c{()}" brackets are optional. If
  61 parameters are used, the parameter types must be declared, as for the \c string
  62 and \c variant arguments of the \c perform signal.
  63
  64 Adding a signal to an item automatically adds a \e{signal handler} as well. The
  65 signal hander is named \c on<SignalName>, with the first letter of the signal in
  66 uppercase.  The previous signals have the following signal handlers:
  67 \snippet doc/src/snippets/declarative/events.qml signal handler declaration
  68
  69 Further, each QML properties have a \c{<property_name>Changed} signal and its
  70 corresponding \c{on<property_name>Changed} signal handler. As a result, property
  71 changes may notify other components for any changes.
  72 \snippet doc/src/snippets/declarative/events.qml automatic signals
  73
  74 To emit a signal, invoke it as a method. The signal handler binding is similar
  75 to a property binding and it is invoked when the signal is emitted. Use the
  76 defined argument names to access the respective arguments.
  77 \snippet doc/src/snippets/declarative/events.qml signal emit
  78 Note that the \c Component.onCompleted is an
  79 \l{attached-signalhandlers}{attached signal handler}; it is invoked when the
  80 \l Component initialization is complete.
  81
  82 \keyword qml-connect-signals-to-method
  83 \section2 Connecting Signals to Methods and Signals
  84
  85 Signal objects have a \c connect() method to a connect a signal either to a
  86 method or another signal. When a signal is connected to a method, the method is
  87 automatically invoked whenever the signal is emitted. (In Qt terminology, the
  88 method is a \e slot that is connected to the \e signal; all methods defined in
  89 QML are created as \l{Signals & Slots}{Qt slots}.) This enables a signal
  90 to be received by a method instead of a \l {Signal Handlers}{signal handler}.
  91
  92 \snippet doc/src/snippets/declarative/events.qml connect method
  93 The \c {connect()} method is appropriate when connecting a JavaScript method to
  94 a signal.
  95
  96 There is a corresponding \c disconnect() method for removing connected
  97 signals.
  98
  99 \section3 Signal to Signal Connect
 100
 101 By connecting signals to other signals, the \c connect() method can form different
 102 signal chains.
 103 \snippet doc/src/snippets/declarative/events.qml forward signal
 104
 105
 106 Whenever the \l MouseArea \c clicked signal is emitted, the \c send
 107 signal will automatically be emitted as well.
 108
 109 \code
 110 output:
 111     MouseArea clicked
 112     Send clicked
 113 \endcode
 114
 115 \section1 C++ Additions
 116
 117 Because QML uses Qt, a signal defined in C++ also works as a QML signal. The
 118 signal may be emitted in QML code or called as a method. In addition, the QML
 119 runtime automatically creates signal handlers for the C++ signals. For more
 120 signal control, the \c connect() method and the \l Connections element may connect
 121 a C++ signal to another signal or method.
 122
 123 For complete information on how to call C++ functions in QML, read the
 124 \l{Extending QML - Signal Support Example}.
 125
 126
 127 */