diff options
Diffstat (limited to 'src/qml/doc/src/javascript/expressions.qdoc')
| -rw-r--r-- | src/qml/doc/src/javascript/expressions.qdoc | 215 |
1 files changed, 96 insertions, 119 deletions
diff --git a/src/qml/doc/src/javascript/expressions.qdoc b/src/qml/doc/src/javascript/expressions.qdoc index e80016cb67..b83127389a 100644 --- a/src/qml/doc/src/javascript/expressions.qdoc +++ b/src/qml/doc/src/javascript/expressions.qdoc @@ -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 in Imported JavaScript Files +\section2 Functions defined in a JavaScript file -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. +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}. -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. |