qiurui
/
qtdeclarative
mirror of https://github.com/qt/qtdeclarative.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Doc: Use input handlers and controls wherever appropriate 

In addition, changed the \section titles to sentence case.

Change-Id: If62cc8f2a3f6a99123ccfb4d030d3f58a2fe8dea
Reviewed-by: Mitch Curtis <mitch.curtis@qt.io>
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
This commit is contained in:
Venugopal Shivashankar 2018-10-17 11:48:32 +02:00 committed by Jani Heikkinen
parent adacda1752
commit fd3cf7a45a
3 changed files with 199 additions and 198 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

9
src/qml/doc/snippets/qml/integrating-javascript/connectjs.qml
View File

@ -48,20 +48,19 @@
**
****************************************************************************/
//![0]
import QtQuick 2.0
import QtQuick 2.12
import "script.js" as MyScript
Item {
id: item
width: 200; height: 200
MouseArea {
id: mouseArea
anchors.fill: parent
TapHandler {
id: inputHandler
}
Component.onCompleted: {
mouseArea.clicked.connect(MyScript.jsFunction)
inputHandler.tapped.connect(MyScript.jsFunction)
}
}
//![0]

215
src/qml/doc/src/javascript/expressions.qdoc
View File

@ -32,15 +32,15 @@
The \l{JavaScript Host Environment} provided by QML can run valid standard
JavaScript constructs such as conditional operators, arrays, variable setting,
loops. In addition to the standard JavaScript properties, the \l {QML Global
and loops. In addition to the standard JavaScript properties, the \l {QML Global
Object} includes a number of helper methods that simplify building UIs and
interacting with the QML environment.
The JavaScript environment provided by QML is stricter than that in a web
browser. For example, in QML you cannot add to, or modify, members of the
JavaScript global object. In regular JavaScript, it is possible to do this
browser. For example, in QML you cannot add to, or modify, members of the
JavaScript global object. In regular JavaScript, it is possible to do this
accidentally by using a variable without declaring it. In QML this will throw
an exception, so all local variables must be explicitly declared. See
an exception, so all local variables must be explicitly declared. See
\l{JavaScript Environment Restrictions} for a complete description of the
restrictions on JavaScript code executed from QML.
@ -49,7 +49,7 @@ Various parts of \l{QML Documents}{QML documents} can contain JavaScript code:
\list 1
\li The body of \l{Property Binding}{property bindings}. These JavaScript
expressions describe relationships between QML object \l{Property Attributes}
{properties}. When any of a property's \e dependencies change, the property
{properties}. When \e dependencies of a property change, the property
is automatically updated too, according to the specified relationship.
\li The body of \l{Signal Attributes}{Signal handlers}. These JavaScript
statements are automatically evaluated whenever a QML object emits the
@ -66,42 +66,41 @@ Various parts of \l{QML Documents}{QML documents} can contain JavaScript code:
\section1 JavaScript in Property Bindings
\section1 JavaScript in property bindings
In the following example, the \l Rectangle's \c color depends on the
\l MouseArea's \c pressed property. This relationship is described using a
In the following example, the \c color property of \l Rectangle depends on the
\c pressed property of \l TapHandler. This relationship is described using a
conditional expression:
\qml
import QtQuick 2.0
import QtQuick 2.12
Rectangle {
id: colorbutton
width: 200; height: 80;
color: mousearea.pressed ? "steelblue" : "lightsteelblue"
color: inputHandler.pressed ? "steelblue" : "lightsteelblue"
MouseArea {
id: mousearea
anchors.fill: parent
TapHandler {
id: inputHandler
}
}
\endqml
In fact, any JavaScript expression (no matter how complex) may be used in a
property binding definition, as long as the result of the expression is a
value whose type can be assigned to the property. This includes side effects.
value whose type can be assigned to the property. This includes side effects.
However, complex bindings and side effects are discouraged because they can
reduce the performance, readability, and maintainability of the code.
There are two ways to define a property binding: the first (and most common)
is, as previously shown, in a \l{QML Object Attributes#Value Assignment on Initialization}
{property initialization}. The second (and much rarer) way is to assign the
There are two ways to define a property binding: the most common one
is shown in the example earlier, in a \l{QML Object Attributes#Value Assignment on Initialization}
{property initialization}. The second (and much rarer) way is to assign the
property a function returned from the \l{Qt::binding()}{Qt.binding()} function,
from within imperative JavaScript code, as shown below:
\qml
import QtQuick 2.0
import QtQuick 2.12
Rectangle {
id: colorbutton
@ -109,13 +108,12 @@ Rectangle {
color: "red"
MouseArea {
id: mousearea
anchors.fill: parent
TapHandler {
id: inputHandler
}
Component.onCompleted: {
color = Qt.binding(function() { return mousearea.pressed ? "steelblue" : "lightsteelblue" });
color = Qt.binding(function() { return inputHandler.pressed ? "steelblue" : "lightsteelblue" });
}
}
\endqml
@ -126,126 +124,111 @@ about \l{qml-javascript-assignment}
{Property Assignment versus Property Binding} for information about how
bindings differ from value assignments.
\section1 JavaScript in Signal Handlers
\section1 JavaScript in signal handlers
QML object types can emit signals in reaction to certain events occurring.
Those signals can be handled by signal handler functions, which can be defined
by clients to implement custom program logic.
Suppose that a button represented by a Rectangle type has a MouseArea and a
Text label. The MouseArea will emit its \l{MouseArea::}{pressed} signal when the
user presses the defined interactive area, which will automatically trigger the
\c onPressed handler, which can be defined by clients. The QML
engine will execute the JavaScript expressions defined in the \c onPressed and
\c onReleased handlers, as required. Typically, a signal handler is bound to
JavaScript expressions to initiate other events or to simply assign property
Suppose that a button represented by a Rectangle type has a TapHandler and a
Text label. The TapHandler emits its \l{TapHandler::}{tapped} signal when the
user presses the button. The clients can react to the signal in the \c onTapped
handler using JavaScript expressions. The QML engine executes these JavaScript
expressions defined in the handler as required. Typically, a signal handler is
bound to JavaScript expressions to initiate other events or to assign property
values.
\qml
import QtQuick 2.0
import QtQuick 2.12
Rectangle {
id: button
width: 200; height: 80; color: "lightsteelblue"
MouseArea {
id: mousearea
anchors.fill: parent
onPressed: {
TapHandler {
id: inputHandler
onTapped: {
// arbitrary JavaScript expression
label.text = "I am Pressed!"
console.log("Tapped!")
}
onReleased: {
// arbitrary JavaScript expression
label.text = "Click Me!"
}
}
Text {
id: label
anchors.centerIn: parent
text: "Press Me!"
text: inputHandler.pressed ? "Pressed!" : "Press here!"
}
}
\endqml
Please see the \l{Signal and Handler Event System} documentation for in-depth
discussion of signals and signal handlers, and see the
\l{QML Object Attributes} documentation for in-depth discussion of how
to define the implementation of signal handlers in QML with JavaScript.
For more details about signals and signal handlers, refer to the following
topics:
\list
\li \l{Signal and Handler Event System}
\li \l{QML Object Attributes}
\endlist
\section1 JavaScript in standalone functions
\section1 JavaScript in Standalone Functions
Program logic can also be defined in JavaScript functions. These functions can
Program logic can also be defined in JavaScript functions. These functions can
be defined inline in QML documents (as custom methods) or externally in
imported JavaScript files.
\section2 JavaScript in Custom Object Methods
\section2 JavaScript in custom methods
Custom methods can be defined in QML documents and may be called from signal
handlers, property bindings, or functions in other QML objects. Methods
defined in this way are often referred to as \e{inline JavaScript functions}
because their implementation is included in the QML object type definition
(QML document), as opposed to an external JavaScript file.
handlers, property bindings, or functions in other QML objects. Such methods
are often referred to as \e{inline JavaScript functions} because their
implementation is included in the QML object type definition
(QML document), instead of in an external JavaScript file.
An example of an inline custom method is as follows:
\qml
import QtQuick 2.0
import QtQuick 2.12
Item {
function factorial(a) {
a = parseInt(a);
if (a <= 0)
return 1;
else
return a * factorial(a - 1);
}
function fibonacci(n){
var arr = [0, 1];
for (var i = 2; i < n + 1; i++)
arr.push(arr[i - 2] + arr[i -1]);
MouseArea {
anchors.fill: parent
onClicked: console.log(factorial(10))
return arr;
}
TapHandler {
onTapped: console.log(fibonacci(10))
}
}
\endqml
The factorial function will run whenever the MouseArea detects a \c clicked signal.
The fibonacci function is run whenever the TapHandler emits a \c tapped signal.
Importantly, custom methods defined inline in a QML document are exposed to
\note The custom methods defined inline in a QML document are exposed to
other objects, and therefore inline functions on the root object in a QML
component can be invoked by callers outside the component. If this is not
component can be invoked by callers outside the component. If this is not
desired, the method can be added to a non-root object or, preferably, written
in an external JavaScript file.
See the \l{QML Object Attributes} documentation for in-depth discussion of how
to define custom methods in QML with JavaScript code implementations.
See the \l{QML Object Attributes} documentation for more information on
defining custom methods in QML using JavaScript.
\section2 Functions defined in a JavaScript file
Non-trivial program logic is best separated into a separate JavaScript file.
This file can be imported into QML using an \c import statement, like the
QML \l {QML Modules}{modules}.
\section2 Functions in Imported JavaScript Files
Non-trivial program logic is best separated into external JavaScript files.
These files can be imported into QML files using an \c import statement, in
the same way that \l {QML Modules}{modules} are imported.
For example, the \c {factorial()} method in the above example could be moved
into an external file named \c factorial.js, and accessed like this:
For example, the \c {fibonacci()} method in the earlier example could be moved
into an external file named \c fib.js, and accessed like this:
\qml
import "factorial.js" as MathFunctions
import QtQuick 2.12
import "fib.js" as MathFunctions
Item {
MouseArea {
anchors.fill: parent
onClicked: console.log(MathFunctions.factorial(10))
TapHandler {
onTapped: console.log(MathFunctions.fibonacci(10))
}
}
\endqml
@ -253,20 +236,18 @@ Item {
For more information about loading external JavaScript files into QML, read
the section about \l{Importing JavaScript Resources in QML}.
\section2 Connecting signals to JavaScript functions
\section2 Connecting Signals to JavaScript Functions
QML object types which emit signals also provide default signal handlers for
their signals, as described in a previous section. Sometimes, however, a
client will want to cause a signal emitted from one object to trigger a
function defined in another object; and in that case, a signal connection
is often preferable.
QML object types that emit signals also provide default signal handlers for
their signals, as described in the \l{JavaScript in signal handlers}{previous}
section. Sometimes, however, a client wants to trigger a function defined in a
QML object when another QML object emits a signal. Such scenarios can be handled
by a signal connection.
A signal emitted by a QML object may be connected to a JavaScript function
by calling the signal's \c connect() method and passing the JavaScript function
as an argument. For example, the following code connects the MouseArea
\c clicked signal to the \c jsFunction() in \c script.js:
as an argument. For example, the following code connects the TapHandler's
\c tapped signal to the \c jsFunction() in \c script.js:
\table
\row
@ -274,34 +255,30 @@ as an argument. For example, the following code connects the MouseArea
\li \snippet qml/integrating-javascript/script.js 0
\endtable
The \c jsFunction() will now be called whenever MouseArea's \c clicked signal
The \c jsFunction() is called whenever the TapHandler's \c tapped signal
is emitted.
See \l{qtqml-syntax-signals.html}
{Connecting Signals to Methods and Signals} for more information.
\section1 JavaScript in Application Startup Code
\section1 JavaScript in application startup code
It is occasionally necessary to run some imperative code at application (or
component instance) startup. While it is tempting to just include the startup
component instance) startup. While it is tempting to just include the startup
script as \e {global code} in an external script file, this can have severe
limitations as the QML environment may not have been fully established. For
limitations as the QML environment may not have been fully established. For
example, some objects might not have been created or some
\l {Property Binding}{property bindings} may not have been established. See
\l {JavaScript Environment Restrictions} for the exact limitations of global
script code.
A QML object will emit the \c{Component.completed} \l{Signal and Handler Event
A QML object emits the \c{Component.completed} \l{Signal and Handler Event
System#Attached Signal Handlers}{attached signal} when its instantiation is
complete. JavaScript code in the corresponding \c{Component.onCompleted} handler
runs after the object is instantiated. Thus, the best place to write application
startup code is in the \c{Component.onCompleted} handler of the top-level
object, because this object emits \c{Component.completed} when the QML environment
is fully established.
complete. The JavaScript code in the corresponding \c{Component.onCompleted}
handler runs after the object is instantiated. Thus, the best place to write
application startup code is in the \c{Component.onCompleted} handler of the
top-level object, because this object emits \c{Component.completed} when the
QML environment is fully established.
For example:
@ -318,11 +295,11 @@ Rectangle {
\endqml
Any object in a QML file - including nested objects and nested QML component
instances - can use this attached property. If there is more than one
instances - can use this attached property. If there is more than one
\c onCompleted() handler to execute at startup, they are run sequentially in
an undefined order.
Likewise, every \c Component will emit a \l {Component::destruction}{destruction()}
Likewise, every \c Component emits a \l {Component::destruction}{destruction()}
signal just before being destroyed.
*/
@ -341,7 +318,7 @@ signal just before being destroyed.
\section1 Scarce Resources in JavaScript
As described in the documentation for \l{QML Basic Types}, a \c var type
property may hold a \e{scarce resource} (image or pixmap). There are several
property may hold a \e{scarce resource} (image or pixmap). There are several
important semantics of scarce resources which should be noted:
\list
@ -351,7 +328,7 @@ important semantics of scarce resources which should be noted:
\endlist
In most cases, allowing the engine to automatically release the resource is
the correct choice. In some cases, however, this may result in an invalid
the correct choice. In some cases, however, this may result in an invalid
variant being returned from a function in JavaScript, and in those cases it
may be necessary for clients to manually preserve or destroy resources for
themselves.
@ -364,9 +341,9 @@ and that we have registered it with the QML type-system as follows:
\snippet qml/integrating-javascript/scarceresources/avatarExample.cpp 0
The AvatarExample class has a property which is a pixmap. When the property
The AvatarExample class has a property which is a pixmap. When the property
is accessed in JavaScript scope, a copy of the resource will be created and
stored in a JavaScript object which can then be used within JavaScript. This
stored in a JavaScript object which can then be used within JavaScript. This
copy will take up valuable system resources, and so by default the scarce
resource copy in the JavaScript object will be released automatically by the
declarative engine once evaluation of the JavaScript expression is complete,
@ -414,7 +391,7 @@ Run it in C++:
\section2 Example Four: Explicit Destruction
In the following example, we release (via destroy()) an explicitly preserved
scarce resource variant. This example shows how a client may free system
scarce resource variant. This example shows how a client may free system
resources by releasing the scarce resource held in a JavaScript object, if
required, during evaluation of a JavaScript expression.
@ -430,7 +407,7 @@ Run it in C++:
\section2 Example Five: Explicit Destruction and JavaScript References
One thing to be aware of when using "var" type properties is that they
hold references to JavaScript objects. As such, if multiple references
hold references to JavaScript objects. As such, if multiple references
to one scarce resource is held, and the client calls destroy() on one
of those references (to explicitly release the scarce resource), all of
the references will be affected.

173
src/qml/doc/src/qmllanguageref/syntax/signals.qdoc
View File

@ -39,25 +39,38 @@ application may need to relay this clicking event to other applications.
QML has a signal and handler mechanism, where the \e signal is the event
and the signal is responded to through a \e {signal handler}. When a signal
is emitted, the corresponding signal handler is invoked. Placing logic such as scripts or other
operations in the handler allows the component to respond to the event.
is emitted, the corresponding signal handler is invoked. Placing logic such as
a script or other operations in the handler allows the component to respond to
the event.
\target qml-signals-and-handlers
\section1 Receiving Signals with Signal Handlers
\section1 Receiving signals with signal handlers
To receive a notification when a particular signal is emitted for a particular object, the object definition should declare a signal handler named \e on<Signal> where \e <Signal> is the name of the signal, with the first letter capitalized. The signal handler should contain the JavaScript code to be executed when the signal handler is invoked.
To receive a notification when a particular signal is emitted for a particular
object, the object definition should declare a signal handler named
\e on<Signal>, where \e <Signal> is the name of the signal, with the first
letter capitalized. The signal handler should contain the JavaScript code to be
executed when the signal handler is invoked.
For example, the \l MouseArea type from the \c QtQuick module has a \c clicked signal that is emitted whenever the mouse is clicked within the area. Since the signal name is \c clicked, the signal handler for receiving this signal should be named \c onClicked. In the example below, whenever the mouse area is clicked, the \c onClicked handler is invoked, applying a random color to the \l Rectangle:
For example, the \l [QtQuick.Controls2]{Button} type from the
\l{Qt Quick Controls 2}{Qt Quick Controls} module has a \c clicked signal, which
is emitted whenever the button is clicked. In this case, the signal handler for
receiving this signal should be \c onClicked. In the example below, whenever
the button is clicked, the \c onClicked handler is invoked, applying a random
color to the parent \l Rectangle:
\qml
import QtQuick 2.0
import QtQuick 2.\QtMinorVersion
import QtQuick.Controls 2.\QtMinorVersion
Rectangle {
id: rect
width: 100; height: 100
width: 250; height: 250
MouseArea {
anchors.fill: parent
Button {
anchors.bottom: parent.bottom
anchors.horizontalCenter: parent.horizontalCenter
text: "Change color!"
onClicked: {
rect.color = Qt.rgba(Math.random(), Math.random(), Math.random(), 1);
}
@ -65,73 +78,61 @@ Rectangle {
}
\endqml
Looking at the \l MouseArea documentation, you can see the \l {MouseArea::}{clicked} signal is emitted with a parameter named \c mouse which is a \l MouseEvent object that contains further details about the mouse click event. This name can be referred to in our \c onClicked handler to access this parameter. For example, the \l MouseEvent type has \c x and \c y coordinates that allows us to print out the exact location where the mouse was clicked:
\section2 Property change signal handlers
\qml
import QtQuick 2.0
Rectangle {
id: rect
width: 100; height: 100
MouseArea {
anchors.fill: parent
onClicked: {
rect.color = Qt.rgba(Math.random(), Math.random(), Math.random(), 1);
// access 'mouse' parameter
console.log("Clicked mouse at", mouse.x, mouse.y)
}
}
}
\endqml
\section2 Property Change Signal Handlers
A signal is automatically emitted when the value of a QML property changes. This type of signal is a \e {property change signal} and signal handlers for these signals are written in the form \e on<Property>Changed where \e <Property> is the name of the property, with the first letter capitalized.
A signal is automatically emitted when the value of a QML property changes.
This type of signal is a \e {property change signal} and signal handlers for
these signals are written in the form \e on<Property>Changed, where
\e <Property> is the name of the property, with the first letter capitalized.
For example, the \l MouseArea type has a \l {MouseArea::pressed}{pressed} property. To receive a notification whenever this property changes, write a signal handler named \c onPressedChanged:
\qml
import QtQuick 2.0
import QtQuick 2.\QtMinorVersion
Rectangle {
id: rect
width: 100; height: 100
MouseArea {
anchors.fill: parent
onPressedChanged: {
console.log("Mouse area is pressed?", pressed)
}
TapHandler {
onPressedChanged: console.log("taphandler pressed?", pressed)
}
}
\endqml
Even though the \l MouseArea documentation does not document a signal handler named \c onPressedChanged, the signal is implicitly provided by the fact that the \c pressed property exists.
Even though the \l TapHandler documentation does not document a signal handler
named \c onPressedChanged, the signal is implicitly provided by the fact that
the \c pressed property exists.
\section2 Using the Connections type
\section2 Using the Connections Type
In some cases it may be desirable to access a signal outside of the object that
emits it. For these purposes, the \c QtQuick module provides the \l Connections
type for connecting to signals of arbitrary objects. A \l Connections object
can receive any signal from its specified \l {Connections::target}{target}.
In some cases it may be desirable to access a signal outside of the object that emits it. For these purposes, the \c QtQuick module provides the \l Connections type for connecting to signals of arbitrary objects. A \l Connections object can receive any signal from its specified \l {Connections::target}{target}.
For example, the \c onClicked handler in the earlier example could have been received by the root \l Rectangle instead, by placing the \c onClicked handler in a \l Connections object that has its \l {Connections::target}{target} set to the \l MouseArea:
For example, the \c onClicked handler in the earlier example could have been
received by the root \l Rectangle instead, by placing the \c onClicked handler
in a \l Connections object that has its \l {Connections::target}{target} set to
the \c button:
\qml
import QtQuick 2.0
import QtQuick 2.\QtMinorVersion
import QtQuick.Controls 2.\QtMinorVersion
Rectangle {
id: rect
width: 100; height: 100
width: 250; height: 250
MouseArea {
id: mouseArea
anchors.fill: parent
Button {
id: button
anchors.bottom: parent.bottom
anchors.horizontalCenter: parent.horizontalCenter
text: "Change color!"
}
Connections {
target: mouseArea
target: button
onClicked: {
rect.color = Qt.rgba(Math.random(), Math.random(), Math.random(), 1);
}
@ -140,16 +141,18 @@ Rectangle {
\endqml
\section2 Attached Signal Handlers
\section2 Attached signal handlers
An \l {Attached Properties and Attached Signal Handlers}{attached signal handler} is a signal handler that receives a signal from an \e {attaching type} rather than the object within which the handler is declared.
An \l {Attached Properties and Attached Signal Handlers}{attached signal handler}
receives a signal from an \e {attaching type} rather than the object within which
the handler is declared.
For example, \l{Component::completed}{Component.onCompleted} is an attached
signal handler. This handler is often used to execute some JavaScript code when
its creation process has been completed, as in the example below:
signal handler. It is often used to execute some JavaScript code when its
creation process is complete. Here is an example:
\qml
import QtQuick 2.0
import QtQuick 2.\QtMinorVersion
Rectangle {
width: 200; height: 200
@ -161,14 +164,23 @@ Rectangle {
}
\endqml
The \c onCompleted handler is not responding to some \c completed signal from the \l Rectangle type. Instead, an object of the \c Component \e {attaching type} with a \c completed signal has automatically been \e attached to the \l Rectangle object by the QML engine, and the engine emits this signal when the object is fully created, thus triggering the \c Component.onCompleted signal handler.
The \c onCompleted handler is not responding to a \c completed signal from
the \l Rectangle type. Instead, an object of the \c Component \e{attaching type}
with a \c completed signal has automatically been \e attached to the \l Rectangle
object by the QML engine. The engine emits this signal when the Rectangle object is
created, thus triggering the \c Component.onCompleted signal handler.
Attached signal handlers allow objects to be notified of particular signals that are significant to each individual object. If there was no \c Component.onCompleted attached signal handler, for example, then an object could not receive this notification without registering for some special signal from some special object. The \e {attached signal handler} mechanism enables objects to receive particular signals without these extra processes.
Attached signal handlers allow objects to be notified of particular signals that are
significant to each individual object. If there was no \c Component.onCompleted
attached signal handler, for example, an object could not receive this notification
without registering for some special signal from some special object.
The \e {attached signal handler} mechanism enables objects to receive particular
signals without extra code.
See \l {Attached properties and attached signal handlers} for more information on attached signal handlers.
See \l {Attached properties and attached signal handlers} for more information on
attached signal handlers.
\section1 Adding Signals to Custom QML Types
\section1 Adding signals to custom QML types
Signals can be added to custom QML types through the \c signal keyword.
@ -178,21 +190,27 @@ The syntax for defining a new signal is:
A signal is emitted by invoking the signal as a method.
For example, say the code below is defined in a file named \c SquareButton.qml. The root \l Rectangle object has an \c activated signal. When the child \l MouseArea is clicked, it emits the parent's \c activated signal with the coordinates of the mouse click:
For example, the code below is defined in a file named \c SquareButton.qml. The
root \l Rectangle object has an \c activated signal, which is emitted whenever the
child \l TapHandler is \c tapped. In this particular example the activated signal
is emitted with the x and y coordinates of the mouse click:
\qml
// SquareButton.qml
import QtQuick 2.\QtMinorVersion
Rectangle {
id: root
signal activated(real xPosition, real yPosition)
property point mouseXY
property int side: 100
width: side; height: side
MouseArea {
anchors.fill: parent
onPressed: root.activated(mouse.x, mouse.y)
TapHandler {
id: handler
onTapped: root.activated(mouseXY.x, mouseXY.y)
onPressedChanged: mouseXY = handler.point.position
}
}
\endqml
@ -210,7 +228,7 @@ See \l {Signal Attributes} for more details on writing signals for custom QML ty
\target qml-connect-signals-to-method
\section1 Connecting Signals to Methods and Signals
\section1 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
@ -220,6 +238,8 @@ signal to be received by a method instead of a signal handler.
Below, the \c messageReceived signal is connected to three methods using the \c connect() method:
\qml
import QtQuick 2.\QtMinorVersion
Rectangle {
id: relay
@ -244,7 +264,12 @@ Rectangle {
}
\endqml
In many cases it is sufficient to receive signals through signal handlers rather than using the connect() function. However, using the \c connect method allows a signal to be received by multiple methods as shown above, which would not be possible with signal handlers as they must be uniquely named. Also, the \c connect method is useful when connecting signals to \l {Dynamic QML Object Creation from JavaScript}{dynamically created objects}.
In many cases it is sufficient to receive signals through signal handlers
rather than using the connect() function. However, using the \c connect
method allows a signal to be received by multiple methods as shown earlier,
which would not be possible with signal handlers as they must be uniquely
named. Also, the \c connect method is useful when connecting signals to
\l {Dynamic QML Object Creation from JavaScript}{dynamically created objects}.
There is a corresponding \c disconnect() method for removing connected signals:
@ -259,12 +284,14 @@ Rectangle {
}
\endqml
\section3 Signal to Signal Connect
\section3 Signal to signal connect
By connecting signals to other signals, the \c connect() method can form different
signal chains.
\qml
import QtQuick 2.\QtMinorVersion
Rectangle {
id: forwarder
width: 100; height: 100
@ -272,20 +299,20 @@ Rectangle {
signal send()
onSend: console.log("Send clicked")
MouseArea {
TapHandler {
id: mousearea
anchors.fill: parent
onClicked: console.log("MouseArea clicked")
onTapped: console.log("Mouse clicked")
}
Component.onCompleted: {
mousearea.clicked.connect(send)
mousearea.tapped.connect(send)
}
}
\endqml
Whenever the \l MouseArea \c clicked signal is emitted, the \c send
Whenever the \l TapHandler's \c tapped signal is emitted, the \c send
signal will automatically be emitted as well.
\code
@ -293,6 +320,4 @@ output:
MouseArea clicked
Send clicked
\endcode
*/