doc/src/qtquick1/qmlevents.qdoc

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