aboutsummaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
authorMichael Brasser <michael.brasser@nokia.com>2011-10-26 13:41:41 +1000
committerQt by Nokia <qt-info@nokia.com>2012-04-12 06:53:11 +0200
commit3787a0813e3b3408456546e46ac679fd44bc9149 (patch)
treec61e027b7346b598a6d7caced944389b910fe1a9 /doc
parent52b16a50de200d1af5b60352f7a783bc349c7d0a (diff)
Begin documenting QML's JS environment.
Provide a basic overview of QML's JavaScript host environment that can be expanded as needed. Change-Id: I1f178a9de26bd3ea6f5707821518419f76ab279d Reviewed-by: Alan Alpert <alan.alpert@nokia.com>
Diffstat (limited to 'doc')
-rw-r--r--doc/src/qml/external-resources.qdoc3
-rw-r--r--doc/src/qml/hostenvironment.qdoc92
-rw-r--r--doc/src/qml/qmlengine.qdoc10
-rw-r--r--doc/src/qml/qmli18n.qdoc4
4 files changed, 104 insertions, 5 deletions
diff --git a/doc/src/qml/external-resources.qdoc b/doc/src/qml/external-resources.qdoc
index b4aecbad75..386992f439 100644
--- a/doc/src/qml/external-resources.qdoc
+++ b/doc/src/qml/external-resources.qdoc
@@ -28,5 +28,8 @@
/*!
\externalpage http://www.ecma-international.org/publications/standards/Ecma-262.htm
\title ECMA-262
+
+ \externalpage http://www.w3schools.com/jsref/default.asp
+ \title W3Schools JavaScript Reference
*/
diff --git a/doc/src/qml/hostenvironment.qdoc b/doc/src/qml/hostenvironment.qdoc
new file mode 100644
index 0000000000..b0d9118944
--- /dev/null
+++ b/doc/src/qml/hostenvironment.qdoc
@@ -0,0 +1,92 @@
+/****************************************************************************
+**
+** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** GNU Free Documentation License
+** Alternatively, this file may be used under the terms of the GNU Free
+** Documentation License version 1.3 as published by the Free Software
+** Foundation and appearing in the file included in the packaging of
+** this file.
+**
+** Other Usage
+** Alternatively, this file may be used in accordance with the terms
+** and conditions contained in a signed written agreement between you
+** and Nokia.
+**
+**
+**
+**
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+\page qmlhostenvironment.html
+\title QML JavaScript Host Environment
+
+QML provides a JavaScript host environment tailored to writing QML applications.
+This environment is different from the host environment provided by a browser
+or a server-side JavaScript environment such as Node.js. For example, QML does
+not provide a \c window object or \c{DOM API} as commonly found in a browser environment.
+
+\section1 Common Base
+
+Like a browser or server-side JavaScript environment, the QML runtime implements the
+\l{ECMA-262}{ECMAScript Language Specification} standard. This provides access to
+all of the built-in types and functions defined by the standard, such as Object, Array, and Math.
+The QML runtime implements the 5th edition of the standard, which is the same edition commonly
+implemented by browsers.
+
+The standard ECMAScript built-ins are not explicitly documented in the QML documentation. For more
+information on their use, please refer to the ECMA-262 5th edition standard or one of the many online
+JavaScript reference and tutorial sites, such as the \l{W3Schools JavaScript Reference} (JavaScript Objects
+Reference section). Many sites focus on JavaScript in the browser, so in some cases you may need to double
+check the specification to determine whether a given function or object is part of standard ECMAScript or
+specific to the browser environment. In the case of the W3Schools link above, the \c{JavaScript Objects
+Reference} section generally covers the standard, while the \c{Browser Objects Reference} and \c{HTML DOM
+Objects Reference} sections are browser specific (and thus not applicable to QML).
+
+\section1 Host Objects and Functions
+
+The QML JavaScript host environment implements the following host objects and functions:
+
+\list
+\li The \l{QmlGlobalQtObject}{Qt object}: This object is specific to QML, and provides helper methods
+ and properties specific to the QML environment.
+\li qsTr(), qsTranslate(), qsTrId(), QT_TR_NOOP(), QT_TRANSLATE_NOOP(), and QT_TRID_NOOP() functions:
+ These functions are specific to QML, and provide \l{Translation}{translation capabilities} to the QML environment.
+\li gc() function: This function is specific to QML, and provides a way to manually trigger garbage collection.
+\li print() function: This function is specific to QML, and provides a simple way to output information to the console.
+\li The \l{Console API}{console object}: This object implements a subset of the \l{http://getfirebug.com/wiki/index.php/Console_API}{FireBug Console API}.
+\li \l{XMLHttpRequest}, DOMException: These objects implement a subset of the \l{http://www.w3.org/TR/XMLHttpRequest/}{W3C XMLHttpRequest specification}.
+\endlist
+
+See \l{QML Global Object} for more details on these host objects and functions.
+
+\section1 Native Object Modification
+
+QML makes the following modifications to native objects:
+
+\list
+\li An arg() function is added to the String prototype.
+\li Locale-aware coversion functions are added to the \l{Date} and \l{Number} prototypes.
+\endlist
+
+\section1 Restrictions
+
+QML implements the following restrictions for JavaScript code:
+
+\list
+\li JavaScript code cannot modify the global object.
+\li Global code is run in a reduced scope.
+\li The value of \c this is undefined in QML in the majority of contexts.
+\endlist
+
+See \l {QML JavaScript Restrictions} for more details on these restrictions.
+
+*/
diff --git a/doc/src/qml/qmlengine.qdoc b/doc/src/qml/qmlengine.qdoc
index b0754fe3ab..ad77d43cb5 100644
--- a/doc/src/qml/qmlengine.qdoc
+++ b/doc/src/qml/qmlengine.qdoc
@@ -467,9 +467,13 @@ specified in QML files, plugins, or applications.
\section1 JavaScript Runtime
- The runtime implements the \l{ECMA-262}{ECMAScript Language Specification} standard.
- The reserved words, conditionals, variables, and object behaviors follow
- after the standard.
+ The runtime implements the \l{ECMA-262}{ECMAScript Language Specification} standard,
+ 5th edition. The reserved words, conditionals, variables, and object behaviors
+ follow after the standard.
+
+ The \l{QML JavaScript Host Environment} article has information about the
+ JavaScript host environment provided by QML, which is different than the
+ browser host environment many are familiar with.
The \l{JavaScript Code} article has information about placing JavaScript
code within QML code.
diff --git a/doc/src/qml/qmli18n.qdoc b/doc/src/qml/qmli18n.qdoc
index d15beafb38..b65c001e8e 100644
--- a/doc/src/qml/qmli18n.qdoc
+++ b/doc/src/qml/qmli18n.qdoc
@@ -33,8 +33,8 @@
\section1 Translation
-Strings in QML can be marked for translation using the qsTr(), qsTranslate(),
-QT_TR_NOOP(), and QT_TRANSLATE_NOOP() functions.
+Strings in QML can be marked for translation using the qsTr(), qsTranslate(), qsTrId(),
+QT_TR_NOOP(), QT_TRANSLATE_NOOP(), and QT_TRID_NOOP() functions.
For example:
\qml