diff options
author | Mitch Curtis <mitch.curtis@qt.io> | 2016-08-05 12:33:03 +0200 |
---|---|---|
committer | Mitch Curtis <mitch.curtis@qt.io> | 2016-08-08 09:43:16 +0000 |
commit | 13a427475d3638de843f33145378587037841a86 (patch) | |
tree | b649b5cfccc89f79c184b7ee2fc93bef1861ac1e /src/qml | |
parent | 68bfc9332cd65c1eb88d1ec87164447b0db43237 (diff) |
Clarify doc on modification of the global object in JS imported by QML
Currently, reading the documentation for modification of the global
object in JavaScript can be confusing.
http://doc.qt.io/qt-5/qtqml-javascript-hostenvironment.html says:
JavaScript code cannot modify the global object.
In QML, the global object is constant - existing properties cannot
be modified or deleted, and no new properties may be created.
...
Any attempt to modify the global object - either implicitly or
explicitly - will cause an exception. If uncaught, this will result
in a warning being printed, that includes the file and line number
of the offending code.
http://doc.qt.io/qt-5/qjsengine.html#globalObject says:
Returns this engine's Global Object.
By default, the Global Object contains the built-in objects that
are part of ECMA-262, such as Math, Date and String. Additionally,
you can set properties of the Global Object to make your own
extensions available to all script code. Non-local variables in
script code will be created as properties of the Global Object, as
well as local variables in global code.
If QQmlEngine "is-a" QJSEngine, and QJSEngine can have its global object
modified, it might seem reasonable to expect that imported JavaScript
code should be able to modify the global object.
This patch aims to be more explicit about the restrictions and give
examples of how libraries should expose their APIs correctly for use by
QML code.
Change-Id: I11beb894a88d52038be90ffe6baa9337943810db
Reviewed-by: Simon Hausmann <simon.hausmann@qt.io>
Diffstat (limited to 'src/qml')
-rw-r--r-- | src/qml/doc/src/javascript/hostenvironment.qdoc | 5 |
1 files changed, 4 insertions, 1 deletions
diff --git a/src/qml/doc/src/javascript/hostenvironment.qdoc b/src/qml/doc/src/javascript/hostenvironment.qdoc index de8b967d72..1e33f2f641 100644 --- a/src/qml/doc/src/javascript/hostenvironment.qdoc +++ b/src/qml/doc/src/javascript/hostenvironment.qdoc @@ -80,7 +80,10 @@ Note that QML makes the following modifications to native objects: QML implements the following restrictions for JavaScript code: \list -\li JavaScript code cannot modify the global object. +\li JavaScript code written in a \c .qml file cannot modify the global object. + JavaScript code in a .js file can modify the global object, + and those modifications will be visible to the .qml file when + \l {Importing a JavaScript Resource from a QML Document}{imported}. In QML, the global object is constant - existing properties cannot be modified or deleted, and no new properties may be created. |