From c5b56564667194b179ebfcc87608d38e9969fade Mon Sep 17 00:00:00 2001 From: Kent Hansen Date: Thu, 11 Aug 2011 13:58:53 +0200 Subject: Improve the Qt/JavaScript (QJS) documentation Make sure all public classes and functions are documented. Fix/remove broken references. Add code snippets. Add a minimal "Making Applications Scriptable" page based on the QtScript docs. Change-Id: I76a32bff776b478f01ff08b3276a0a020a1fa81f Reviewed-on: http://codereview.qt.nokia.com/2863 Reviewed-by: Qt Sanity Bot Reviewed-by: Simon Hausmann --- doc/src/declarative/qtjavascript.qdoc | 92 ++++++++++++++++++++++ doc/src/snippets/code/src_script_qjsengine.cpp | 90 +++++++++++++++++++++ doc/src/snippets/code/src_script_qjsvalue.cpp | 65 +++++++++++++++ .../snippets/code/src_script_qjsvalueiterator.cpp | 72 +++++++++++++++++ doc/src/snippets/qtjavascript/evaluation/main.cpp | 51 ++++++++++++ .../qtjavascript/registeringobjects/main.cpp | 57 ++++++++++++++ .../qtjavascript/registeringvalues/main.cpp | 53 +++++++++++++ 7 files changed, 480 insertions(+) create mode 100644 doc/src/declarative/qtjavascript.qdoc create mode 100644 doc/src/snippets/code/src_script_qjsengine.cpp create mode 100644 doc/src/snippets/code/src_script_qjsvalue.cpp create mode 100644 doc/src/snippets/code/src_script_qjsvalueiterator.cpp create mode 100644 doc/src/snippets/qtjavascript/evaluation/main.cpp create mode 100644 doc/src/snippets/qtjavascript/registeringobjects/main.cpp create mode 100644 doc/src/snippets/qtjavascript/registeringvalues/main.cpp (limited to 'doc/src') diff --git a/doc/src/declarative/qtjavascript.qdoc b/doc/src/declarative/qtjavascript.qdoc new file mode 100644 index 0000000000..6d5e237c63 --- /dev/null +++ b/doc/src/declarative/qtjavascript.qdoc @@ -0,0 +1,92 @@ +/**************************************************************************** +** +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** 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$ +** +****************************************************************************/ + +/*! + \group qtjavascript + \title Scripting Classes and Overviews + + \brief Classes for embedding JavaScript in Qt/C++ applications. +*/ + +/*! + \page qtjavascript.html + \title Making Applications Scriptable + \ingroup frameworks-technologies + + Qt provides support for application scripting with JavaScript. + The following guides and references cover aspects of programming with + JavaScript and Qt. + + \tableofcontents + + \section1 Scripting Classes + + The following classes add scripting capabilities to Qt applications. + + \annotatedlist qtjavascript + + \section1 Basic Usage + + To evaluate script code, you create a QJSEngine and call its + evaluate() function, passing the script code (text) to evaluate + as argument. + + \snippet doc/src/snippets/qtjavascript/evaluation/main.cpp 0 + + The return value will be the result of the evaluation (represented + as a QJSValue object); this can be converted to standard C++ + and Qt types. + + Custom properties can be made available to scripts by registering + them with the script engine. This is most easily done by setting + properties of the script engine's \e{Global Object}: + + \snippet doc/src/snippets/qtjavascript/registeringvalues/main.cpp 0 + + This places the properties in the script environment, thus making them + available to script code. + + \section1 Making a QObject Available to the Script Engine + + Any QObject-based instance can be made available for use with scripts. + + When a QObject is passed to the QJSEngine::newQObject() function, + a Qt Script wrapper object is created that can be used to make the + QObject's signals, slots, properties, and child objects available + to scripts. + + Here's an example of making an instance of a QObject subclass + available to script code under the name \c{"myObject"}: + + \snippet doc/src/snippets/qtjavascript/registeringobjects/main.cpp 0 + + This will create a global variable called \c{myObject} in the + script environment. The variable serves as a proxy to the + underlying C++ object. Note that the name of the script variable + can be anything; i.e., it is not dependent upon QObject::objectName(). + + */ diff --git a/doc/src/snippets/code/src_script_qjsengine.cpp b/doc/src/snippets/code/src_script_qjsengine.cpp new file mode 100644 index 0000000000..56c3d6b114 --- /dev/null +++ b/doc/src/snippets/code/src_script_qjsengine.cpp @@ -0,0 +1,90 @@ +/**************************************************************************** +** +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +QJSEngine myEngine; +QJSValue three = myEngine.evaluate("1 + 2"); +//! [0] + + +//! [1] +QJSValue fun = myEngine.evaluate("(function(a, b) { return a + b; })"); +QJSValueList args; +args << 1 << 2; +QJSValue threeAgain = fun.call(QJSValue(), args); +//! [1] + + +//! [2] +QString fileName = "helloworld.qs"; +QFile scriptFile(fileName); +if (!scriptFile.open(QIODevice::ReadOnly)) + // handle error +QTextStream stream(&scriptFile); +QString contents = stream.readAll(); +scriptFile.close(); +myEngine.evaluate(contents, fileName); +//! [2] + + +//! [3] +myEngine.globalObject().setProperty("myNumber", 123); +... +QJSValue myNumberPlusOne = myEngine.evaluate("myNumber + 1"); +//! [3] + + +//! [4] +QJSValue result = myEngine.evaluate(...); +if (myEngine.hasUncaughtException()) + qDebug() << "uncaught exception:" << result.toString(); +//! [4] + + +//! [5] +QPushButton button; +QJSValue scriptButton = myEngine.newQObject(&button); +myEngine.globalObject().setProperty("button", scriptButton); + +myEngine.evaluate("button.checkable = true"); + +qDebug() << scriptButton.property("checkable").toBoolean(); +scriptButton.property("show").call(); // call the show() slot +//! [5] diff --git a/doc/src/snippets/code/src_script_qjsvalue.cpp b/doc/src/snippets/code/src_script_qjsvalue.cpp new file mode 100644 index 0000000000..c64c4c0f2a --- /dev/null +++ b/doc/src/snippets/code/src_script_qjsvalue.cpp @@ -0,0 +1,65 @@ +/**************************************************************************** +** +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +QJSEngine myEngine; +QJSValue myObject = myEngine.newObject(); +QJSValue myOtherObject = myEngine.newObject(); +myObject.setProperty("myChild", myOtherObject); +myObject.setProperty("name", "John Doe"); +//! [0] + + +//! [1] +QJSEngine engine; +engine.evaluate("function fullName() { return this.firstName + ' ' + this.lastName; }"); +engine.evaluate("somePerson = { firstName: 'John', lastName: 'Doe' }"); + +QJSValue global = engine.globalObject(); +QJSValue fullName = global.property("fullName"); +QJSValue who = global.property("somePerson"); +qDebug() << fullName.call(who).toString(); // "John Doe" + +engine.evaluate("function cube(x) { return x * x * x; }"); +QJSValue cube = global.property("cube"); +QJSValueList args; +args << 3; +qDebug() << cube.call(QJSValue(), args).toNumber(); // 27 +//! [1] diff --git a/doc/src/snippets/code/src_script_qjsvalueiterator.cpp b/doc/src/snippets/code/src_script_qjsvalueiterator.cpp new file mode 100644 index 0000000000..f72e9180e1 --- /dev/null +++ b/doc/src/snippets/code/src_script_qjsvalueiterator.cpp @@ -0,0 +1,72 @@ +/**************************************************************************** +** +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +QScriptValue object; +... +QScriptValueIterator it(object); +while (it.hasNext()) { + it.next(); + qDebug() << it.name() << ": " << it.value().toString(); +} +//! [0] + + +//! [1] +QScriptValue obj = ...; // the object to iterate over +while (obj.isObject()) { + QScriptValueIterator it(obj); + while (it.hasNext()) { + it.next(); + qDebug() << it.name(); + } + obj = obj.prototype(); +} +//! [1] + + +//! [2] +while (it.hasNext()) { + it.next(); + if (it.flags() & QScriptValue::SkipInEnumeration) + continue; + qDebug() << "found enumerated property:" << it.name(); +} +//! [2] diff --git a/doc/src/snippets/qtjavascript/evaluation/main.cpp b/doc/src/snippets/qtjavascript/evaluation/main.cpp new file mode 100644 index 0000000000..77825669a8 --- /dev/null +++ b/doc/src/snippets/qtjavascript/evaluation/main.cpp @@ -0,0 +1,51 @@ +/**************************************************************************** +** +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#include + +int main(int argc, char *argv[]) +{ + QCoreApplication app(argc, argv); + //! [0] + QJSEngine engine; + qDebug() << "the magic number is:" << engine.evaluate("1 + 2").toNumber(); + //! [0] + return 0; +} diff --git a/doc/src/snippets/qtjavascript/registeringobjects/main.cpp b/doc/src/snippets/qtjavascript/registeringobjects/main.cpp new file mode 100644 index 0000000000..25c0f148e7 --- /dev/null +++ b/doc/src/snippets/qtjavascript/registeringobjects/main.cpp @@ -0,0 +1,57 @@ +/**************************************************************************** +** +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#include +#include +#include "myobject.h" + +int main(int argc, char *argv[]) +{ + QCoreApplication app(argc, argv); + //! [0] + QJSEngine engine; + QObject *someObject = new MyObject; + QJSValue objectValue = engine.newQObject(someObject); + engine.globalObject().setProperty("myObject", objectValue); + //! [0] + qDebug() << "myObject's calculate() function returns" + << engine.evaluate("myObject.calculate(10)").toNumber(); + return 0; +} diff --git a/doc/src/snippets/qtjavascript/registeringvalues/main.cpp b/doc/src/snippets/qtjavascript/registeringvalues/main.cpp new file mode 100644 index 0000000000..fe32f7065a --- /dev/null +++ b/doc/src/snippets/qtjavascript/registeringvalues/main.cpp @@ -0,0 +1,53 @@ +/**************************************************************************** +** +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#include + +int main(int argc, char *argv[]) +{ + QCoreApplication app(argc, argv); + QJSEngine engine; + //! [0] + engine.globalObject().setProperty("foo", 123); + qDebug() << "foo times two is:" << engine.evaluate("foo * 2").toNumber(); + //! [0] + return 0; +} + -- cgit v1.2.3