diff options
Diffstat (limited to 'doc/src')
27 files changed, 5472 insertions, 0 deletions
diff --git a/doc/src/examples/context2d.qdoc b/doc/src/examples/context2d.qdoc new file mode 100644 index 0000000..f10e1ec --- /dev/null +++ b/doc/src/examples/context2d.qdoc @@ -0,0 +1,339 @@ +/**************************************************************************** +** +** 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$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the Technology Preview License Agreement accompanying +** this package. +** +** 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. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example script/context2d + \title Context2D Example + + This Qt Script example is an implementation of the Context2D API. + + \image context2d-example.png + + Context2D is part of the specification for the HTML \c{<canvas>} + element. It can be used to draw graphics via scripting. A good + resource for learning more about the HTML \c{<canvas>} element is + the \l{http://developer.mozilla.org/en/docs/HTML:Canvas}{Mozilla Developer Center}. + + \section1 Using The HTML Canvas Element in a Web Browser + + First, let's look at how the \c{<canvas>} element is typically + used in a web browser. The following HTML snippet defines a + canvas of size 400x400 pixels with id \c{mycanvas}: + + \code + <canvas width="400" height="400" id="mycanvas">Fallback content goes here.</canvas> + \endcode + + To draw on the canvas, we must first obtain a reference to the + DOM element corresponding to the \c{<canvas>} tag and then call + the element's getContext() function. The resulting object + implements the Context2D API that we use to draw. + + \code + <script> + var canvas = document.getElementById("mycanvas"); + var ctx = canvas.getContext("2d"); + + // Draw a face + ctx.beginPath(); + ctx.arc(75,75,50,0,Math.PI*2,true); // Outer circle + ctx.moveTo(110,75); + ctx.arc(75,75,35,0,Math.PI,false); // Mouth + ctx.moveTo(65,65); + ctx.arc(60,65,5,0,Math.PI*2,true); // Left eye + ctx.moveTo(95,65); + ctx.arc(90,65,5,0,Math.PI*2,true); // Right eye + ctx.stroke(); + </script> + \endcode + + When the page is rendered by a browser that supports the + \c{<canvas>} tag, this would be the result: + + \image context2d-example-smileysmile.png + + \section1 Using Qt Script to script a Canvas + + The goal of this example is to be able to evaluate scripts + that use the Context2D API, and render the results. Basic + interaction (mouse, keyboard) should also be supported. + In other words, we want to present scripts with an execution + environment that very much resembles that of a web browser. Of + course, our environment is only a small subset of what a browser + provides; i.e. we don't provide a full DOM API, only what is + needed to run "self-contained" Context2D scripts (i.e. scripts + that don't depend on other parts of the DOM document). + + Our "Context2D-browser" is set up through the following steps: + \list + \o Create an Environment. + \o Create a Context2D, and a QContext2DCanvas widget to render it. + \o Add the canvas object to the environment; this will enable + scripts to obtain a reference to it. + \o Evaluate scripts in the environment. + \endlist + + Once a script has been evaluated, the application handles any + timer events and input events that occur subsequently + (i.e. forwards events to their associated script targets). + + \section1 The Context2D Class + + The "heart" of this example is the Context2D C++ class that implements + the drawing API. Its interface is defined in terms of properties + and slots. Note that this class isn't tied to Qt Script in any + way. + + \snippet examples/script/context2d/context2d.h 0 + + The properties define various aspects of the Context2D + configuration. + + \snippet examples/script/context2d/context2d.h 1 + + The slots define the operations that can be performed. + + \snippet examples/script/context2d/context2d.h 2 + + The changed() signal is emitted when the contents of the drawing + area has changed, so that clients associated with the Context2D + object (i.e. the canvas widget that renders it) are notified. + + \section2 Implementation + + Conveniently enough, the concepts, data structures and operations + of the Context2D API map more or less directly to Qt's painting + API. Conceptually, all we have to do is initialize a QPainter + according to the Context2D properties, and use functions like + QPainter::strokePath() to do the painting. Painting is done on a + QImage. + + \snippet examples/script/context2d/context2d.cpp 0 + + The property accessors and most of the slots manipulate the + internal Context2D state in some way. For the \c{lineCap} + property, Context2D uses a string representation; we therefore + have to map it from/to a Qt::PenCapStyle. The \c{lineJoin} + property is handled in the same fashion. All the property setters + also set a \e{dirty flag} for the property; this is used to + decide which aspects of the QPainter that need to be updated + before doing the next painting operation. + + \snippet examples/script/context2d/context2d.cpp 3 + + The implementation of the \c{fillStyle} property is interesting, + since the value can be either a string or a \c{CanvasGradient}. + We handle this by having the property be of type QVariant, + and check the actual type of the value to see how to handle the + write. + + \snippet examples/script/context2d/context2d.cpp 1 + + Context2D does not have a concept of a paint event; painting + operations can happen at any time. We would like to be efficient, + and not have to call QPainter::begin() and QPainter::end() for + every painting operation, since typically many painting operations + will follow in quick succession. The implementations of the + painting operations use a helper function, beginPainting(), that + activates the QPainter if it isn't active already, and updates + the state of the QPainter (brush, pen, etc.) so that it reflects + the current Context2D state. + + \snippet examples/script/context2d/context2d.cpp 2 + + The implementation of each painting operation ends by calling + scheduleChange(), which will post a zero-timer event if one is + not already pending. When the application returns to the event + loop later (presumably after all the drawing operations have + finished), the timer will trigger, QPainter::end() will be + called, and the changed() signal is emitted with the new + image as argument. The net effect is that there will typically + be only a single (QPainter::begin(), QPainter::end()) pair + executed for the full sequence of painting operations. + + \section1 The Canvas Widget + + \snippet examples/script/context2d/qcontext2dcanvas.h 0 + + The QContext2DCanvas class provides a widget that renders + the contents of a Context2D object. It also provides a + minimal scripting API, most notably the getContext() function. + + \snippet examples/script/context2d/qcontext2dcanvas.cpp 3 + + The constructor connects to the changed() signal of the + Context2D object, so that the widget can update itself + when it needs to do so. Mouse tracking is enabled so that + mouse move events will be received even when no mouse + buttons are depressed. + + \snippet examples/script/context2d/qcontext2dcanvas.cpp 0 + + The getContext() function asks the environment to wrap the + Context2D object; the resulting proxy object makes the + Context2D API available to scripts. + + \snippet examples/script/context2d/qcontext2dcanvas.cpp 1 + + The paintEvent() function simply paints the contents that + was last received from the Context2D object. + + \snippet examples/script/context2d/qcontext2dcanvas.cpp 2 + + The canvas widget reimplements mouse and key event handlers, and + forwards these events to the scripting environment. The + environment will take care of delivering the event to the proper + script target, if any. + + \section1 The Environment + + \snippet examples/script/context2d/environment.h 0 + + The Environment class provides a scripting environment where a + Canvas C++ object can be registered, looked up by ID (name), + and where scripts can be evaluated. The environment has a + \c{document} property, just like the scripting environment of a + web browser, so that scripts can call + \c{document.getElementById()} to obtain a reference to a canvas. + + \snippet examples/script/context2d/environment.h 1 + + The Environment class provides the timer attributes of the DOM + Window Object interface. This enables us to support scripts that + do animation, for example. + + \snippet examples/script/context2d/environment.h 2 + + The scriptError() signal is emitted when evaluation of a script + causes a script exception. For example, if a mouse press handler + or timeout handler causes an exception, the environment's client(s) + will be notified of this and can report the error. + + \snippet examples/script/context2d/environment.cpp 0 + + The constructor initializes the environment. First it creates + the QScriptEngine that will be used to evaluate scripts. It + creates the Document object that provides the getElementById() + function. Note that the QScriptEngine::ExcludeSuperClassContents + flag is specified to avoid the wrapper objects from exposing properties + and methods inherited from QObject. Next, the environment wraps + a pointer to \e{itself}; this is to prepare for setting this object + as the script engine's Global Object. The properties of the standard + Global Object are copied, so that these will also be available in + our custom Global Object. We also create two self-references to the + object; again, this is to provide a minimal level of compabilitity + with the scripting environment that web browsers provide. + + \snippet examples/script/context2d/environment.cpp 5 + + The addCanvas() function adds the given canvas to the list of + registered canvas objects. The canvasByName() function looks up + a canvas by QObject::objectName(). This function is used to + implement the \c{document.getElementById()} script function. + + \snippet examples/script/context2d/environment.cpp 1 + + The setInterval() and clearInterval() implementations use a QHash + to map from timer ID to the QScriptValue that holds the expression + to evaluate when the timer is triggered. A helper function, + maybeEmitScriptError(), is called after invoking the script handler; + it will emit the scriptError() signal if the script engine has an + uncaught exception. + + \snippet examples/script/context2d/environment.cpp 2 + + The toWrapper() functions creates a QScriptValue that wraps the + given QObject. Note that the QScriptEngine::PreferExistingWrapperObject + flag is specified; this guarantees that a single, unique wrapper + object will be returned, even if toWrapper() is called several times + with the same argument. This is important, since it is possible that + a script can set new properties on the resulting wrapper object (e.g. + event handlers like \c{onmousedown}), and we want these to persist. + + \snippet examples/script/context2d/environment.cpp 3 + + The handleEvent() function determines if there exists a handler + for the given event in the environment, and if so, invokes that + handler. Since the script expects a DOM event, the Qt C++ event + must be converted to a DOM event before it is passed to the + script. This mapping is relatively straightforward, but again, + we only implement a subset of the full DOM API; just enough to + get most scripts to work. + + \snippet examples/script/context2d/environment.cpp 4 + + The newFakeDomEvent() function is a helper function that creates + a new script object and initializes it with default values for + the attributes defined in the DOM Event and DOM UIEvent + interfaces. + + \snippet examples/script/context2d/environment.h 3 + + The Document class defines two slots that become available to + scripts: getElementById() and getElementsByTagName(). + When the tag name is "canvas", getElementsByTagName() will + return a list of all canvas objects that are registered in + the environment. + + \section1 The Application Window + + \snippet examples/script/context2d/window.cpp 0 + + The Window constructor creates an Environment object and + connects to its scriptError() signal. It then creates a + Context2D object, and a QContext2DCanvas widget to hold it. + The canvas widget is given the name \c{tutorial}, and added to the + environment; scripts can access the canvas by e.g. + \c{document.getElementById('tutorial')}. + + \snippet examples/script/context2d/window.cpp 1 + + The window contains a list widget that is populated with + available scripts (read from a \c{scripts/} folder). + + \snippet examples/script/context2d/window.cpp 2 + + When an item is selected, the corresponding script is + evaluated in the environment. + + \snippet examples/script/context2d/window.cpp 3 + + When the "Run in Debugger" button is clicked, the Qt Script debugger will + automatically be invoked when the first statement of the script is + reached. This enables the user to inspect the scripting environment and + control further execution of the script; e.g. he can single-step through + the script and/or set breakpoints. It is also possible to enter script + statements in the debugger's console widget, e.g. to perform custom + Context2D drawing operations, interactively. + + \snippet examples/script/context2d/window.cpp 4 + + If the evaluation of a script causes an uncaught exception, the Qt Script + debugger will automatically be invoked; this enables the user to get an + idea of what went wrong. + +*/ diff --git a/doc/src/examples/defaultprototypes.qdoc b/doc/src/examples/defaultprototypes.qdoc new file mode 100644 index 0000000..5a2b69e --- /dev/null +++ b/doc/src/examples/defaultprototypes.qdoc @@ -0,0 +1,124 @@ +/**************************************************************************** +** +** 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$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the Technology Preview License Agreement accompanying +** this package. +** +** 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. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example script/defaultprototypes + \title Default Prototypes Example + + This Qt Script example shows how to use default prototypes + to make a non-QObject-based type scriptable. + + \image defaultprototypes-example.png + + With QScriptEngine::setDefaultPrototype() you can specify + a QtScript object that defines a scripting interface for + a C++ type; Qt Script operations on values of such types + will then be delegated to your prototype object. In this + example, a simple scripting interface for QListWidgetItem is + defined, so that the text of items can easily be accessed from + script code. + + To define a scripting API for QListWidgetItem in terms of + Qt properties and slots, we subclass QObject and QScriptable. + + \snippet examples/script/defaultprototypes/prototypes.h 0 + + A single property, \c{text}, is defined, along with a slot, + \c{toString}. + + \snippet examples/script/defaultprototypes/prototypes.cpp 0 + + The implementation of the property accessors use + the qscriptvalue_cast() function to cast the script object + to a QListWidgetItem pointer. The normal C++ QListWidgetItem + API is then used to implement the desired functionality. + + Although not shown here, it is possible to throw a script + exception from a prototype function; for example, you could throw + a TypeError exception if the qscriptvalue_cast() fails. + + QListWidgetItems are usually added to a QListWidget. While + QListWidget is a QObject-based class, not all the functionality + needed for this example are present. We can solve this by creating + a default prototype for the QListWidget class as well. The + prototype will augment the functionality already provided by the + Qt Script QObject integration; i.e. if a property or slot is not + found in the QListWidget object itself, the prototype will be used + as a fallback. + + \snippet examples/script/defaultprototypes/prototypes.h 1 + + The additional slots will make it possible to add items to + a QListWidget from script code, and to set the background + color of the widget from a string. + + \snippet examples/script/defaultprototypes/prototypes.cpp 1 + + Again, we use qscriptvalue_cast() to cast the script object + to the relevant C++ type, in this case a QListWidget pointer. + The addItem() and addItems() functions simply forward their + arguments to the corresponding functions in the QListWidget + class. setBackgroundColor() gets the widget's palette, creates + a QColor from the given string argument and changes the palette + accordingly. + + \snippet examples/script/defaultprototypes/main.cpp 0 + + The relevant C++ types must be made known to Qt's meta type + system. + + \snippet examples/script/defaultprototypes/main.cpp 1 + + For each type that we want to associate a prototype object with, + we create an instance of the prototype class, pass it to + QScriptEngine::newQObject(), and then create the link between + the C++ type and the resulting script object by calling + QScriptEngine::setDefaultPrototype(). + + \snippet examples/script/defaultprototypes/main.cpp 2 + + In this example, a single QListWidget object is added as + a global script variable, called \c{listWidget}. Script code + can add items to this widget by calling addItem() or addItems(). + + \snippet examples/script/defaultprototypes/code.js 0 + + Script code can connect to signals of the QListWidget object; + signal handlers can use the interface defined in + the QListWidgetItem prototype to manipulate item arguments. + + \snippet examples/script/defaultprototypes/code.js 1 + + Not shown in this example is how to make QListWidgetItem + constructible from Qt Script code, i.e. to be able to + write "new QListWidgetItem()" in a script. In order to do + this, you have to define your own script constructor for + the type. The constructor would just be a factory function + that constructs a new C++ QListWidgetItem and returns it + back to the script. See QScriptEngine::newFunction() for more + information. +*/ diff --git a/doc/src/examples/helloscript.qdoc b/doc/src/examples/helloscript.qdoc new file mode 100644 index 0000000..4b3ede5 --- /dev/null +++ b/doc/src/examples/helloscript.qdoc @@ -0,0 +1,128 @@ +/**************************************************************************** +** +** 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$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the Technology Preview License Agreement accompanying +** this package. +** +** 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. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example script/helloscript + \title Hello Script Example + + The Hello Script example shows the basic use of Qt Script: How to embed + a script engine into the application, how to evaluate a script, and how + to process the result of the evaluation. The example also shows how to + apply internationalization to scripts. + + \snippet examples/script/helloscript/main.cpp 0 + + The application will load the script file to evaluate from a resource, so + we first make sure that the resource is initialized. + + \snippet examples/script/helloscript/main.cpp 1 + + We attempt to load a translation, and install translation functions in the + script engine. How to produce a translation is explained later. + + \snippet examples/script/helloscript/main.cpp 2 + + A push button is created and exported to the script environment as a + global variable, \c button. Scripts will be able to access properties, + signals and slots of the button as properties of the \c button script + object; the script object acts as a proxy to the C++ button object. + + \snippet examples/script/helloscript/main.cpp 3 + + The contents of the script file are read. + + \snippet examples/script/helloscript/helloscript.js 0 + + The script sets the \c text (note that the qTr() function is used to allow + for translation) and \c styleSheet properties of the button, and calls the + button's \c show() slot. + + \snippet examples/script/helloscript/main.cpp 4 + + The script is evaluated. Note that the file name is passed as the + (optional) second parameter; this makes it possible for the script engine + to produce a meaningful backtrace if something goes wrong, and makes the + qTr() function be able to resolve the translations that are associated + with this script. + + \snippet examples/script/helloscript/main.cpp 5 + + If the result is an Error object (e.g. the script contained a syntax + error, or tried to call a function that doesn't exist), we obtain + the line number and string representation of the error and display + it in a message box. + + \snippet examples/script/helloscript/main.cpp 6 + + If the evaluation went well, the application event loop is entered. + + \section1 Translating the Application + + The Qt Script internalization support builds on what Qt already provides + for C++; see the \l{Hello tr() Example} for an introduction. + + Since we haven't made the translation file \c helloscript_la.qm, the + source text is shown when we run the application ("Hello world!"). + + To generate the translation file, run \c lupdate as follows: + + \code + lupdate helloscript.js -ts helloscript_la.ts + \endcode + + You should now have a file \c helloscript_la.ts in the current + directory. Run \c linguist to edit the translation: + + \code + linguist helloscript_la.ts + \endcode + + You should now see the text "helloscript.js" in the top left pane. + Double-click it, then click on "Hello world!" and enter "Orbis, te + saluto!" in the \gui Translation pane (the middle right of the + window). Don't forget the exclamation mark! + + Click the \gui Done checkbox and choose \gui File|Save from the + menu bar. The TS file will no longer contain + + \snippet doc/src/snippets/code/doc_src_examples_hellotr.qdoc 3 + + but instead will have + + \snippet doc/src/snippets/code/doc_src_examples_hellotr.qdoc 4 + + To see the application running in Latin, we have to generate a QM + file from the TS file. Generating a QM file can be achieved + either from within \e {Qt Linguist} (for a single TS file), or + by using the command line program \c lrelease which will produce one + QM file for each of the TS files listed in the project file. + Generate \c hellotr_la.qm from \c hellotr_la.ts by choosing + \gui File|Release from \e {Qt Linguist}'s menu bar and pressing + \gui Save in the file save dialog that pops up. Now run the \c helloscript + program again. This time the button will be labelled "Orbis, te + saluto!". +*/ diff --git a/doc/src/images/context2d-example-smileysmile.png b/doc/src/images/context2d-example-smileysmile.png Binary files differnew file mode 100644 index 0000000..369f32e --- /dev/null +++ b/doc/src/images/context2d-example-smileysmile.png diff --git a/doc/src/images/context2d-example.png b/doc/src/images/context2d-example.png Binary files differnew file mode 100644 index 0000000..0c12754 --- /dev/null +++ b/doc/src/images/context2d-example.png diff --git a/doc/src/images/defaultprototypes-example.png b/doc/src/images/defaultprototypes-example.png Binary files differnew file mode 100644 index 0000000..72fe3c4 --- /dev/null +++ b/doc/src/images/defaultprototypes-example.png diff --git a/doc/src/images/qtscript-debugger.png b/doc/src/images/qtscript-debugger.png Binary files differnew file mode 100644 index 0000000..c417d0b --- /dev/null +++ b/doc/src/images/qtscript-debugger.png diff --git a/doc/src/scripting/ecmascript.qdoc b/doc/src/scripting/ecmascript.qdoc new file mode 100644 index 0000000..7d59759 --- /dev/null +++ b/doc/src/scripting/ecmascript.qdoc @@ -0,0 +1,342 @@ +/**************************************************************************** +** +** 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$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the Technology Preview License Agreement accompanying +** this package. +** +** 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. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page ecmascript.html + \title ECMAScript Reference + \brief A list of objects, functions and properties supported by QtScript. + + This reference contains a list of built-in objects, functions and + properties supported by QtScript. For a detailed description, see + the \l{ECMA-262} specification. + + \tableofcontents + + \section1 The Global Object + + \section2 Value Properties + + \list + \o NaN + \o Infinity + \o undefined + \endlist + + \section2 Function Properties + + \list + \o eval(x) + \o parseInt(string, radix) + \o parseFloat(string) + \o isNaN(number) + \o isFinite(number) + \o decodeURI(encodedURI) + \o decodeURIComponent(encodedURIComponent) + \o encodeURI(uri) + \o encodeURIComponent(uriComponent) + \endlist + + \section2 Constructor Properties + + \list + \o Object + \o Function + \o Array + \o String + \o Boolean + \o Number + \o Date + \o RegExp + \o Error + \o EvalError + \o RangeError + \o ReferenceError + \o SyntaxError + \o TypeError + \o URIError + \endlist + + \section2 Other Properties + + \list + \o Math + \o JSON + \endlist + + \section1 Object Objects + + \section2 Object Constructor + + \section3 Function Properties + + \list + \o getPrototypeOf(O) + \o getOwnPropertyDescriptor(O, P) + \o getOwnPropertyNames(O) + \o create(O [, Properties]) + \o defineProperty(O, P, Attributes) + \o defineProperties(O, Properties) + \o keys(O) + \endlist + + \section2 Object Prototype Object + + \section3 Function Properties + + \list + \o toString() + \o toLocaleString() + \o valueOf() + \o hasOwnProperty(V) + \o isPrototypeOf(V) + \o propertyIsEnumerable(V) + \endlist + + \section1 Function Objects + + \section2 Function Prototype Object + + \section3 Function Properties + + \list + \o toString() + \o apply(thisArg, argArray) + \o call(thisArg [, arg1 [, arg2, ...]]) + \endlist + + \section1 Array Objects + + \section2 Array Prototype Object + + \section3 Function Properties + + \list + \o toString() + \o toLocaleString() + \o concat([item1 [, item2 [, ...]]]) + \o join(separator) + \o pop() + \o push([item1 [, item2 [, ...]]]) + \o reverse() + \o shift() + \o slice(start, end) + \o sort(comparefn) + \o splice(start, deleteCount[, item1 [, item2 [, ...]]]) + \o unshift([item1 [, item2 [, ...]]]) + \o indexOf(searchElement [, fromIndex]) + \o lastIndexOf(searchElement [, fromIndex]) + \o every(callbackfn [, thisArg]) + \o some(callbackfn [, thisArg]) + \o forEach(callbackfn [, thisArg]) + \o map(callbackfn [, thisArg]) + \o filter(callbackfn [, thisArg]) + \o reduce(callbackfn [, initialValue]) + \o reduceRight(callbackfn [, initialValue]) + \endlist + + \section1 String Objects + + \section2 String Prototype Object + + \section3 Function Properties + + \list + \o toString() + \o valueOf() + \o charAt(pos) + \o charCodeAt(pos) + \o concat([string1 [, string2 [, ...]]]) + \o indexOf(searchString ,position) + \o lastIndexOf(searchString, position) + \o localeCompare(that) + \o match(regexp) + \o replace(searchValue, replaceValue) + \o search(regexp) + \o slice(start, end) + \o split(separator, limit) + \o substring(start, end) + \o toLowerCase() + \o toLocaleLowerCase() + \o toUpperCase() + \o toLocaleUpperCase() + \o trim() + \endlist + + \section1 Boolean Objects + + \section2 Boolean Prototype Object + + \section3 Function Properties + + \list + \o toString() + \o valueOf() + \endlist + + \section1 Number Objects + + \section2 Number Prototype Object + + \section3 Function Properties + + \list + \o toString(radix) + \o toLocaleString() + \o toFixed(fractionDigits) + \o toExponential(fractionDigits) + \o toPrecision(precision) + \endlist + + \section1 The Math Object + + \section2 Value Properties + + \list + \o E + \o LN10 + \o LN2 + \o LOG2E + \o LOG10E + \o PI + \o SQRT1_2 + \o SQRT2 + \endlist + + \section2 Function Properties + + \list + \o abs(x) + \o acos(x) + \o asin(x) + \o atan(x) + \o atan2(y, x) + \o ceil(x) + \o cos(x) + \o exp(x) + \o floor(x) + \o log(x) + \o max([value1 [, value2 [, ...]]]) + \o min([value1 [, value2 [, ...]]]) + \o pow(x, y) + \o random() + \o round(x) + \o sin(x) + \o sqrt(x) + \o tan(x) + \endlist + + \section1 Date Objects + + \section2 Date Prototype Object + + \section3 Function Properties + + \list + \o toString() + \o toDateString() + \o toTimeString() + \o toLocaleString() + \o toLocaleDateString() + \o toLocaleTimeString() + \o valueOf() + \o getTime() + \o getFullYear() + \o getUTCFullYear() + \o getMonth() + \o getUTCMonth() + \o getDate() + \o getUTCDate() + \o getDay() + \o getUTCDay() + \o getHours() + \o getUTCHours() + \o getMinutes() + \o getUTCMinutes() + \o getSeconds() + \o getUTCSeconds() + \o getMilliseconds() + \o getUTCMilliseconds() + \o getTimeZoneOffset() + \o setTime(time) + \o setMilliseconds(ms) + \o setUTCMilliseconds(ms) + \o setSeconds(sec [, ms]) + \o setUTCSeconds(sec [, ms]) + \o setMinutes(min [, sec [, ms]]) + \o setUTCMinutes(min [, sec [, ms]]) + \o setHours(hour [, min [, sec [, ms]]]) + \o setUTCHours(hour [, min [, sec [, ms]]]) + \o setDate(date) + \o setUTCDate(date) + \o setMonth(month [, date]) + \o setUTCMonth(month [, date]) + \o setFullYear(year [, month [, date]]) + \o setUTCFullYear(year [, month [, date]]) + \o toUTCString() + \o toISOString() + \o toJSON() + \endlist + + \section1 RegExp Objects + + \section2 RegExp Prototype Object + + \section3 Function Properties + + \list + \o exec(string) + \o test(string) + \o toString() + \endlist + + \section1 Error Objects + + \section2 Error Prototype Object + + \section3 Value Properties + + \list + \o name + \o message + \endlist + + \section3 Function Properties + + \list + \o toString() + \endlist + + \section1 The JSON Object + + \section2 Function Properties + + \list + \o parse(text [, reviver]) + \o stringify(value [, replacer [, space]]) + \endlist + +*/ diff --git a/doc/src/scripting/qtscriptdebugger-manual.qdoc b/doc/src/scripting/qtscriptdebugger-manual.qdoc new file mode 100644 index 0000000..b9b8442 --- /dev/null +++ b/doc/src/scripting/qtscriptdebugger-manual.qdoc @@ -0,0 +1,422 @@ +/**************************************************************************** +** +** 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$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the Technology Preview License Agreement accompanying +** this package. +** +** 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. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page qtscriptdebugger-manual.html + \title Qt Script Debugger Manual + \brief A manual describing how to use the Qt Script debugger. + + The Qt Script debugger is a tool for debugging script execution in + Qt applications that use Qt Script. Application developers can embed + the debugger into their application through the + QScriptEngineDebugger class. This manual describes how to use the + debugger. We assume that the reader is somewhat familiar with + general debugging concepts and existing debugging tools. + + We assume that the debugger has been integrated into the application + through the QScriptEngineDebugger::standardWindow() + function, which provides the standard debugger configuration. + + \tableofcontents + + \section1 Getting Started + + The following image shows the debugger as created with + \l{QScriptEngineDebugger::}{standardWindow()}: + + \image qtscript-debugger.png Running a script under the Qt Script debugger. + + The debugger will start, i.e., take control over the script's + execution when any of these conditions are met: + + \list + \o The \c{debugger} statement is encountered in the script. + \o Clicking the \gui Interrupt menu item from the \gui Debug + menu in the main window. + \o A breakpoint is reached. + \o An uncaught script exception is thrown. + \endlist + + Once the debugger is started, the execution state can be inspected, + e.g., the value of variables can be queried and the current program + stack shown. New breakpoints can be set. + + The debugger will resume, i.e., give the control back to the script + engine, when the user clicks \gui Continue menu item from the \gui + Debug menu. It will be invoked again if one of the conditions + described in the list above is met. + + \section1 Overview of Debugger Components + + The debugger's functionality is divided into a series of components, + each being a widget that can be shown in the main window of the + debugger. The following table describes each component and how they + relate to each other. + + \table + \header + \o Component + \o Description + \row + \o Console Widget + \o The console widget provides a command-line interface to the + debugger's functionality, and also serves as an interactive script + interpreter. The set of commands and their syntax is inspired by + GDB, the GNU Debugger. Commands and script variables are + auto-completed through the TAB key. + + Any console command that causes a change in the debugger or debugger + target's state will immediately be reflected in the other debugger + components (e.g. breakpoints or local variables changed). + + The console provides a simple and powerful way of manipulating the + script environment. For example, typing "x" and hitting enter will + evaluate "x" in the current stack frame and display the result. + Typing "x = 123" will assign the value 123 to the variable \c{x} in + the current scope (or create a global variable \c{x} if there isn't + one -- scripts evaluated through the console can have arbitrary side + effects, so be careful). + + \row + \o Stack Widget + \o The stack widget shows a backtrace of the script execution state. + Each row represents one frame in the stack. A row contains the + frame index (0 being the inner-most frame), the name of the script function, + and the location (file name and line number). To select a particular + stack frame to inspect, click on its row. + + \row + \o Locals Widget + \o The locals widget shows the variables that are local to the + currently selected stack frame; that is, the properties of the + objects in the scope chain and the \c{this}-object. Objects can be + expanded, so that their properties can be examined, recursively. + Properties whose value has changed are shown in bold font. + + Properties that are not read-only can be edited. Double-click on the + value and type in the new value; the value can be an arbitrary + expression. The expression will be evaluated in the associated stack + frame. While typing, you can press the TAB key to get possible + completions for the expression. + + \row + \o Code Widget + \o The code widget shows the code of the currently selected script. + The widget displays an arrow in the left margin, marking the + code line that is being executed. + Clicking in the margin of a line will cause a breakpoint to be + toggled at that line. A breakpoint has to be set on a line that + contains an actual statement in order to be useful.When an uncaught script exception occurs, the + offending line will be shown with a red background. + + The code widget is read-only; it cannot currently be used to edit + and (re)evaluate scripts. This is however possible from the + command-line interface, see \l{Console Command Reference}. + + \row + \o Scripts Widget + + \o The scripts widget shows the scripts that are currently loaded in + the script engine. Clicking on a script will cause its code to be + shown in the code widget. When a script is no longer referenced by + the debugger target it is removed from the scripts widget. Code + evaluated through QScriptEngine::evaluate() without a name specified, will be + displayed in the widget as Anonymous. + + \row + \o Breakpoints Widget + + \o The breakpoints widget shows all the breakpoints that are set. A + breakpoint can be disabled or enabled by clicking the checkbox next + to the breakpoint's ID (the ID is provided so that the breakpoint + can be manipulated through the console widget as well). + + A condition can be associated with the breakpoint; the condition can + be an arbitrary expression that should evaluate to true or + false. The breakpoint will only be triggered when its location is + reached \bold{and} the condition evaluates to true. + + Similarly, if the breakpoint's ignore-count is set to N, the + breakpoint will be ignored the next N times it is hit. + + A new breakpoint can be set by clicking the New Breakpoint button + and typing in a location of the form <filename>\bold{:}<linenumber>. + The breakpoint location can refer to an already loaded script, or + one that has not been loaded yet. + + \row + \o Debug Output Widget + \o The debug output widget shows messages generated by the print() + script function. Scripts can use the special variables \c{__FILE__} + and \c{__LINE__} to include the current location information in the + messages. + + \row + \o Error Log Widget + \o The error log widget shows error messages that have been generated. + All uncaught exceptions that occur in the engine will appear here. + + \endtable + + \section2 Resuming Script Evaluation + + Script evaluation can be resumed in one of the following ways: + + \list + \o \bold{Continue}: Evaluation will resume normally. + \o \bold{Step Into}: Evaluation will resume until the next statement is reached. + \o \bold{Step Over}: Evaluation will resume until the next statement is reached; + but if the current statement is a function call, the debugger + will treat it as a single statement. + \o \bold{Step Out}: Evaluation will resume until the current function exits and + the next statement is reached. + \o \bold{Run to Cursor}: Run until the statement at the cursor is reached. + \o \bold{Run to New Script}: Run until the first statement of a new script is reached. + \endlist + + In any case, script evaluation can also be stopped due to either of the + following reasons: + + \list + \o A \c{debugger} statement is encountered. + \o A breakpoint is hit. + \o An uncaught script exception occurs. + \endlist + + \section2 Resuming After an Uncaught Exception + + When an uncaught script exception occurs, it is not possible to + continue evaluating the current function normally. However, you can + use the console command \bold{return} to catch the exception and + return a value to the calling function. + + \section1 Console Command Reference + + Note that you can also get help on the available commands by typing + ".help" in the console. + + \section2 Breakpoint-related Commands + + Break points is set + + \section3 break <location> + + Sets a breakpoint at a given code line. + + \code + .break foo.qs:123 + \endcode + + This command sets a breakpoint at \c{foo.qs}, line 123. + + \code + .break 123 + \endcode + + This command sets a breakpoint at line 123 in the current script; the current script + is the script associated with the current stack frame. + + Each breakpoint has a unique identifier (an integer) associated with it. + This identifier is needed by other breakpoint-related commands. + + \section3 clear <location> + + \code + .clear foo.qs:123 + \endcode + + clears (deletes) the breakpoint at \c{foo.qs}, line 123. + + \code + clear 123 + \endcode + + clears (deletes) the breakpoint at line 123 in the current script; + the current script is the script associated with the current stack + frame. + + \section3 condition <breakpoint-id> <expression> + + Sets a condition for a breakpoint. + + \code + .condition 1 i > 42 + \endcode + + specifies that breakpoint 1 should only be triggered if the variable \c{i} + is greater than 42. + + The expression can be an arbitrary one, i.e. it can have + side-effects. It can be any valid QScript conditional + expression. + + \section3 delete <breakpoint-id> + + Deletes a breakpoint, i.e., removes it from the current debugging + session. + + \section3 disable <breakpoint-id> + + Disables a breakpoint. The breakpoint will continue to exist, but + will not stop program execution. + + \section3 enable <breakpoint-id> + + Enables a breakpoint. Breakpoints are enabled by default, so you + only need to use this command if you have disabled to breakpoint + previously. + + \section3 ignore <breakpoint-id> <count> + + Sets the ignore-count of a breakpoint, i.e., the breakpoint will not + stop the program execution unless it have been reached \c count + times. This can, for instance, be useful in loops to stop at a + specific iteration. + + \code + .ignore 1 5 + \endcode + + Specifies that breakpoint 1 should be ignored the next 5 times it is + hit. + + \section3 info breakpoints + + Lists the breakpoints that are set. + + \code + .info breakpoints + \endcode + + \section3 tbreak <location> + + Sets a temporary breakpoint. This command is identical to the + \c{break} command, only the breakpoint will be automatically deleted + the first time it is hit. + + \section2 File-related Commands + + \section3 list <location> + + Lists the contents of a script around a given location, where the + location is given as a line number and, optionally, the name of the + file from which you will print. If only a line number is given, \c + {.list} will use the file of the current stack frame. + + \code + .list foo.qs:125 + \endcode + + When no arguments are given, \c{list} will incrementally list + sections of the current script. + + \section3 info scripts + + Lists the scripts that are currently loaded. + + \section2 Execution-related Commands + + \section3 advance <location> + + Advances execution to a given location. The syntax of the location + is the same as for setting breakpoints. For example: + + \code + .advance foo.qs:125 + \endcode + + \section3 continue + + Continues execution normally, i.e, gives the execution control over + the script back to the QScriptEngine. + + \section3 eval <program> + + Evaluates a program. + + \section3 finish + + Continues execution until the current function exits and the next + statement is reached (i.e., the statement after the call to the + function). + + \section3 interrupt + + Requests that execution should be interrupted. Interruption will + occur as soon as a new script statement is reached. + + \section3 next <count = 1> + + Continues execution until a new statement is reached; but if the + current statement is a function call, the function call will be + treated as a single statement. This will be done \c count times + before execution is stopped; the default is one. + + \section3 return <expression> + + Makes the current frame return to its caller. If \c expression is + given, it will sent as the result of the function (i.e., replacing + the functions return value). \c expression can be any valid QScript + expression. + + \section3 step <count = 1> + + Continues execution until a new statement is reached. If the number + \c count is given as argument, this will be done \c count times + before execution is stopped. As opposed to \l{next <count = 1>}, \c + step will enter functions when encountering a function call + statement. + + \section2 Stack-related Commands + + \section3 backtrace + + Shows a backtrace of the current execution. The trace will list the + function name and its position in the script for each stack frame. + + \section3 down + + Selects the previous (inner) stack frame. The execution will not + return to this frame, but you will get access to its local + variables. + + \section3 frame <index> + + This command moves to the stack frame with the given \c index. The + index of the frame on the top of the stack is 0. Previous frames are + numbered from 1 and upwards (the bottom frame in the stack has the + largest index). + + \section3 info locals + + Lists the variables that are in the scope of the current frame. + + \section3 up + + Selects the next (outer) stack frame. + +*/ diff --git a/doc/src/scripting/qtscriptextensions.qdoc b/doc/src/scripting/qtscriptextensions.qdoc new file mode 100644 index 0000000..431adb0 --- /dev/null +++ b/doc/src/scripting/qtscriptextensions.qdoc @@ -0,0 +1,101 @@ +/**************************************************************************** +** +** 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$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the Technology Preview License Agreement accompanying +** this package. +** +** 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. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page qtscriptextensions.html + \title Creating QtScript Extensions + \brief A guide to creating and using QtScript extensions. + + QtScript extensions can make additional functionality available to scripts + evaluated by a QScriptEngine. Extensions are imported by calling + the QScriptEngine::importExtension() function. + + There are three ways to create an extension: + + \list + \o Subclass QScriptExtensionPlugin and implement the desired functionality. + \o Implement the functionality in a script file. + \o Use a hybrid approach, where part of the functionality is implemented in a + QScriptExtensionPlugin, and part is implemented in a script file. + \endlist + + The (dot-qualified) extension name is used to determine the path (relative to + the application's plugin path) where QScriptEngine will look for the script + file that will initialize the extension; if a file called \c{__init__.js} + (usually located in \c{[application plugin path]/script/foo/}) is + found in the corresponding folder, its contents will be evaluated by the engine + when the extension is imported. + As an example, if the extension is called \c{"foo.bar.baz"}, the engine will look + for \c{__init__.js} in \c{foo/bar/baz}. Additionally, before importing + \c{"foo.bar.baz"}, the engine will ensure that the extensions \c{"foo"} and \c{"foo.bar"} + are imported, locating and evaluating the corresponding \c{__init__.js} + in the same manner (in folders \c{foo} and \c{foo/bar}, respectively). + + The contents of \c{__init__.js} are evaluated in a new QScriptContext, + as if it were the body of a function. The engine's Global Object acts as + the \c{this} object. The following local variables are initially available + to the script: + + \list + \o \bold{__extension__}: The name of the extension (e.g. \c{"foo.bar.baz"}). + \o \bold{__setupPackage__}: A convenience function for setting up a "namespace" in the script environment. A typical application is to call \c{__setupPackage__()} with \c{__extension__} as argument; e.g. \c{__setupPackage__("foo.bar.baz")} would ensure that the object chain represented by the expression \c{foo.bar.baz} exists in the script environment. (This function is semantically equivalent to QScriptExtensionPlugin::setupPackage().) + \o \bold{__postInit__}: By default, this variable is undefined. If you assign a function to it, that function will be called \bold{after} the C++ plugin's initialize() function has been called. You can use this to perform further initialization that depends on e.g. native functions that the C++ plugin registers. + \endlist + + An example of a simple \c{__init__.js}: + + \snippet doc/src/snippets/code/doc_src_qtscriptextensions.js 0 + + QScriptEngine will look for a QScriptExtensionPlugin that provides + the relevant extension by querying each plugin for its keys() + until a match is found. The plugin's initialize() function will be + called \bold{after} the relevant \c{__init__.js} (if any) has been + evaluated. + + Continuining with the example of our imaginary extension \c{"foo.bar.baz"}, + the following steps will be performed by QScriptEngine::importExtension(): + + \list + \o If it exists, \c{foo/__init__.js} is evaluated. + \o If a plugin with \c{"foo"} in its list of keys is found, its initialize() function is called with \c{"foo"} as key. + \o If it exists, \c{foo/bar/__init__.js} is evaluated. + \o If a plugin with \c{"foo.bar"} in its list of keys is found, its initialize() function is called with \c{"foo.bar"} as key. + \o If it exists, \c{foo/bar/baz/__init__.js} is evaluated. + \o If a plugin with "foo.bar.baz" in its list of keys is found, its initialize() function is called with \c{"foo.bar.baz"} as key. + \endlist + + \section1 Static Extensions + + When an extension is compiled and linked into your application as a + static plugin, Qt Script will look for the optional \c{__init__.js} + script in a resource, prefixed by \c{:/qtscriptextension}. For example, + if the extension key is "foo.bar", Qt Script will evaluate the contents + of the file \c{:/qtscriptextension/foo/bar/__init__.js}, if it + exists. Note that if the resource is built into the plugin, you may + need to use the Q_INIT_RESOURCE() macro to initialize the resource + before importing the extension. +*/ diff --git a/doc/src/scripting/scripting.qdoc b/doc/src/scripting/scripting.qdoc new file mode 100644 index 0000000..f882da0 --- /dev/null +++ b/doc/src/scripting/scripting.qdoc @@ -0,0 +1,1877 @@ +/**************************************************************************** +** +** 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$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the Technology Preview License Agreement accompanying +** this package. +** +** 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. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \group script + \title Scripting Classes and Overviews + + \brief Classes that add scripting capabilities to Qt applications. +*/ + +/*! + \page scripting.html + \title Making Applications Scriptable + \ingroup frameworks-technologies + + Qt 4.3 and later provides support for application scripting with ECMAScript. + The following guides and references cover aspects of programming with + ECMAScript and Qt. + + \tableofcontents + + \section1 Scripting Classes + + The following classes add scripting capabilities to Qt applications. + + \annotatedlist script + + \section1 Language Overview + + Qt Script is based on the ECMAScript scripting language, as defined + in standard \l{ECMA-262}. Microsoft's JScript, and Netscape's + JavaScript are also based on the ECMAScript standard. For an + overview of ECMAScript, see the + \l{ECMAScript Reference}{ECMAScript reference}. + If you are not familiar with the ECMAScript language, there are + several existing tutorials and books that cover this subject, such + as \l{JavaScript: The Definitive Guide}. + + Existing users of \l{Qt Script for Applications (QSA)} may find the + \l{Moving from QSA to Qt Script} document useful when porting + QSA scripts to Qt Script. + + \section1 Basic Usage + + To evaluate script code, you create a QScriptEngine and call its + evaluate() function, passing the script code (text) to evaluate + as argument. + + \snippet doc/src/snippets/qtscript/evaluation/main.cpp 0 + + The return value will be the result of the evaluation (represented + as a QScriptValue 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/qtscript/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 QScriptEngine::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/qtscript/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(). + + The \l{QScriptEngine::}{newQObject()} function accepts two additional + optional arguments: one is the ownership mode, and the other is a + collection of options that allow you to control certain aspects of how + the QScriptValue that wraps the QObject should behave. We will come + back to the usage of these arguments later. + + \section2 Using Signals and Slots + + Qt Script adapts Qt's central \l{Signals and Slots} feature for + scripting. There are three principal ways to use signals and slots + with Qt Script: + + \list + \i \bold{Hybrid C++/script}: C++ application code connects a + signal to a script function. The script function can, for example, be + a function that the user has typed in, or one that you have read from a + file. This approach is useful if you have a QObject but don't want + to expose the object itself to the scripting environment; you just + want a script to be able to define how a signal should be reacted + to, and leave it up to the C++ side of your application to establish + the connection. + + \i \bold{Hybrid script/C++}: A script can connect signals and slots + to establish connections between pre-defined objects that the + application exposes to the scripting environment. In this scenario, + the slots themselves are still written in C++, but the definition of + the connections is fully dynamic (script-defined). + + \i \bold{Purely script-defined}: A script can both define signal + handler functions (effectively "slots written in Qt Script"), + \e{and} set up the connections that utilize those handlers. For + example, a script can define a function that will handle the + QLineEdit::returnPressed() signal, and then connect that signal to the + script function. + \endlist + + Use the qScriptConnect() function to connect a C++ signal to a + script function. In the following example a script signal handler is + defined that will handle the QLineEdit::textChanged() signal: + + \snippet doc/src/snippets/code/doc_src_qtscript.cpp 47 + + The first two arguments to qScriptConnect() are the same + as you would pass to QObject::connect() to establish a normal C++ + connection. The third argument is the script object that will act + as the \c this object when the signal handler is invoked; in the above + example we pass an invalid script value, so the \c this object will + be the Global Object. The fourth argument is the script function + ("slot") itself. The following example shows how the \c this argument + can be put to use: + + \snippet doc/src/snippets/code/doc_src_qtscript.cpp 48 + + We create two QLineEdit objects and define a single signal handler + function. The connections use the same handler function, but the + function will be invoked with a different \c this object depending on + which object's signal was triggered, so the output of the print() + statement will be different for each. + + In script code, Qt Script uses a different syntax for connecting to + and disconnecting from signals than the familiar C++ syntax; i.e., + QObject::connect(). + To connect to a signal, you reference the relevant signal as a property + of the sender object, and invoke its \c{connect()} function. There + are three overloads of \c{connect()}, each with a corresponding + \c{disconnect()} overload. The following subsections describe these + three forms. + + \section3 Signal to Function Connections + + \c{connect(function)} + + In this form of connection, the argument to \c{connect()} is the + function to connect to the signal. + + \snippet doc/src/snippets/code/doc_src_qtscript.js 2 + + The argument can be a Qt Script function, as in the above + example, or it can be a QObject slot, as in + the following example: + + \snippet doc/src/snippets/code/doc_src_qtscript.js 3 + + When the argument is a QObject slot, the argument types of the + signal and slot do not necessarily have to be compatible; + QtScript will, if necessary, perform conversion of the signal + arguments to match the argument types of the slot. + + To disconnect from a signal, you invoke the signal's + \c{disconnect()} function, passing the function to disconnect + as argument: + + \snippet doc/src/snippets/code/doc_src_qtscript.js 4 + + When a script function is invoked in response to a signal, the + \c this object will be the Global Object. + + \section3 Signal to Member Function Connections + + \c{connect(thisObject, function)} + + In this form of the \c{connect()} function, the first argument + is the object that will be bound to the variable, \c this, when + the function specified using the second argument is invoked. + + If you have a push button in a form, you typically want to do + something involving the form in response to the button's + \c{clicked} signal; passing the form as the \c this object + makes sense in such a case. + + \snippet doc/src/snippets/code/doc_src_qtscript.js 5 + + To disconnect from the signal, pass the same arguments to \c{disconnect()}: + + \snippet doc/src/snippets/code/doc_src_qtscript.js 6 + + \section3 Signal to Named Member Function Connections + + \c{connect(thisObject, functionName)} + + In this form of the \c{connect()} function, the first argument is + the object that will be bound to the variable, \c this, when + a function is invoked in response to the signal. The second argument + specifies the name of a function that is connected to the signal, + and this refers to a member function of the object passed as the + first argument (\c thisObject in the above scheme). + + Note that the function is resolved when the connection is made, not + when the signal is emitted. + + \snippet doc/src/snippets/code/doc_src_qtscript.js 7 + + To disconnect from the signal, pass the same arguments to \c{disconnect()}: + + \snippet doc/src/snippets/code/doc_src_qtscript.js 8 + + \section3 Error Handling + + When \c{connect()} or \c{disconnect()} succeeds, the function will + return \c{undefined}; otherwise, it will throw a script exception. + You can obtain an error message from the resulting \c{Error} object. + Example: + + \snippet doc/src/snippets/code/doc_src_qtscript.js 9 + + \section3 Emitting Signals from Scripts + + To emit a signal from script code, you simply invoke the signal + function, passing the relevant arguments: + + \snippet doc/src/snippets/code/doc_src_qtscript.js 10 + + It is currently not possible to define a new signal in a script; + i.e., all signals must be defined by C++ classes. + + \section3 Overloaded Signals and Slots + + When a signal or slot is overloaded, QtScript will attempt to + pick the right overload based on the actual types of the QScriptValue arguments + involved in the function invocation. For example, if your class has slots + \c{myOverloadedSlot(int)} and \c{myOverloadedSlot(QString)}, the following + script code will behave reasonably: + + \snippet doc/src/snippets/code/doc_src_qtscript.js 11 + + You can specify a particular overload by using array-style property access + with the \l{QMetaObject::normalizedSignature()}{normalized signature} of + the C++ function as the property name: + + \snippet doc/src/snippets/code/doc_src_qtscript.js 12 + + If the overloads have different number of arguments, QtScript will + pick the overload with the argument count that best matches the + actual number of arguments passed to the slot. + + For overloaded signals, Qt Script will throw an error if you try to connect + to the signal by name; you have to refer to the signal with the full + normalized signature of the particular overload you want to connect to. + + \section2 Accessing Properties + + The properties of the QObject are available as properties + of the corresponding QtScript object. When you manipulate + a property in script code, the C++ get/set method for that + property will automatically be invoked. For example, if your + C++ class has a property declared as follows: + + \snippet doc/src/snippets/code/doc_src_qtscript.cpp 13 + + then script code can do things like the following: + + \snippet doc/src/snippets/code/doc_src_qtscript.js 14 + + \section2 Accessing Child QObjects + + Every named child of the QObject (that is, for which + QObject::objectName() is not an empty string) is by default available as + a property of the QtScript wrapper object. For example, + if you have a QDialog with a child widget whose \c{objectName} property is + \c{"okButton"}, you can access this object in script code through + the expression + + \snippet doc/src/snippets/code/doc_src_qtscript.js 15 + + Since \c{objectName} is itself a Q_PROPERTY, you can manipulate + the name in script code to, for example, rename an object: + + \snippet doc/src/snippets/code/doc_src_qtscript.js 16 + + You can also use the functions \c{findChild()} and \c{findChildren()} + to find children. These two functions behave identically to + QObject::findChild() and QObject::findChildren(), respectively. + + For example, we can use these functions to find objects using strings + and regular expressions: + + \snippet doc/src/snippets/code/doc_src_qtscript.js 17 + + You typically want to use \c{findChild()} when manipulating a form + that uses nested layouts; that way the script is isolated from the + details about which particular layout a widget is located in. + + \section2 Controlling QObject Ownership + + Qt Script uses garbage collection to reclaim memory used by script + objects when they are no longer needed; an object's memory can be + automatically reclaimed when it is no longer referenced anywhere in + the scripting environment. Qt Script lets you control what happens + to the underlying C++ QObject when the wrapper object is reclaimed + (i.e., whether the QObject is deleted or not); you do this when you + create an object by passing an ownership mode as the second argument + to QScriptEngine::newQObject(). + + Knowing how Qt Script deals with ownership is important, since it can + help you avoid situations where a C++ object isn't deleted when it + should be (causing memory leaks), or where a C++ object \e{is} + deleted when it shouldn't be (typically causing a crash if C++ code + later tries to access that object). + + \section3 Qt Ownership + + By default, the script engine does not take ownership of the + QObject that is passed to QScriptEngine::newQObject(); the object + is managed according to Qt's object ownership (see + \l{Object Trees & Ownership}). This mode is appropriate + when, for example, you are wrapping C++ objects that are part of + your application's core; that is, they should persist regardless of + what happens in the scripting environment. Another way of stating + this is that the C++ objects should outlive the script engine. + + \section3 Script Ownership + + Specifying QScriptEngine::ScriptOwnership as the ownership mode + will cause the script engine to take full ownership of the QObject + and delete it when it determines that it is safe to do so + (i.e., when there are no more references to it in script code). + This ownership mode is appropriate if the QObject does not have a + parent object, and/or the QObject is created in the context of the + script engine and is not intended to outlive the script engine. + + For example, a constructor function that constructs QObjects + only to be used in the script environment is a good candidate: + + \snippet doc/src/snippets/code/doc_src_qtscript.cpp 18 + + \section3 Auto-Ownership + + With QScriptEngine::AutoOwnership the ownership is based on whether + the QObject has a parent or not. + If the QtScript garbage collector finds that the QObject is no + longer referenced within the script environment, the QObject will + be deleted \e{only} if it does not have a parent. + + \section3 What Happens When Someone Else Deletes the QObject? + + It is possible that a wrapped QObject is deleted outside of + Qt Script's control; i.e., without regard to the ownership mode + specified. In this case, the wrapper object will still + be an object (unlike the C++ pointer it wraps, the script object + won't become null). Any attempt to access properties of the script + object will, however, result in a script exception being thrown. + + Note that QScriptValue::isQObject() will still return true for a + deleted QObject, since it tests the type of the script object, not + whether the internal pointer is non-null. In other words, if + QScriptValue::isQObject() returns true but QScriptValue::toQObject() + returns a null pointer, this indicates that the QObject has been + deleted outside of Qt Script (perhaps accidentally). + + \section2 Customizing Access to the QObject + + QScriptEngine::newQObject() can take a third argument which allows + you to control various aspects of the access to the QObject through + the QtScript wrapper object it returns. + + QScriptEngine::ExcludeChildObjects specifies that child objects of + the QObject should not appear as properties of the wrapper object. + + QScriptEngine::ExcludeSuperClassProperties and + QScriptEngine::ExcludeSuperClassMethods can be used to avoid + exposing members that are inherited from the QObject's superclass. + This is useful for defining a "pure" interface where inherited members + don't make sense from a scripting perspective; e.g., you don't want + script authors to be able to change the \c{objectName} property of + the object or invoke the \c{deleteLater()} slot. + + QScriptEngine::AutoCreateDynamicProperties specifies that properties + that don't already exist in the QObject should be created as dynamic + properties of the QObject, rather than as properties of the QtScript + wrapper object. If you want new properties to truly become persistent + properties of the QObject, rather than properties that are destroyed + along with the wrapper object (and that aren't shared if the QObject + is wrapped multiple times with QScriptEngine::newQObject()), you + should use this option. + + QScriptEngine::SkipMethodsInEnumeration specifies that signals and + slots should be skipped when enumerating the properties of the QObject + wrapper in a for-in script statement. This is useful when defining + prototype objects, since by convention function properties of + prototypes should not be enumerable. + + \section2 Making a QObject-based Class New-able from a Script + + The QScriptEngine::newQObject() function is used to wrap an + existing QObject instance, so that it can be made available to + scripts. A different scenario is that you want scripts to be + able to construct new objects, not just access existing ones. + + The Qt meta-type system currently does not provide dynamic + binding of constructors for QObject-based classes. If you want to + make such a class new-able from scripts, Qt Script can generate + a reasonable script constructor for you; see + QScriptEngine::scriptValueFromQMetaObject(). + + You can also use QScriptEngine::newFunction() to wrap your own + factory function, and add it to the script environment; see + QScriptEngine::newQMetaObject() for an example. + + \section2 Enum Values + + Values for enums declared with Q_ENUMS are not available as + properties of individual wrapper objects; rather, they are + properties of the QMetaObject wrapper object that can be created + with QScriptEngine::newQMetaObject(). + + \section1 Conversion Between QtScript and C++ Types + + QtScript will perform type conversion when a value needs to be + converted from the script side to the C++ side or vice versa; for + instance, when a C++ signal triggers a script function, when + you access a QObject property in script code, or when + you call QScriptEngine::toScriptValue() or + QScriptEngine::fromScriptValue() in C++. QtScript provides default + conversion operations for many of the built-in Qt types. You can + change the conversion operation for a type (including your custom + C++ types) by registering your own conversion functions with + qScriptRegisterMetaType(). + + \section2 Default Conversion from Qt Script to C++ + + The following table describes the default conversion from a + QScriptValue to a C++ type. + + \table 80% + \header \o C++ Type \o Default Conversion + \row \o bool \o QScriptValue::toBool() + \row \o int \o QScriptValue::toInt32() + \row \o uint \o QScriptValue::toUInt32() + \row \o float \o float(QScriptValue::toNumber()) + \row \o double \o QScriptValue::toNumber() + \row \o short \o short(QScriptValue::toInt32()) + \row \o ushort \o QScriptValue::toUInt16() + \row \o char \o char(QScriptValue::toInt32()) + \row \o uchar \o unsigned char(QScriptValue::toInt32()) + \row \o qlonglong \o qlonglong(QScriptValue::toInteger()) + \row \o qulonglong \o qulonglong(QScriptValue::toInteger()) + \row \o QString \o An empty string if the QScriptValue is null + or undefined; QScriptValue::toString() otherwise. + \row \o QDateTime \o QScriptValue::toDateTime() + \row \o QDate \o QScriptValue::toDateTime().date() + \row \o QRegExp \o QScriptValue::toRegExp() + \row \o QObject* \o QScriptValue::toQObject() + \row \o QWidget* \o QScriptValue::toQObject() + \row \o QVariant \o QScriptValue::toVariant() + \row \o QChar \o If the QScriptValue is a string, the result + is the first character of the string, or a null QChar + if the string is empty; otherwise, the result is a QChar + constructed from the unicode obtained by converting the + QScriptValue to a \c{ushort}. + \row \o QStringList \o If the QScriptValue is an array, the + result is a QStringList constructed from the result of + QScriptValue::toString() for each array element; otherwise, + the result is an empty QStringList. + \row \o QVariantList \o If the QScriptValue is an array, the result + is a QVariantList constructed from the result of + QScriptValue::toVariant() for each array element; otherwise, + the result is an empty QVariantList. + \row \o QVariantMap \o If the QScriptValue is an object, the result + is a QVariantMap with a (key, value) pair of the form + (propertyName, propertyValue.toVariant()) for each property, + using QScriptValueIterator to iterate over the object's + properties. + \row \o QObjectList \o If the QScriptValue is an array, the result + is a QObjectList constructed from the result of + QScriptValue::toQObject() for each array element; otherwise, + the result is an empty QObjectList. + \row \o QList<int> \o If the QScriptValue is an array, the result is + a QList<int> constructed from the result of + QScriptValue::toInt32() for each array element; otherwise, + the result is an empty QList<int>. + \endtable + + Additionally, QtScript will handle the following cases: + + \list + \i If the QScriptValue is a QObject and the target type name ends with + \c * (i.e., it is a pointer), the QObject pointer will be cast to the + target type with qobject_cast(). + \i If the QScriptValue is a QVariant and the target type name ends with + \c * (i.e., it is a pointer), and the \l{QVariant::userType()}{userType()} + of the QVariant is the type that the target type points to, the result + is a pointer to the QVariant's data. + \i If the QScriptValue is a QVariant and it can be converted to the + target type (according to QVariant::canConvert()), the QVariant will + be cast to the target type with qvariant_cast(). + \endlist + + \section2 Default Conversion from C++ to Qt Script + + The following table describes the default behavior when a QScriptValue is + constructed from a C++ type: + + \table 80% + \header \o C++ Type \o Default Construction + \row \o void \o QScriptEngine::undefinedValue() + \row \o bool \o QScriptValue(engine, value) + \row \o int \o QScriptValue(engine, value) + \row \o uint \o QScriptValue(engine, value) + \row \o float \o QScriptValue(engine, value) + \row \o double \o QScriptValue(engine, value) + \row \o short \o QScriptValue(engine, value) + \row \o ushort \o QScriptValue(engine, value) + \row \o char \o QScriptValue(engine, value) + \row \o uchar \o QScriptValue(engine, value) + \row \o QString \o QScriptValue(engine, value) + \row \o qlonglong \o QScriptValue(engine, qsreal(value)). Note that + the conversion may lead to loss of precision, since not all + 64-bit integers can be represented using the qsreal type. + \row \o qulonglong \o QScriptValue(engine, qsreal(value)). Note that + the conversion may lead to loss of precision, since not all + 64-bit unsigned integers can be represented using the qsreal + type. + \row \o QChar \o QScriptValue(this, value.unicode()) + \row \o QDateTime \o \l{QScriptEngine::newDate()}{QScriptEngine::newDate}(value) + \row \o QDate \o \l{QScriptEngine::newDate()}{QScriptEngine::newDate}(value) + \row \o QRegExp \o \l{QScriptEngine::newRegExp()}{QScriptEngine::newRegExp}(value) + \row \o QObject* \o \l{QScriptEngine::newQObject()}{QScriptEngine::newQObject}(value) + \row \o QWidget* \o \l{QScriptEngine::newQObject()}{QScriptEngine::newQObject}(value) + \row \o QVariant \o \l{QScriptEngine::newVariant()}{QScriptEngine::newVariant}(value) + \row \o QStringList \o A new script array (created with + QScriptEngine::newArray()), whose elements are created using + the QScriptValue(QScriptEngine *, QString) constructor for + each element of the list. + \row \o QVariantList \o A new script array (created with + QScriptEngine::newArray()), whose elements are created using + QScriptEngine::newVariant() for each element of the list. + \row \o QVariantMap \o A new script object (created with + QScriptEngine::newObject()), whose properties are initialized + according to the (key, value) pairs of the map. + \row \o QObjectList \o A new script array (created with + QScriptEngine::newArray()), whose elements are created using + QScriptEngine::newQObject() for each element of the list. + \row \o QList<int> \o A new script array (created with + QScriptEngine::newArray()), whose elements are created using + the QScriptValue(QScriptEngine *, int) constructor for each + element of the list. + \endtable + + Other types (including custom types) will be wrapped using + QScriptEngine::newVariant(). For null pointers of any type, the + result is QScriptEngine::nullValue(). + + \section1 How to Design and Implement Application Objects + + This section explains how to implement application objects and + provides the necessary technical background material. + + \section2 Making a C++ object available to Scripts Written in QtScript + + Making C++ classes and objects available to a scripting language is + not trivial because scripting languages tend to be more dynamic than + C++, and it must be possible to introspect objects (query information + such as function names, function signatures, properties, etc., at + run-time). Standard C++ does not provide features for this. + + We can achieve the functionality we want by extending C++, using + C++'s own facilities so our code is still standard C++. The Qt + meta-object system provides the necessary additional functionality. + It allows us to write using an extended C++ syntax, but converts this + into standard C++ using a small utility program called \l{moc} + (Meta-Object Compiler). Classes that wish to take advantage of the + meta-object facilities are either subclasses of QObject, or use the + \c{Q_OBJECT} macro. Qt has used this approach for many years and it has + proven to be solid and reliable. QtScript uses this meta-object + technology to provide scripters with dynamic access to C++ classes + and objects. + + To completely understand how to make C++ objects available to Qt + Script, some basic knowledge of the Qt meta-object system is very + helpful. We recommend that you read about the Qt \l{Object Model} + and \l{The Meta-Object System}, which are useful for understanding + how to implement application objects. + + However, this knowledge is not essential in the simplest cases. + To make an object available in QtScript, it must derive from + QObject. All classes which derive from QObject can be introspected + and can provide the information needed by the scripting engine at + run-time; e.g., class name, functions, signatures. Because we obtain + the information we need about classes dynamically at run-time, there + is no need to write wrappers for QObject derived classes. + + \section2 Making C++ Class Member Functions Available in QtScript + + The meta-object system also makes information about signals and slots + dynamically available at run-time. By default, for QObject subclasses, + only the signals and slots are automatically made available to scripts. + This is very convenient because, in practice, we normally only want to + make specially chosen functions available to scripters. When you create + a QObject subclass, make sure that the functions you want to expose to + QtScript are public slots. + + For example, the following class definition enables scripting only for + certain functions: + + \snippet doc/src/snippets/code/doc_src_qtscript.cpp 19 + + In the example above, aNonScriptableFunction() is not declared as a + slot, so it will not be available in QtScript. The other three + functions will automatically be made available in QtScript because + they are declared in the \c{public slots} section of the class + definition. + + It is possible to make any function script-invokable by specifying + the \c{Q_INVOKABLE} modifier when declaring the function: + + \snippet doc/src/snippets/code/doc_src_qtscript.cpp 20 + + Once declared with \c{Q_INVOKABLE}, the method can be invoked from + QtScript code just as if it were a slot. Although such a method is + not a slot, you can still specify it as the target function in a + call to \c{connect()} in script code; \c{connect()} accepts both + native and non-native functions as targets. + + As discussed in \l{Default Conversion from Qt Script to C++}, Qt + Script handles conversion for many C++ types. If your function takes + arguments for which Qt Script does not handle conversion, you need + to supply conversion functions. This is done using the + qScriptRegisterMetaType() function. + + \section2 Making C++ Class Properties Available in QtScript + + In the previous example, if we wanted to get or set a property using + QtScript we would have to write code like the following: + + \snippet doc/src/snippets/code/doc_src_qtscript.js 21 + + Scripting languages often provide a property syntax to modify and + retrieve properties (in our case the enabled state) of an + object. Many script programmers would want to write the above code + like this: + + \snippet doc/src/snippets/code/doc_src_qtscript.js 22 + + To make this possible, you must define properties in the C++ QObject + subclass. For example, the following \c MyObject class declaration + declares a boolean property called \c enabled, which uses the function + \c{setEnabled(bool)} as its setter function and \c{isEnabled()} as its + getter function: + + \snippet doc/src/snippets/code/doc_src_qtscript.cpp 23 + + The only difference from the original code is the use of the macro + \c{Q_PROPERTY}, which takes the type and name of the property, and + the names of the setter and getter functions as arguments. + + If you don't want a property of your class to be accessible in + QtScript, you set the \c{SCRIPTABLE} attribute to \c false when + declaring the property; by default, the \c{SCRIPTABLE} attribute is + \c true. For example: + + \snippet doc/src/snippets/code/doc_src_qtscript.cpp 24 + + \section2 Reacting to C++ Objects Signals in Scripts + + In the Qt object model, signals are used as a notification mechanism + between QObjects. This means one object can connect a signal to + another object's slot and, every time the signal is emitted, the slot + is called. This connection is established using the QObject::connect() + function. + + The signals and slots mechanism is also available to QtScript + programmers. The code to declare a signal in C++ is the same, + regardless of whether the signal will be connected to a slot in C++ + or in QtScript. + + \snippet doc/src/snippets/code/doc_src_qtscript.cpp 25 + + The only change we have made to the code in the previous section is + to declare a signals section with the relevant signal. Now, the + script writer can define a function and connect to the object like + this: + + \snippet doc/src/snippets/code/doc_src_qtscript.js 26 + + \section2 Design of Application Objects + + The previous section described how to implement C++ objects which + can be used in QtScript. Application objects are the same kind of + objects, and they make your application's functionality available to + QtScript scripters. Since the C++ application is already written + in Qt, many objects are already QObjects. The easiest approach would + be to simply add all these QObjects as application objects to the + scripting engine. For small applications this might be sufficient, + but for larger applications this is probably not the right + approach. The problem is that this method reveals too much of the + internal API and gives script programmers access to application + internals which should not be exposed. + + Generally, the best way of making application functionality available + to scripters is to code some QObjects which define the applications + public API using signals, slots, and properties. This gives you + complete control of the functionality made available by the + application. The implementations of these objects simply call the + functions in the application which do the real work. So, instead of + making all your QObjects available to the scripting engine, just add + the wrapper QObjects. + + \section3 Returning QObject Pointers + + If you have a slot that returns a QObject pointer, you should note + that, by default, Qt Script only handles conversion of the types + QObject* and QWidget*. This means that if your slot is declared + with a signature like "MyObject* getMyObject()", QtScript doesn't + automatically know that MyObject* should be handled in the same way + as QObject* and QWidget*. The simplest way to solve this is to only + use QObject* and QWidget* in the method signatures of your scripting + interface. + + Alternatively, you can register conversion functions for your custom + type with the qScriptRegisterMetaType() function. In this way, you + can preserve the precise typing in your C++ declarations, while + still allowing pointers to your custom objects to flow seamlessly + between C++ and scripts. Example: + + \snippet doc/src/snippets/code/doc_src_qtscript.cpp 43 + + \section1 Function Objects and Native Functions + + In Qt Script, functions are first-class values; they are objects that + can have properties of their own, just like any other type of + object. They can be stored in variables and passed as arguments to + other functions. Knowing how function calls in Qt Script behave is + useful when you want to define and use your own script functions. + This section discusses this matter, and also explains how you can + implement native functions; that is, Qt Script functions written in + C++, as opposed to functions written in the scripting language + itself. Even if you will be relying mostly on the dynamic QObject + binding that Qt Script provides, knowing about these powerful + concepts and techniques is important to understand what's actually + going on when script functions are executed. + + \section2 Calling a Qt Script Function from C++ + + Calling a Qt Script function from C++ is achieved with the + QScriptValue::call() function. A typical scenario is that you evaluate a + script that defines a function, and at some point you want to call that + function from C++, perhaps passing it some arguments, and then handle the + result. The following script defines a Qt Script object that has a + toKelvin() function: + + \snippet doc/src/snippets/code/doc_src_qtscript.js 90 + + The toKelvin() function takes a temperature in Kelvin as argument, and + returns the temperature converted to Celsius. The following snippet shows + how the toKelvin() function might be obtained and called from C++: + + \snippet doc/src/snippets/code/doc_src_qtscript.cpp 91 + + If a script defines a global function, you can access the function as a + property of QScriptEngine::globalObject(). For example, the following script + defines a global function add(): + + \snippet doc/src/snippets/code/doc_src_qtscript.js 56 + + C++ code might call the add() function as follows: + + \snippet doc/src/snippets/code/doc_src_qtscript.cpp 92 + + As already mentioned, functions are just values in Qt Script; a function by + itself is not "tied to" a particular object. This is why you have to specify + a \c{this} object (the first argument to QScriptValue::call()) that the + function should be applied to. + + If the function is supposed to act as a method (i.e. it can only be applied + to a certain class of objects), it is up to the function itself to check + that it is being called with a compatible \c{this} object. + + Passing an invalid QScriptValue as the \c{this} argument to + QScriptValue::call() indicates that the Global Object should be used as the + \c{this} object; in other words, that the function should be invoked as a + global function. + + \section2 The \c this Object + + When a Qt Script function is invoked from a script, the \e{way} in which it + is invoked determines the \c this object when the function body is executed, + as the following script example illustrates: + + \snippet doc/src/snippets/code/doc_src_qtscript.js 49 + + An important thing to note is that in Qt Script, unlike C++ and Java, the + \c this object is not part of the execution scope. This means that + member functions (i.e., functions that operate on \c this) must always + use the \c this keyword to access the object's properties. For example, + the following script probably doesn't do what you want: + + \snippet doc/src/snippets/code/doc_src_qtscript.js 50 + + You will get a reference error saying that 'a is not defined' or, worse, + two totally unrelated global variables \c a and \c b will be used to + perform the computation, if they exist. Instead, the script should look + like this: + + \snippet doc/src/snippets/code/doc_src_qtscript.js 51 + + Accidentally omitting the \c this keyword is a typical source of + error for programmers who are used to the scoping rules of C++ and Java. + + \section2 Wrapping a Native Function + + Qt Script provides QScriptEngine::newFunction() as a way of wrapping a + C++ function pointer; this enables you to implement a function in + C++ and add it to the script environment, so that scripts can invoke + your function as if it were a "normal" script function. Here is how the + previous \c{getProperty()} function can be written in C++: + + \snippet doc/src/snippets/code/doc_src_qtscript.cpp 52 + + Call QScriptEngine::newFunction() to wrap the function. This will + produce a special type of function object that carries a pointer to + the C++ function internally. Once the resulting wrapper has been + added to the scripting environment (e.g., by setting it as a property + of the Global Object), scripts can call the function without having + to know nor care that it is, in fact, a native function. + + Note that the name of the C++ function doesn't matter in the + scripting sense; the name by which the function is invoked by + scripts depends only on what you call the script object property + in which you store the function wrapper. + + It is currently not possible to wrap member functions; i.e., methods + of a C++ class that require a \c this object. + + \section2 The QScriptContext Object + + A QScriptContext holds all the state associated with a particular + invocation of your function. Through the QScriptContext, you can: + \list + \i Get the arguments that were passed to the function. + \i Get the \c this object. + \i Find out whether the function was called with the \c new operator + (the significance of this will be explained later). + \i Throw a script error. + \i Get the function object that's being invoked. + \i Get the activation object (the object used to hold local variables). + \endlist + + The following sections explain how to make use of this + functionality. + + \section2 Processing Function Arguments + + Two things are worth noting about function arguments: + + \list 1 + \o Any script function \mdash including native functions \mdash can + be invoked with any number of arguments. This means that it is up to + the function itself to check the argument count if necessary, and act + accordingly (e.g., throw an error if the number of arguments is + too large, or prepare a default value if the number is too small). + \o A value of any type can be supplied as an argument to any + function. This means that it is up to you to check the type of the + arguments if necessary, and act accordingly (e.g., throw an error + if an argument is not an object of a certain type). + \endlist + + In summary: Qt Script does not automatically enforce any constraints on the + number or type of arguments involved in a function call. + + \section3 Formal Parameters and the Arguments Object + + A native Qt Script function is analogous to a script function that defines no + formal parameters and only uses the built-in \c arguments variable to + process its arguments. To see this, let's first consider how a + script would normally define an \c{add()} function that takes two + arguments, adds them together and returns the result: + + \snippet doc/src/snippets/code/doc_src_qtscript.js 56 + + When a script function is defined with formal parameters, their + names can be viewed as mere aliases of properties of the \c + arguments object; for example, in the \c{add(a, b)} definition's + function body, \c a and \c arguments[0] refer to the same + variable. This means that the \c{add()} function can equivalently be + written like this: + + \snippet doc/src/snippets/code/doc_src_qtscript.js 57 + + This latter form closely matches what a native implementation + typically looks like: + + \snippet doc/src/snippets/code/doc_src_qtscript.cpp 58 + + \section3 Checking the Number of Arguments + + Again, remember that the presence (or lack) of formal parameter + names in a function definition does not affect how the function + may be invoked; \c{add(1, 2, 3)} is allowed by the engine, as is + \c{add(42)}. In the case of the \c {add()} function, the function + really needs two arguments in order to do something useful. This + can be expressed by the script definition as follows: + + \snippet doc/src/snippets/code/doc_src_qtscript.js 59 + + This would result in an error being thrown if a script invokes + \c{add()} with anything other than two arguments. The native + function can be modified to perform the same check: + + \snippet doc/src/snippets/code/doc_src_qtscript.cpp 62 + + \section3 Checking the Types of Arguments + + In addition to expecting a certain number of arguments, a function might + expect that those arguments are of certain types (e.g., that the first + argument is a number and that the second is a string). Such a function + should explicitly check the type of arguments and/or perform a conversion, + or throw an error if the type of an argument is incompatible. + + As it is, the native implementation of \c{add()} shown above doesn't + have the exact same semantics as the script counterpart; this is + because the behavior of the Qt Script \c{+} operator depends on the + types of its operands (for example, if one of the operands is a string, + string concatenation is performed). To give the script function + stricter semantics (namely, that it should only add numeric + operands), the argument types can be tested: + + \snippet doc/src/snippets/code/doc_src_qtscript.js 60 + + Then an invocation like \c{add("foo", new Array())} will + cause an error to be thrown. + + The C++ version can call QScriptValue::isNumber() to perform similar + tests: + + \snippet doc/src/snippets/code/doc_src_qtscript.cpp 63 + + A less strict script implementation might settle for performing an + explicit to-number conversion before applying the \c{+} operator: + + \snippet doc/src/snippets/code/doc_src_qtscript.js 61 + + In a native implementation, this is equivalent to calling + QScriptValue::toNumber() without performing any type test first, + since QScriptValue::toNumber() will automatically perform a type + conversion if necessary. + + To check if an argument is of a certain object type (class), + scripts can use the \c instanceof operator (e.g., \c{"arguments[0] + instanceof Array"} evaluates to true if the first argument is an + Array object); native functions can call QScriptValue::instanceOf(). + + To check if an argument is of a custom C++ type, you typically use + qscriptvalue_cast() and check if the result is valid. For object types, + this means casting to a pointer and checking if it is non-zero; for + value types, the class should have an \c{isNull()}, \c{isValid()} + or similar method. Alternatively, since most custom types are + transported in \l{QVariant}s, you can check if the script value is a + QVariant using QScriptValue::isVariant(), and then check if the + QVariant can be converted to your type using QVariant::canConvert(). + + \section3 Functions with Variable Numbers of Arguments + + Because of the presence of the built-in \c arguments object, + implementing functions that take a variable number of arguments + is simple. In fact, as we have seen, in the technical sense \e{all} + Qt Script functions can be seen as variable-argument functions. + As an example, consider a concat() function that takes an arbitrary + number of arguments, converts the arguments to their string + representation and concatenates the results; for example, + \c{concat("Qt", " ", "Script ", 101)} would return "Qt Script 101". + A script definition of \c{concat()} might look like this: + + \snippet doc/src/snippets/code/doc_src_qtscript.js 64 + + Here is an equivalent native implementation: + + \snippet doc/src/snippets/code/doc_src_qtscript.cpp 65 + + A second use case for a variable number of arguments is to implement + optional arguments. Here's how a script definition typically does + it: + + \snippet doc/src/snippets/code/doc_src_qtscript.js 66 + + And here's the native equivalent: + + \snippet doc/src/snippets/code/doc_src_qtscript.cpp 67 + + A third use case for a variable number of arguments is to simulate + C++ overloads. This involves checking the number of arguments and/or + their type at the beginning of the function body (as already shown), + and acting accordingly. It might be worth thinking twice before + doing this, and instead favor unique function names; e.g., having + separate \c{processNumber(number)} and \c{processString(string)} + functions rather than a generic \c{process(anything)} function. + On the caller side, this makes it harder for scripts to accidentally + call the wrong overload (since they don't know or don't comprehend + your custom sophisticated overloading resolution rules), and on the + callee side, you avoid the need for potentially complex (read: + error-prone) checks to resolve ambiguity. + + \section3 Accessing the Arguments Object + + Most native functions use the QScriptContext::argument() function to + access function arguments. However, it is also possible to access + the built-in \c arguments object itself (the one referred to by the + \c arguments variable in script code), by calling the + QScriptContext::argumentsObject() function. This has three principal + applications: + + \list + \o The \c arguments object can be used to easily forward a function + call to another function. In script code, this is what it + typically looks like: + + \snippet doc/src/snippets/code/doc_src_qtscript.js 68 + + For example, \c{foo(10, 20, 30)} would result in the \c{foo()} function + executing the equivalent of \c{bar(10, 20, 30)}. This is useful if + you want to perform some special pre- or post-processing when + calling a function (e.g., to log the call to \c{bar()} without having + to modify the \c{bar()} function itself, like the above example), or if + you want to call a "base implementation" from a prototype + function that has the exact same "signature". In C++, the forwarding + function might look like this: + + \snippet doc/src/snippets/code/doc_src_qtscript.cpp 69 + + \o The arguments object can serve as input to a QScriptValueIterator, + providing a generic way to iterate over the arguments. A debugger + might use this to display the arguments object in a general purpose + "Qt Script Object Explorer", for example. + + \o The arguments object can be serialized (e.g., with JSON) and transferred + to another entity (e.g., a script engine running in another thread), + where the object can be deserialized and passed as argument to + another script function. + \endlist + + \section2 Constructor Functions + + Some script functions are constructors; they are expected to initialize + new objects. The following snippet is a small example: + + \snippet doc/src/snippets/code/doc_src_qtscript.js 75 + + There is nothing special about constructor functions. In fact, any + script function can act as a constructor function (i.e., any function + can serve as the operand to \c{new}). Some functions behave differently + depending on whether they are called as part of a \c{new} expression + or not; for example, the expression \c{new Number(1)} will create a + Number object, whereas \c{Number("123")} will perform a type + conversion. Other functions, like \c{Array()}, will always create + and initialize a new object (e.g., \c{new Array()} and \c{Array()} have + the same effect). + + A native Qt Script function can call the + QScriptContext::isCalledAsConstructor() function to determine if it + is being called as a constructor or as a regular function. When a + function is called as a constructor (i.e., it is the operand in a + \c{new} expression), this has two important implications: + + \list + \i The \c this object, QScriptContext::thisObject(), contains + the new object to be initialized; the engine creates this + new object automatically before invoking your function. This means + that your native constructor function normally doesn't have to (and + shouldn't) create a new object when it is called as a + constructor, since the engine has already prepared a new + object. Instead your function should operate on the supplied + \c this object. + \i The constructor function should return an undefined value, + QScriptEngine::undefinedValue(), to tell the engine that the + \c this object should be the final result of the \c new + operator. Alternatively, the function can return the \c this + object itself. + \endlist + + When QScriptContext::isCalledAsConstructor() returns false, how your + constructor handles this case depends on what behavior you desire. + If, like the built-in \c{Number()} function, a plain function call should + perform a type conversion of its argument, then you perform the conversion + and return the result. If, on the other hand, you want your constructor + to behave \e{as if it was called as a constructor} (with + \c{new}), you have to explicitly create a new object (that is, + ignore the \c this object), initialize that object, and return it. + + The following example implements a constructor function that always + creates and initializes a new object: + + \snippet doc/src/snippets/code/doc_src_qtscript.cpp 76 + + Given this constructor, scripts would be able to use either the + expression \c{new Person("Bob")} or \c{Person("Bob")} to create a + new \c{Person} object; both behave in the same way. + + There is no equivalent way for a function defined in script + code to determine whether or not it was invoked as a constructor. + + Note that, even though it is not considered good practice, there is + nothing that stops you from choosing to ignore the default + constructed (\c this) object when your function is called as a + constructor and creating your own object anyway; simply have the + constructor return that object. The object will "override" the + default object that the engine constructed (i.e., the default + object will simply be discarded internally). + + \section2 Associating Data with a Function + + Even if a function is global \mdash i.e., not associated with any particular + (type of) object \mdash you might still want to associate some data with it, + so that it becomes self-contained; for example, the function could have + a pointer to some C++ resource that it needs to access. If your application + only uses a single script engine, or the same C++ resource can/should be + shared among all script engines, you can simply use a static C++ variable + and access it from within the native Qt Script function. + + In the case where a static C++ variable or singleton class is + not appropriate, you can call QScriptValue::setProperty() on the + function object, but be aware that those properties will also be + accessible to script code. The alternative is to use QScriptValue::setData(); + this data is not script-accessible. The implementation can access this + internal data through the QScriptContext::callee() function, which + returns the function object being invoked. The following example + shows how this might be used: + + \snippet doc/src/snippets/code/doc_src_qtscript.cpp 55 + + \section2 Native Functions as Arguments to Functions + + As previously mentioned, a function object can be passed as argument + to another function; this is also true for native functions, + naturally. As an example, here's a native comparison function + that compares its two arguments numerically: + + \snippet doc/src/snippets/code/doc_src_qtscript.cpp 53 + + The above function can be passed as argument to the standard + \c{Array.prototype.sort} function to sort an array numerically, + as the following C++ code illustrates: + + \snippet doc/src/snippets/code/doc_src_qtscript.cpp 54 + + Note that, in this case, we are truly treating the native function + object as a value \mdash i.e., we don't store it as a property of the + scripting environment \mdash we simply pass it on as an "anonymous" + argument to another script function and then forget about it. + + \section2 The Activation Object + + Every Qt Script function invocation has an \e{activation object} + associated with it; this object is accessible through the + QScriptContext::activationObject() function. The activation object + is a script object whose properties are the local variables + associated with the invocation (including the arguments for which + the script function has a corresponding formal parameter name). + Thus, getting, modifying, creating and deleting local variables + from C++ is done using the regular QScriptValue::property() and + QScriptValue::setProperty() functions. The activation object itself + is not directly accessible from script code (but it is implicitly + accessed whenever a local variable is read from or written to). + + For C++ code, there are two principal applications of the + activation object: + + \list + \i The activation object provides a standard way to traverse the + variables associated with a function call, by using it as the input + to QScriptValueIterator. This is useful for debugging purposes. + + \i The activation object can be used to prepare local variables + that should be available when a script is evaluated inline; this + can be viewed as a way of passing arguments to the script + itself. This technique is typically used in conjunction with + QScriptEngine::pushContext(), as in the following example: + + \snippet doc/src/snippets/code/doc_src_qtscript.cpp 77 + + We create a temporary execution context, create a local variable + for it, evaluate the script, and finally restore the old context. + \endlist + + \section2 Property Getters and Setters + + A script object property can be defined in terms of a getter/setter + function, similar to how a Qt C++ property has read and write + functions associated with it. This makes it possible for a script to + use expressions like \c{object.x} instead of \c{object.getX()}; the + getter/setter function for \c{x} will implicitly be invoked + whenever the property is accessed. To scripts, the property looks + and behaves just like a regular object property. + + A single Qt Script function can act as both getter and setter for + a property. When it is called as a getter, the argument count is 0. + When it is called as a setter, the argument count is 1; the argument + is the new value of the property. In the following example, we + define a native combined getter/setter that transforms the value + slightly: + + \snippet doc/src/snippets/code/doc_src_qtscript.cpp 78 + + The example uses the internal data of the object to store and + retrieve the transformed value. Alternatively, the property + could be stored in another, "hidden" property of the object itself + (e.g., \c{__x__}). A native function is free to implement whatever + storage scheme it wants, as long as the external behavior of the + property itself is consistent (e.g., that scripts should not be able + to distinguish it from a regular property). + + The following C++ code shows how an object property can be defined + in terms of the native getter/setter: + + \snippet doc/src/snippets/code/doc_src_qtscript.cpp 79 + + When the property is accessed, like in the following script, the + getter/setter does its job behind the scenes: + + \snippet doc/src/snippets/code/doc_src_qtscript.js 80 + + \note It is important that the setter function, not just the getter, + returns the value of the property; i.e., the setter should \e{not} + return QScriptValue::UndefinedValue. This is because the result of + the property assignment is the value returned by the setter, and + not the right-hand side expression. Also note that you normally + should not attempt to read the same property that the getter modifies + within the getter itself, since this will cause the getter to be + called recursively. + + You can remove a property getter/setter by calling + QScriptValue::setProperty(), passing an invalid QScriptValue + as the getter/setter. Remember to specify the + QScriptValue::PropertyGetter/QScriptValue::PropertySetter flag(s), + otherwise the only thing that will happen is that the setter will be + invoked with an invalid QScriptValue as its argument! + + Property getters and setters can be defined and installed by script + code as well, as in the following example: + + \snippet doc/src/snippets/code/doc_src_qtscript.js 81 + + Getters and setters can only be used to implement "a priori + properties"; i.e., the technique can't be used to react to an access + to a property that the object doesn't already have. To gain total + control of property access in this way, you need to subclass + QScriptClass. + + \section1 Making Use of Prototype-Based Inheritance + + In ECMAScript, inheritance is based on the concept of \e{shared + prototype objects}; this is quite different from the class-based + inheritance familiar to C++ programmers. With QtScript, you can + associate a custom prototype object with a C++ type using + QScriptEngine::setDefaultPrototype(); this is the key to providing + a script interface to that type. Since the QtScript module is built + on top of Qt's meta-type system, this can be done for any C++ type. + + You might be wondering when exactly you would need to use this + functionality in your application; isn't the automatic binding + provided by QScriptEngine::newQObject() enough? No, not under all + circumstances. + Firstly, not every C++ type is derived from QObject; types that + are not QObjects cannot be introspected through Qt's meta-object + system (they do not have properties, signals and slots). Secondly, + even if a type is QObject-derived, the functionality you want to + expose to scripts might not all be available, since it is unusual to + define every function to be a slot (and it's not always + possible/desirable to change the C++ API to make it so). + + It is perfectly possible to solve this problem by using "conventional" + C++ techniques. For instance, the QRect class could effectively be + made scriptable by creating a QObject-based C++ wrapper class with + \c{x}, \c{y}, \c{width} properties and so on, which forwarded property + access and function calls to the wrapped value. However, as we shall + see, by taking advantage of the ECMAScript object model and combining + it with Qt's meta-object system, we can arrive at a solution that is + more elegant, consistent and lightweight, supported by a small API. + + This section explains the underlying concepts of prototype-based + inheritance. Once these concepts are understood, the associated + practices can be applied throughout the QtScript API in order to + create well-behaved, consistent bindings to C++ that will fit nicely + into the ECMAScript universe. + + When experimenting with QtScript objects and inheritance, it can be + helpful to use the interactive interpreter included with the + \l{Qt Script Examples}, located in \c{examples/script/qscript}. + + \section2 Prototype Objects and Shared Properties + + The purpose of a QtScript \e{prototype object} is to define + behavior that should be shared by a set of other QtScript + objects. We say that objects which share the same prototype object + belong to the same \e{class} (again, on the technical side this + should not to be confused with the class constructs of languages + like C++ and Java; ECMAScript has no such construct). + + The basic prototype-based inheritance mechanism works as follows: Each + QtScript object has an internal link to another object, its + \e{prototype}. When a property is looked up in an object, and the + object itself does not have the property, the property is looked up + in the prototype object instead; if the prototype has the property, + then that property is returned. Otherwise, the property is looked up + in the prototype of the prototype object, and so on; this chain of + objects constitutes a \e{prototype chain}. The chain of prototype + objects is followed until the property is found or the end of the + chain is reached. + + For example, when you create a new object by the expression \c{new + Object()}, the resulting object will have as its prototype the + standard \c{Object} prototype, \c{Object.prototype}; through this + prototype relation, the new object inherits a set of properties, + including the \c{hasOwnProperty()} function and \c{toString()} + function: + + \snippet doc/src/snippets/code/doc_src_qtscript.js 27 + + The \c{toString()} function itself is not defined in \c{o} (since we + did not assign anything to \c{o.toString}), so instead the + \c{toString()} function in the standard \c{Object} prototype is + called, which returns a highly generic string representation of + \c{o} ("[object Object]"). + + Note that the properties of the prototype object are not \e{copied} to + the new object; only a \e{link} from the new object to the prototype + object is maintained. This means that changes done to the prototype + object will immediately be reflected in the behavior of all objects + that have the modified object as their prototype. + + \section2 Defining Classes in a Prototype-Based Universe + + In QtScript, a class is not defined explicitly; there is no + \c{class} keyword. Instead, you define a new class in two steps: + + \list 1 + \i Define a \e{constructor function} that will initialize new objects. + \i Set up a \e{prototype object} that defines the class interface, and + assign this object to the public \c{prototype} property of the + constructor function. + \endlist + + With this arrangement, the constructor's public \c{prototype} + property will automatically be set as the prototype of objects created + by applying the \c{new} operator to your constructor function; + e.g., the prototype of an object created by \c{new Foo()} will be the + value of \c{Foo.prototype}. + + Functions that don't operate on the \c this object ("static" methods) + are typically stored as properties of the constructor function, not + as properties of the prototype object. The same is true for + constants, such as enum values. + + The following code defines a simple constructor function for a class + called \c{Person}: + + \snippet doc/src/snippets/code/doc_src_qtscript.js 28 + + Next, you want to set up \c{Person.prototype} as your prototype + object; i.e., define the interface that should be common to all + \c{Person} objects. QtScript automatically creates a default + prototype object (by the expression \c{new Object()}) for every + script function; you can add properties to this object, or you can + assign your own custom object. (Generally speaking, any QtScript + object can act as prototype for any other object.) + + Here's an example of how you might want to override the + \c{toString()} function that \c{Person.prototype} inherits from + \c{Object.prototype}, to give your \c{Person} objects a more + appropriate string representation: + + \snippet doc/src/snippets/code/doc_src_qtscript.js 29 + + This resembles the process of reimplementing a virtual function + in C++. Henceforth, when the property named \c{toString} is + looked up in a \c{Person} object, it will be resolved in + \c{Person.prototype}, not in \c{Object.prototype} as before: + + \snippet doc/src/snippets/code/doc_src_qtscript.js 30 + + There are also some other interesting things we can learn about a + \c{Person} object: + + \snippet doc/src/snippets/code/doc_src_qtscript.js 31 + + The \c{hasOwnProperty()} function is not inherited from + \c{Person.prototype}, but rather from \c{Object.prototype}, which is + the prototype of \c{Person.prototype} itself; i.e., the prototype + chain of \c{Person} objects is \c{Person.prototype} followed by + \c{Object.prototype}. This prototype chain establishes a \e{class + hierarchy}, as demonstrated by applying the \c{instanceof} operator; + \c{instanceof} checks if the value of the public \c{prototype} + property of the constructor function on the right-hand side is + reached by following the prototype chain of the object on the + left-hand side. + + When defining subclasses, there's a general pattern you can use. The + following example shows how one can create a subclass of \c{Person} + called \c{Employee}: + + \snippet doc/src/snippets/code/doc_src_qtscript.js 32 + + Again, you can use the \c{instanceof} to verify that the + class relationship between \c{Employee} and \c{Person} has been + correctly established: + + \snippet doc/src/snippets/code/doc_src_qtscript.js 33 + + This shows that the prototype chain of \c{Employee} objects is the + same as that of \c{Person} objects, but with \c{Employee.prototype} + added to the front of the chain. + + \section2 Prototype-Based Programming with the QtScript C++ API + + You can use QScriptEngine::newFunction() to wrap + native functions. When implementing a constructor function, + you also pass the prototype object as an argument to + QScriptEngine::newFunction(). + You can call QScriptValue::construct() to call a constructor + function, and you can use QScriptValue::call() from within a + native constructor function if you need to call a base class + constructor. + + The QScriptable class provides a convenient way to implement a + prototype object in terms of C++ slots and properties. Take a look + at the \l{Default Prototypes Example} to see how this is done. + Alternatively, the prototype functionality can be implemented in + terms of standalone native functions that you wrap with + QScriptEngine::newFunction() and set as properties of your prototype + object by calling QScriptValue::setProperty(). + + In the implementation of your prototype functions, you use + QScriptable::thisObject() (or QScriptContext::thisObject()) to + obtain a reference to the QScriptValue being operated upon; then you + call qscriptvalue_cast() to cast it to your C++ type, and perform + the relevant operations using the usual C++ API for the type. + + You associate a prototype object with a C++ type by calling + QScriptEngine::setDefaultPrototype(). Once this mapping is + established, QtScript will automatically assign the correct + prototype when a value of such a type is wrapped in a QScriptValue; + either when you explicitly call QScriptEngine::toScriptValue(), or + when a value of such a type is returned from a C++ slot and + internally passed back to script code by the engine. This means you + \e{don't} have to implement wrapper classes if you use this + approach. + + As an example, let's consider how the \c{Person} class from the + preceding section can be implemented in terms of the Qt Script API. + We begin with the native constructor function: + + \snippet doc/src/snippets/code/doc_src_qtscript.cpp 34 + + Here's the native equivalent of the \c{Person.prototype.toString} + function we saw before: + + \snippet doc/src/snippets/code/doc_src_qtscript.cpp 35 + + The \c{Person} class can then be initialized as follows: + + \snippet doc/src/snippets/code/doc_src_qtscript.cpp 36 + + The implementation of the \c{Employee} subclass is similar. We + use QScriptValue::call() to call the super-class (Person) constructor: + + \snippet doc/src/snippets/code/doc_src_qtscript.cpp 37 + + The \c{Employee} class can then be initialized as follows: + + \snippet doc/src/snippets/code/doc_src_qtscript.cpp 38 + + When implementing the prototype object of a class, you may want to use + the QScriptable class, as it enables you to define the API of your + script class in terms of Qt properties, signals and slots, and + automatically handles value conversion between the Qt Script and C++ + side. + + \section2 Implementing Prototype Objects for Value-based Types + + When implementing a prototype object for a value-based type -- + e.g. QPointF -- the same general technique applies; you populate + a prototype object with functionality that should be shared + among instances. You then associate the prototype object with + the type by calling QScriptEngine::setDefaultPrototype(). This + ensures that when e.g. a value of the relevant type is returned + from a slot back to the script, the prototype link of the script + value will be initialized correctly. + + When values of the custom type are stored in QVariants -- which Qt + Script does by default --, qscriptvalue_cast() enables you to safely + cast the script value to a pointer to the C++ type. This makes it + easy to do type-checking, and, for prototype functions that should + modify the underlying C++ value, lets you modify the actual value + contained in the script value (and not a copy of it). + + \snippet doc/src/snippets/code/doc_src_qtscript.cpp 39 + + \section2 Implementing Constructors for Value-based Types + + You can implement a constructor function for a value-based type + by wrapping a native factory function. For example, the following + function implements a simple constructor for QPoint: + + \snippet doc/src/snippets/code/doc_src_qtscript.cpp 44 + + In the above code we simplified things a bit, e.g. we didn't check + the argument count to decide which QPoint C++ constructor to use. + In your own constructors you have to do this type of resolution + yourself, i.e. by checking the number of arguments passed to the + native function, and/or by checking the type of the arguments and + converting the arguments to the desired type. If you detect a problem + with the arguments you may want to signal this by throwing a script + exception; see QScriptContext::throwError(). + + \section2 Managing Non-QObject-based Objects + + For value-based types (e.g. QPoint), the C++ object will be destroyed when + the Qt Script object is garbage-collected, so managing the memory of the C++ + object is not an issue. For QObjects, Qt Script provides several + alternatives for managing the underlying C++ object's lifetime; see the + \l{Controlling QObject Ownership} section. However, for polymorphic types + that don't inherit from QObject, and when you can't (or won't) wrap the type + in a QObject, you have to manage the lifetime of the C++ object yourself. + + A behavior that's often reasonable when a Qt Script object wraps a C++ + object, is that the C++ object is deleted when the Qt Script object is + garbage-collected; this is typically the case when the objects can be + constructed by scripts, as opposed to the application providing the scripts + with pre-made "environment" objects. A way of making the lifetime of the C++ + object follow the lifetime of the Qt Script object is by using a shared + pointer class, such as QSharedPointer, to hold a pointer to your object; + when the Qt Script object containing the QSharedPointer is + garbage-collected, the underlying C++ object will be deleted if there are no + other references to the object. + + The following snippet shows a constructor function that constructs + QXmlStreamReader objects that are stored using QSharedPointer: + + \snippet doc/src/snippets/code/doc_src_qtscript.cpp 93 + + Prototype functions can use qscriptvalue_cast() to cast the \c this object + to the proper type: + + \snippet doc/src/snippets/code/doc_src_qtscript.cpp 94 + + The prototype and constructor objects are set up in the usual way: + + \snippet doc/src/snippets/code/doc_src_qtscript.cpp 95 + + Scripts can now construct QXmlStreamReader objects by calling the \c + XmlStreamReader constructor, and when the Qt Script object is + garbage-collected (or the script engine is destroyed), the QXmlStreamReader + object is destroyed as well. + + \section1 Defining Custom Script Classes with QScriptClass + + There are cases where neither the dynamic QObject binding provided + by QScriptEngine::newQObject() or the manual binding provided by + QScriptEngine::newFunction() is sufficient. For example, you might + want to implement a dynamic script proxy to an underlying object; + or you might want to implement an array-like class (i.e. that gives + special treatment to properties that are valid array indexes, and + to the property "length"). In such cases, you can subclass + QScriptClass to achieve the desired behavior. + + QScriptClass allows you to handle all property access for a + (class of) script object through virtual get/set property functions. + Iteration of custom properties is also supported through the + QScriptClassPropertyIterator class; this means you can advertise + properties to be reported by for-in script statements and + QScriptValueIterator. + + \section1 Error Handling and Debugging Facilities + + Syntax errors in scripts will be reported as soon as a script is + evaluated; QScriptEngine::evaluate() will return a SyntaxError object + that you can convert to a string to get a description of the error. + + The QScriptEngine::uncaughtExceptionBacktrace() function gives you + a human-readable backtrace of the last uncaught exception. In order + to get useful filename information in backtraces, you should pass + proper filenames to QScriptEngine::evaluate() when evaluating your + scripts. + + Often an exception doesn't happen at the time the script is evaluated, + but at a later time when a function defined by the script is actually + executed. For C++ signal handlers, this is tricky; consider the case + where the clicked() signal of a button is connected to a script function, + and that script function causes a script exception when it is handling + the signal. Where is that script exception propagated to? + + The solution is to connect to the QScriptEngine::signalHandlerException() + signal; this will give you notification when a signal handler causes + an exception, so that you can find out what happened and/or recover + from it. + + In Qt 4.4 the QScriptEngineAgent class was introduced. QScriptEngineAgent + provides an interface for reporting low-level "events" in a script engine, + such as when a function is entered or when a new script statement is + reached. By subclassing QScriptEngineAgent you can be notified of these + events and perform some action, if you want. QScriptEngineAgent itself + doesn't provide any debugging-specific functionality (e.g. setting + breakpoints), but it is the basis of tools that do. + + The QScriptEngineDebugger class introduced in Qt 4.5 provides a + \l{Qt Script Debugger Manual}{Qt Script debugger} that can be embedded + into your application. + + \section2 Redefining print() + + Qt Script provides a built-in print() function that can be useful for + simple debugging purposes. The built-in print() function writes to + standard output. You can redefine the print() function (or add your + own function, e.g. debug() or log()) that redirects the text to + somewhere else. The following code shows a custom print() that adds + text to a QPlainTextEdit. + + \snippet doc/src/snippets/code/doc_src_qtscript.cpp 45 + + The following code shows how the custom print() function may be + initialized and used. + + \snippet doc/src/snippets/code/doc_src_qtscript.cpp 46 + + A pointer to the QPlainTextEdit is stored as an internal property + of the script function itself, so that it can be retrieved when + the function is called. + + \section1 Using QtScript Extensions + + The QScriptEngine::importExtension() function can be used to load plugins + into a script engine. Plugins typically add some extra functionality to + the engine; for example, a plugin might add full bindings for the Qt + Arthur painting API, so that those classes may be used from Qt Script + scripts. There are currently no script plugins shipped with Qt. + + If you are implementing some Qt Script functionality that you want other + Qt application developers to be able to use, \l{Creating QtScript Extensions} + {developing an extension} (e.g. by subclassing QScriptExtensionPlugin) is + worth looking into. + + \section1 Internationalization + + Since Qt 4.5, Qt Script supports internationalization of scripts by building + on the C++ internationalization functionality (see \l{Internationalization + with Qt}). + + \section2 Use qsTr() for All Literal Text + + Wherever your script uses "quoted text" for text that will be presented to + the user, ensure that it is processed by the QCoreApplication::translate() + function. Essentially all that is necessary to achieve this is to use + the qsTr() script function. Example: + + \snippet doc/src/snippets/code/doc_src_qtscript.js 82 + + This accounts for 99% of the user-visible strings you're likely to write. + + The qsTr() function uses the basename of the script's filename (see + QFileInfo::baseName()) as the translation context; if the filename is not + unique in your project, you should use the qsTranslate() function and pass a + suitable context as the first argument. Example: + + \snippet doc/src/snippets/code/doc_src_qtscript.js 83 + + If you need to have translatable text completely outside a function, there + are two functions to help: QT_TR_NOOP() and QT_TRANSLATE_NOOP(). They merely + mark the text for extraction by the \c lupdate utility described below. At + runtime, these functions simply return the text to translate unmodified. + + Example of QT_TR_NOOP(): + + \snippet doc/src/snippets/code/doc_src_qtscript.js 84 + + Example of QT_TRANSLATE_NOOP(): + + \snippet doc/src/snippets/code/doc_src_qtscript.js 85 + + \section2 Use String.prototype.arg() for Dynamic Text + + The String.prototype.arg() function (which is modeled after QString::arg()) + offers a simple means for substituting arguments: + + \snippet doc/src/snippets/code/doc_src_qtscript.js 86 + + \section2 Produce Translations + + Once you are using qsTr() and/or qsTranslate() throughout your scripts, you + can start producing translations of the user-visible text in your program. + + The \l{Qt Linguist manual} provides further information about + Qt's translation tools, \e{Qt Linguist}, \c lupdate and \c + lrelease. + + Translation of Qt Script scripts is a three-step process: + + \list 1 + + \o Run \c lupdate to extract translatable text from the script source code + of the Qt application, resulting in a message file for translators (a TS + file). The utility recognizes qsTr(), qsTranslate() and the + \c{QT_TR*_NOOP()} functions described above and produces TS files + (usually one per language). + + \o Provide translations for the source texts in the TS file, using + \e{Qt Linguist}. Since TS files are in XML format, you can also + edit them by hand. + + \o Run \c lrelease to obtain a light-weight message file (a QM + file) from the TS file, suitable only for end use. Think of the TS + files as "source files", and QM files as "object files". The + translator edits the TS files, but the users of your application + only need the QM files. Both kinds of files are platform and + locale independent. + + \endlist + + Typically, you will repeat these steps for every release of your + application. The \c lupdate utility does its best to reuse the + translations from previous releases. + + When running \c lupdate, you must specify the location of the script(s), + and the name of the TS file to produce. Examples: + + \snippet doc/src/snippets/code/doc_src_qtscript.qdoc 87 + + will extract translatable text from \c myscript.qs and create the + translation file \c myscript_la.qs. + + \snippet doc/src/snippets/code/doc_src_qtscript.qdoc 88 + + will extract translatable text from all files ending with \c{.qs} in the + \c scripts folder and create the translation file \c scripts_la.qs. + + Alternatively, you can create a separate qmake project file that sets up + the \c SOURCES and \c TRANSLATIONS variables appropriately; then run + \c lupdate with the project file as input. + + \snippet doc/src/snippets/code/doc_src_qtscript.qdoc 89 + + When running \c lrelease, you must specify the name of the TS input + file; or, if you are using a qmake project file to manage script + translations, you specify the name of that file. \c lrelease will create + \c myscript_la.qm, the binary representation of the translation. + + \section2 Apply Translations + + In your application, you must use QTranslator::load() to load the + translation files appropriate for the user's language, and install them + using QCoreApplication::installTranslator(). Finally, you must call + QScriptEngine::installTranslatorFunctions() to make the script translation + functions (qsTr(), qsTranslate() and \c{QT_TR*_NOOP()}) available to scripts + that are subsequently evaluated by QScriptEngine::evaluate(). For scripts + that are using the qsTr() function, the proper filename must be passed as + second argument to QScriptEngine::evaluate(). + + \c linguist, \c lupdate and \c lrelease are installed in the \c bin + subdirectory of the base directory Qt is installed into. Click Help|Manual + in \e{Qt Linguist} to access the user's manual; it contains a tutorial + to get you started. + + See also the \l{Hello Script Example}. + + \section1 ECMAScript Compatibility + + QtScript implements all the built-in objects and properties defined + in the \l{ECMA-262} standard; see the + \l{ECMAScript Reference}{ECMAScript reference} for an overview. + + \section1 QtScript Extensions to ECMAScript + + \list + \i \c{__proto__} \br + The prototype of an object (QScriptValue::prototype()) + can be accessed through its \c{__proto__} property in script code. + This property has the QScriptValue::Undeletable flag set. + For example: + + \snippet doc/src/snippets/code/doc_src_qtscript.js 40 + + \i \c{Object.prototype.__defineGetter__} \br + This function installs a + getter function for a property of an object. The first argument is + the property name, and the second is the function to call to get + the value of that property. When the function is invoked, the + \c this object will be the object whose property is accessed. + For example: + + \snippet doc/src/snippets/code/doc_src_qtscript.js 41 + + \i \c{Object.prototype.__defineSetter__} \br + This function installs a + setter function for a property of an object. The first argument is + the property name, and the second is the function to call to set + the value of that property. When the function is invoked, the + \c this object will be the object whose property is accessed. + For example: + + \snippet doc/src/snippets/code/doc_src_qtscript.js 42 + + \i \c{Function.prototype.connect} \br + This function connects + a signal to a slot. Usage of this function is described in + the section \l{Using Signals and Slots}. + + \i \c{Function.prototype.disconnect} \br + This function disconnects + a signal from a slot. Usage of this function is described in + the section \l{Using Signals and Slots}. + + \i \c{QObject.prototype.findChild} \br + This function is semantically equivalent to QObject::findChild(). + + \i \c{QObject.prototype.findChildren} \br + This function is semantically equivalent to QObject::findChildren(). + + \i \c{QObject.prototype.toString} \br + This function returns a default string representation of a QObject. + + \i \c{gc} \br + This function invokes the garbage collector. + + \i \c{Error.prototype.backtrace} \br + This function returns a human-readable backtrace, in the form of + an array of strings. + + \i Error objects have the following additional properties: + \list + \i \c{lineNumber}: The line number where the error occurred. + \i \c{fileName}: The file name where the error occurred (if a file name + was passed to QScriptEngine::evaluate()). + \i \c{stack}: An array of objects describing the stack. Each object has + the following properties: + \list + \i \c{functionName}: The function name, if available. + \i \c{fileName}: The file name, if available. + \i \c{lineNumber}: The line number, if available. + \endlist + \endlist + + \endlist + + */ diff --git a/doc/src/snippets/code/doc_src_qtscript.cpp b/doc/src/snippets/code/doc_src_qtscript.cpp new file mode 100644 index 0000000..de82029 --- /dev/null +++ b/doc/src/snippets/code/doc_src_qtscript.cpp @@ -0,0 +1,568 @@ +/**************************************************************************** +** +** 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] +#include <QtScript> +//! [0] + +//! [13] +Q_PROPERTY(bool enabled READ enabled WRITE setEnabled) +//! [13] + +//! [18] +QScriptValue myQObjectConstructor(QScriptContext *context, QScriptEngine *engine) +{ + // let the engine manage the new object's lifetime. + return engine->newQObject(new MyQObject(), QScriptEngine::ScriptOwnership); +} +//! [18] + + +//! [19] +class MyObject : public QObject +{ + Q_OBJECT + +public: + MyObject( ... ); + + void aNonScriptableFunction(); + +public slots: // these functions (slots) will be available in QtScript + void calculate( ... ); + void setEnabled( bool enabled ); + bool isEnabled() const; + +private: + .... + +}; +//! [19] + + +//! [20] +class MyObject : public QObject +{ + Q_OBJECT + + public: + Q_INVOKABLE void thisMethodIsInvokableInQtScript(); + void thisMethodIsNotInvokableInQtScript(); + + ... +}; +//! [20] + + +//! [23] +class MyObject : public QObject +{ + Q_OBJECT + // define the enabled property + Q_PROPERTY( bool enabled WRITE setEnabled READ isEnabled ) + +public: + MyObject( ... ); + + void aNonScriptableFunction(); + +public slots: // these functions (slots) will be available in QtScript + void calculate( ... ); + void setEnabled( bool enabled ); + bool isEnabled() const; + +private: + .... + +}; +//! [23] + + +//! [24] +Q_PROPERTY(int nonScriptableProperty READ foo WRITE bar SCRIPTABLE false) +//! [24] + + +//! [25] +class MyObject : public QObject +{ + Q_OBJECT + // define the enabled property + Q_PROPERTY( bool enabled WRITE setEnabled READ isEnabled ) + +public: + MyObject( ... ); + + void aNonScriptableFunction(); + +public slots: // these functions (slots) will be available in QtScript + void calculate( ... ); + void setEnabled( bool enabled ); + bool isEnabled() const; + +signals: // the signals + void enabledChanged( bool newState ); + +private: + .... + +}; +//! [25] + + +//! [34] +QScriptValue Person_ctor(QScriptContext *context, QScriptEngine *engine) +{ + QString name = context->argument(0).toString(); + context->thisObject().setProperty("name", name); + return engine->undefinedValue(); +} +//! [34] + + +//! [35] +QScriptValue Person_prototype_toString(QScriptContext *context, QScriptEngine *engine) +{ + QString name = context->thisObject().property("name").toString(); + QString result = QString::fromLatin1("Person(name: %0)").arg(name); + return result; +} +//! [35] + + +//! [36] +QScriptEngine engine; +QScriptValue ctor = engine.newFunction(Person_ctor); +ctor.property("prototype").setProperty("toString", engine.newFunction(Person_prototype_toString)); +QScriptValue global = engine.globalObject(); +global.setProperty("Person", ctor); +//! [36] + + +//! [37] +QScriptValue Employee_ctor(QScriptContext *context, QScriptEngine *engine) +{ + QScriptValue super = context->callee().property("prototype").property("constructor"); + super.call(context->thisObject(), QScriptValueList() << context->argument(0)); + context->thisObject().setProperty("salary", context->argument(1)); + return engine->undefinedValue(); +} +//! [37] + + +//! [38] +QScriptValue empCtor = engine.newFunction(Employee_ctor); +empCtor.setProperty("prototype", global.property("Person").construct()); +global.setProperty("Employee", empCtor); +//! [38] + + +//! [39] +Q_DECLARE_METATYPE(QPointF) +Q_DECLARE_METATYPE(QPointF*) + +QScriptValue QPointF_prototype_x(QScriptContext *context, QScriptEngine *engine) +{ + // Since the point is not to be modified, it's OK to cast to a value here + QPointF point = qscriptvalue_cast<QPointF>(context->thisObject()); + return point.x(); +} + +QScriptValue QPointF_prototype_setX(QScriptContext *context, QScriptEngine *engine) +{ + // Cast to a pointer to be able to modify the underlying C++ value + QPointF *point = qscriptvalue_cast<QPointF*>(context->thisObject()); + if (!point) + return context->throwError(QScriptContext::TypeError, "QPointF.prototype.setX: this object is not a QPointF"); + point->setX(context->argument(0).toNumber()); + return engine->undefinedValue(); +} +//! [39] + + +//! [43] +class MyObject : public QObject +{ + Q_OBJECT + ... +}; + +Q_DECLARE_METATYPE(MyObject*) + +QScriptValue myObjectToScriptValue(QScriptEngine *engine, MyObject* const &in) +{ return engine->newQObject(in); } + +void myObjectFromScriptValue(const QScriptValue &object, MyObject* &out) +{ out = qobject_cast<MyObject*>(object.toQObject()); } + +... + +qScriptRegisterMetaType(&engine, myObjectToScriptValue, myObjectFromScriptValue); +//! [43] + +//! [44] +QScriptValue QPoint_ctor(QScriptContext *context, QScriptEngine *engine) +{ + int x = context->argument(0).toInt32(); + int y = context->argument(1).toInt32(); + return engine->toScriptValue(QPoint(x, y)); +} + +... + +engine.globalObject().setProperty("QPoint", engine.newFunction(QPoint_ctor)); +//! [44] + +//! [45] +QScriptValue myPrintFunction(QScriptContext *context, QScriptEngine *engine) +{ + QString result; + for (int i = 0; i < context->argumentCount(); ++i) { + if (i > 0) + result.append(" "); + result.append(context->argument(i).toString()); + } + + QScriptValue calleeData = context->callee().data(); + QPlainTextEdit *edit = qobject_cast<QPlainTextEdit*>(calleeData.toQObject()); + edit->appendPlainText(result); + + return engine->undefinedValue(); +} +//! [45] + +//! [46] +int main(int argc, char **argv) +{ + QApplication app(argc, argv); + + QScriptEngine eng; + QPlainTextEdit edit; + + QScriptValue fun = eng.newFunction(myPrintFunction); + fun.setData(eng.newQObject(&edit)); + eng.globalObject().setProperty("print", fun); + + eng.evaluate("print('hello', 'world')"); + + edit.show(); + return app.exec(); +} +//! [46] + + +//! [47] +QScriptEngine eng; +QLineEdit *edit = new QLineEdit(...); +QScriptValue handler = eng.evaluate("(function(text) { print('text was changed to', text); })"); +qScriptConnect(edit, SIGNAL(textChanged(const QString &)), QScriptValue(), handler); +//! [47] + +//! [48] +QLineEdit *edit1 = new QLineEdit(...); +QLineEdit *edit2 = new QLineEdit(...); + +QScriptValue handler = eng.evaluate("(function() { print('I am', this.name); })"); +QScriptValue obj1 = eng.newObject(); +obj1.setProperty("name", "the walrus"); +QScriptValue obj2 = eng.newObject(); +obj2.setProperty("name", "Sam"); + +qScriptConnect(edit1, SIGNAL(returnPressed()), obj1, handler); +qScriptConnect(edit2, SIGNAL(returnPressed()), obj2, handler); +//! [48] + +//! [52] +QScriptValue getProperty(QScriptContext *ctx, QScriptEngine *eng) +{ + QString name = ctx->argument(0).toString(); + return ctx->thisObject().property(name); +} +//! [52] + +//! [53] +QScriptValue myCompare(QScriptContext *ctx, QScriptEngine *eng) +{ + double first = ctx->argument(0).toNumber(); + double second = ctx->argument(1).toNumber(); + int result; + if (first == second) + result = 0; + else if (first < second) + result = -1; + else + result = 1; + return result; +} +//! [53] + +//! [54] +QScriptEngine eng; +QScriptValue comparefn = eng.newFunction(myCompare); +QScriptValue array = eng.evaluate("new Array(10, 5, 20, 15, 30)"); +array.property("sort").call(array, QScriptValueList() << comparefn); + +// prints "5,10,15,20,30" +qDebug() << array.toString(); +//! [54] + +//! [55] +QScriptValue rectifier(QScriptContext *ctx, QScriptEngine *eng) +{ + QRectF magicRect = qscriptvalue_cast<QRectF>(ctx->callee().data()); + QRectF sourceRect = qscriptvalue_cast<QRectF>(ctx->argument(0)); + return eng->toScriptValue(sourceRect.intersected(magicRect)); +} + +... + +QScriptValue fun = eng.newFunction(rectifier); +QRectF magicRect = QRectF(10, 20, 30, 40); +fun.setData(eng.toScriptValue(magicRect)); +eng.globalObject().setProperty("rectifier", fun); +//! [55] + +//! [58] +QScriptValue add(QScriptContext *ctx, QScriptEngine *eng) +{ + double a = ctx->argument(0).toNumber(); + double b = ctx->argument(1).toNumber(); + return a + b; +} +//! [58] + +//! [62] +QScriptValue add(QScriptContext *ctx, QScriptEngine *eng) +{ + if (ctx->argumentCount() != 2) + return ctx->throwError("add() takes exactly two arguments"); + double a = ctx->argument(0).toNumber(); + double b = ctx->argument(1).toNumber(); + return a + b; +} +//! [62] + +//! [63] +QScriptValue add(QScriptContext *ctx, QScriptEngine *eng) +{ + if (ctx->argumentCount() != 2) + return ctx->throwError("add() takes exactly two arguments"); + if (!ctx->argument(0).isNumber()) + return ctx->throwError(QScriptContext::TypeError, "add(): first argument is not a number"); + if (!ctx->argument(1).isNumber()) + return ctx->throwError(QScriptContext::TypeError, "add(): second argument is not a number"); + double a = ctx->argument(0).toNumber(); + double b = ctx->argument(1).toNumber(); + return a + b; +} +//! [63] + +//! [65] +QScriptValue concat(QScriptContext *ctx, QScriptEngine *eng) +{ + QString result = ""; + for (int i = 0; i < ctx->argumentCount(); ++i) + result += ctx->argument(i).toString(); + return result; +} +//! [65] + +//! [67] +QScriptValue sort(QScriptContext *ctx, QScriptEngine *eng) +{ + QScriptValue comparefn = ctx->argument(0); + if (comparefn.isUndefined()) + comparefn = /* the built-in comparison function */; + else if (!comparefn.isFunction()) + return ctx->throwError(QScriptContext::TypeError, "sort(): argument is not a function"); + ... +} +//! [67] + +//! [69] +QScriptValue foo(QScriptContext *ctx, QScriptEngine *eng) +{ + QScriptValue bar = eng->globalObject().property("bar"); + QScriptValue arguments = ctx->argumentsObject(); + qDebug() << "calling bar() with" << arguments.property("length").toInt32() << "arguments"; + QScriptValue result = bar.apply(ctx->thisObject(), arguments); + qDebug() << "bar() returned" << result.toString(); + return result; +} +//! [69] + +//! [72] +QScriptValue counter(QScriptContext *ctx, QScriptEngine *eng) +{ + QScriptValue act = ctx->activationObject(); + act.setProperty("count", 0); + QScriptValue result = eng->newFunction(counter_inner); + result.setScope(act); + return result; +} +//! [72] + +//! [73] +QScriptValue counter_inner(QScriptContext *ctx, QScriptEngine *eng) +{ + QScriptValue outerAct = ctx->callee().scope(); + double count = outerAct.property("count").toNumber(); + outerAct.setProperty("count", count+1); + return count; +} +//! [73] + +//! [74] +QScriptValue counter_hybrid(QScriptContext *ctx, QScriptEngine *eng) +{ + QScriptValue act = ctx->activationObject(); + act.setProperty("count", 0); + return eng->evaluate("(function() { return count++; })"); +} +//! [74] + +//! [76] +QScriptValue Person_ctor(QScriptContext *ctx, QScriptEngine *eng) +{ + QScriptValue object; + if (ctx->isCalledAsConstructor()) { + object = ctx->thisObject(); + } else { + object = eng->newObject(); + object.setPrototype(ctx->callee().property("prototype")); + } + object.setProperty("name", ctx->argument(0)); + return object; +} +//! [76] + +//! [77] +QScriptContext *ctx = eng.pushContext(); +QScriptValue act = ctx->activationObject(); +act.setProperty("digit", 7); + +qDebug() << eng.evaluate("digit + 1").toNumber(); // 8 + +eng.popContext(); +//! [77] + +//! [78] +QScriptValue getSet(QScriptContext *ctx, QScriptEngine *eng) +{ + QScriptValue obj = ctx->thisObject(); + QScriptValue data = obj.data(); + if (!data.isValid()) { + data = eng->newObject(); + obj.setData(data); + } + QScriptValue result; + if (ctx->argumentCount() == 1) { + QString str = ctx->argument(0).toString(); + str.replace("Roberta", "Ken"); + result = str; + data.setProperty("x", result); + } else { + result = data.property("x"); + } + return result; +} +//! [78] + +//! [79] +QScriptEngine eng; +QScriptValue obj = eng.newObject(); +obj.setProperty("x", eng.newFunction(getSet), + QScriptValue::PropertyGetter|QScriptValue::PropertySetter); +//! [79] + +//! [91] +QScriptValue object = engine.evaluate("({ unitName: 'Celsius', toKelvin: function(x) { return x + 273; } })"); +QScriptValue toKelvin = object.property("toKelvin"); +QScriptValue result = toKelvin.call(object, QScriptValueList() << 100); +qDebug() << result.toNumber(); // 373 +//! [91] + +//! [92] +QScriptValue add = engine.globalObject().property("add"); +qDebug() << add.call(QScriptValue(), QScriptValueList() << 1 << 2).toNumber(); // 3 +//! [92] + +//! [93] +typedef QSharedPointer<QXmlStreamReader> XmlStreamReaderPointer; + +Q_DECLARE_METATYPE(XmlStreamReaderPointer) + +QScriptValue constructXmlStreamReader(QScriptContext *context, QScriptEngine *engine) +{ + if (!context->isCalledAsConstructor()) + return context->throwError(QScriptContext::SyntaxError, "please use the 'new' operator"); + + QIODevice *device = qobject_cast<QIODevice*>(context->argument(0).toQObject()); + if (!device) + return context->throwError(QScriptContext::TypeError, "please supply a QIODevice as first argument"); + + // Create the C++ object + QXmlStreamReader *reader = new QXmlStreamReader(device); + + XmlStreamReaderPointer pointer(reader); + + // store the shared pointer in the script object that we are constructing + return engine->newVariant(context->thisObject(), QVariant::fromValue(pointer)); +} +//! [93] + +//! [94] +QScriptValue xmlStreamReader_atEnd(QScriptContext *context, QScriptEngine *) +{ + XmlStreamReaderPointer reader = qscriptvalue_cast<XmlStreamReaderPointer>(context->thisObject()); + if (!reader) + return context->throwError(QScriptContext::TypeError, "this object is not an XmlStreamReader"); + return reader->atEnd(); +} +//! [94] + +//! [95] + QScriptEngine engine; + QScriptValue xmlStreamReaderProto = engine.newObject(); + xmlStreamReaderProto.setProperty("atEnd", engine.newFunction(xmlStreamReader_atEnd)); + + QScriptValue xmlStreamReaderCtor = engine.newFunction(constructXmlStreamReader, xmlStreamReaderProto); + engine.globalObject().setProperty("XmlStreamReader", xmlStreamReaderCtor); +//! [95] diff --git a/doc/src/snippets/code/doc_src_qtscript.js b/doc/src/snippets/code/doc_src_qtscript.js new file mode 100644 index 0000000..fe1f9b9 --- /dev/null +++ b/doc/src/snippets/code/doc_src_qtscript.js @@ -0,0 +1,444 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ + +//! [2] +function myInterestingScriptFunction() { + // ... +} +// ... +myQObject.somethingChanged.connect(myInterestingScriptFunction); +//! [2] + + +//! [3] +myQObject.somethingChanged.connect(myOtherQObject.doSomething); +//! [3] + + +//! [4] +myQObject.somethingChanged.disconnect(myInterestingFunction); +myQObject.somethingChanged.disconnect(myOtherQObject.doSomething); +//! [4] + + +//! [5] +var obj = { x: 123 }; +var fun = function() { print(this.x); }; +myQObject.somethingChanged.connect(obj, fun); +//! [5] + + +//! [6] +myQObject.somethingChanged.disconnect(obj, fun); +//! [6] + + +//! [7] +var obj = { x: 123, fun: function() { print(this.x); } }; +myQObject.somethingChanged.connect(obj, "fun"); +//! [7] + + +//! [8] +myQObject.somethingChanged.disconnect(obj, "fun"); +//! [8] + + +//! [9] +try { + myQObject.somethingChanged.connect(myQObject, "slotThatDoesntExist"); +} catch (e) { + print(e); +} +//! [9] + + +//! [10] +myQObject.somethingChanged("hello"); +//! [10] + + +//! [11] +myQObject.myOverloadedSlot(10); // will call the int overload +myQObject.myOverloadedSlot("10"); // will call the QString overload +//! [11] + + +//! [12] +myQObject['myOverloadedSlot(int)']("10"); // call int overload; the argument is converted to an int +myQObject['myOverloadedSlot(QString)'](10); // call QString overload; the argument is converted to a string +//! [12] + + +//! [14] +myQObject.enabled = true; + +// ... + +myQObject.enabled = !myQObject.enabled; +//! [14] + + +//! [15] +myDialog.okButton +//! [15] + + +//! [16] +myDialog.okButton.objectName = "cancelButton"; +// from now on, myDialog.cancelButton references the button +//! [16] + + +//! [17] +var okButton = myDialog.findChild("okButton"); +if (okButton != null) { + // do something with the OK button +} + +var buttons = myDialog.findChildren(RegExp("button[0-9]+")); +for (var i = 0; i < buttons.length; ++i) { + // do something with buttons[i] +} +//! [17] + + +//! [21] +var obj = new MyObject; +obj.setEnabled( true ); +print( "obj is enabled: " + obj.isEnabled() ); +//! [21] + + +//! [22] +var obj = new MyObject; +obj.enabled = true; +print( "obj is enabled: " + obj.enabled ); +//! [22] + + +//! [26] +function enabledChangedHandler( b ) +{ + print( "state changed to: " + b ); +} + +function init() +{ + var obj = new MyObject(); + // connect a script function to the signal + obj["enabledChanged(bool)"].connect(enabledChangedHandler); + obj.enabled = true; + print( "obj is enabled: " + obj.enabled ); +} +//! [26] + + +//! [27] +var o = new Object(); +o.foo = 123; +print(o.hasOwnProperty('foo')); // true +print(o.hasOwnProperty('bar')); // false +print(o); // calls o.toString(), which returns "[object Object]" +//! [27] + + +//! [28] +function Person(name) +{ + this.name = name; +} +//! [28] + + +//! [29] +Person.prototype.toString = function() { return "Person(name: " + this.name + ")"; } +//! [29] + + +//! [30] +var p1 = new Person("John Doe"); +var p2 = new Person("G.I. Jane"); +print(p1); // "Person(name: John Doe)" +print(p2); // "Person(name: G.I. Jane)" +//! [30] + + +//! [31] +print(p1.hasOwnProperty('name')); // 'name' is an instance variable, so this returns true +print(p1.hasOwnProperty('toString')); // returns false; inherited from prototype +print(p1 instanceof Person); // true +print(p1 instanceof Object); // true +//! [31] + + +//! [32] +function Employee(name, salary) +{ + Person.call(this, name); // call base constructor + + this.salary = salary; +} + +// set the prototype to be an instance of the base class +Employee.prototype = new Person(); + +// initialize prototype +Employee.prototype.toString = function() { + // ... +} +//! [32] + + +//! [33] +var e = new Employee("Johnny Bravo", 5000000); +print(e instanceof Employee); // true +print(e instanceof Person); // true +print(e instanceof Object); // true +print(e instanceof Array); // false +//! [33] + + +//! [40] +var o = new Object(); +(o.__proto__ === Object.prototype); // this evaluates to true +//! [40] + + +//! [41] +var o = new Object(); +o.__defineGetter__("x", function() { return 123; }); +var y = o.x; // 123 +//! [41] + + +//! [42] +var o = new Object(); +o.__defineSetter__("x", function(v) { print("and the value is:", v); }); +o.x = 123; // will print "and the value is: 123" +//! [42] + + +//! [49] +var getProperty = function(name) { return this[name]; }; + +name = "Global Object"; // creates a global variable +print(getProperty("name")); // "Global Object" + +var myObject = { name: 'My Object' }; +print(getProperty.call(myObject, "name")); // "My Object" + +myObject.getProperty = getProperty; +print(myObject.getProperty("name")); // "My Object" + +getProperty.name = "The getProperty() function"; +getProperty.getProperty = getProperty; +getProperty.getProperty("name"); // "The getProperty() function" +//! [49] + +//! [50] +var o = { a: 1, b: 2, sum: function() { return a + b; } }; +print(o.sum()); // reference error, or sum of global variables a and b!! +//! [50] + +//! [51] +var o = { a: 1, b: 2, sum: function() { return this.a + this.b; } }; +print(o.sum()); // 3 +//! [51] + +//! [56] +function add(a, b) { + return a + b; +} +//! [56] + +//! [57] +function add() { + return arguments[0] + arguments[1]; +} +//! [57] + +//! [59] +function add() { + if (arguments.length != 2) + throw Error("add() takes exactly two arguments"); + return arguments[0] + arguments[1]; +} +//! [59] + +//! [60] +function add() { + if (arguments.length != 2) + throw Error("add() takes exactly two arguments"); + if (typeof arguments[0] != "number") + throw TypeError("add(): first argument is not a number"); + if (typeof arguments[1] != "number") + throw TypeError("add(): second argument is not a number"); + return arguments[0] + arguments[1]; +} +//! [60] + +//! [61] +function add() { + if (arguments.length != 2) + throw Error("add() takes exactly two arguments"); + return Number(arguments[0]) + Number(arguments[1]); +} +//! [61] + +//! [64] +function concat() { + var result = ""; + for (var i = 0; i < arguments.length; ++i) + result += String(arguments[i]); + return result; +} +//! [64] + +//! [66] +function sort(comparefn) { + if (comparefn == undefined) + comparefn = fn; /* replace fn with the built-in comparison function */ + else if (typeof comparefn != "function") + throw TypeError("sort(): argument must be a function"); + // ... +} +//! [66] + +//! [68] +function foo() { + // Let bar() take care of this. + print("calling bar() with " + arguments.length + "arguments"); + var result = bar.apply(this, arguments); + print("bar() returned" + result); + return result; +} +//! [68] + +//! [70] +function counter() { + var count = 0; + return function() { + return count++; + } +} +//! [70] + +//! [71] +var c1 = counter(); // create a new counter function +var c2 = counter(); // create a new counter function +print(c1()); // 0 +print(c1()); // 1 +print(c2()); // 0 +print(c2()); // 1 +//! [71] + +//! [75] +function Book(isbn) { + this.isbn = isbn; +} + +var coolBook1 = new Book("978-0131872493"); +var coolBook2 = new Book("978-1593271473"); +//! [75] + +//! [80] +obj.x = "Roberta sent me"; +print(obj.x); // "Ken sent me" +obj.x = "I sent the bill to Roberta"; +print(obj.x); // "I sent the bill to Ken" +//! [80] + +//! [81] +obj = {}; +obj.__defineGetter__("x", function() { return this._x; }); +obj.__defineSetter__("x", function(v) { print("setting x to", v); this._x = v; }); +obj.x = 123; +//! [81] + +//! [82] +myButton.text = qsTr("Hello world!"); +//! [82] + +//! [83] +myButton.text = qsTranslate("MyAwesomeScript", "Hello world!"); +//! [83] + +//! [84] +FriendlyConversation.prototype.greeting = function(type) +{ + if (FriendlyConversation['greeting_strings'] == undefined) { + FriendlyConversation['greeting_strings'] = [ + QT_TR_NOOP("Hello"), + QT_TR_NOOP("Goodbye") + ]; + } + return qsTr(FriendlyConversation.greeting_strings[type]); +} +//! [84] + +//! [85] +FriendlyConversation.prototype.greeting = function(type) +{ + if (FriendlyConversation['greeting_strings'] == undefined) { + FriendlyConversation['greeting_strings'] = [ + QT_TRANSLATE_NOOP("FriendlyConversation", "Hello"), + QT_TRANSLATE_NOOP("FriendlyConversation", "Goodbye") + ]; + } + return qsTranslate("FriendlyConversation", FriendlyConversation.greeting_strings[type]); +} +//! [85] + +//! [86] +FileCopier.prototype.showProgress = function(done, total, currentFileName) +{ + this.label.text = qsTr("%1 of %2 files copied.\nCopying: %3") + .arg(done) + .arg(total) + .arg(currentFileName); +} +//! [86] + +//! [90] +({ unitName: "Celsius", + toKelvin: function(x) { return x + 273; } + }) +//! [90] diff --git a/doc/src/snippets/code/doc_src_qtscript.qdoc b/doc/src/snippets/code/doc_src_qtscript.qdoc new file mode 100644 index 0000000..b65311f --- /dev/null +++ b/doc/src/snippets/code/doc_src_qtscript.qdoc @@ -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$ +** +****************************************************************************/ + +//! [87] +lupdate myscript.qs -ts myscript_la.ts +//! [87] + +//! [88] +lupdate -extensions qs scripts/ -ts scripts_la.ts +//! [88] + +//! [89] +lrelease myscript_la.ts +//! [89] diff --git a/doc/src/snippets/code/doc_src_qtscriptextensions.js b/doc/src/snippets/code/doc_src_qtscriptextensions.js new file mode 100644 index 0000000..456077d --- /dev/null +++ b/doc/src/snippets/code/doc_src_qtscriptextensions.js @@ -0,0 +1,47 @@ +/**************************************************************************** +** +** 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] +print("importing " + __extension__); +__setupPackage__("cool.stuff"); + +cool.stuff.add = function(a, b) { return a + b; } +cool.stuff.subtract = function(a, b) { return a - b; } +//! [0] diff --git a/doc/src/snippets/code/src.scripttools.qscriptenginedebugger.cpp b/doc/src/snippets/code/src.scripttools.qscriptenginedebugger.cpp new file mode 100644 index 0000000..b17f465 --- /dev/null +++ b/doc/src/snippets/code/src.scripttools.qscriptenginedebugger.cpp @@ -0,0 +1,49 @@ +/**************************************************************************** +** +** 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] + QScriptEngine engine; + QScriptEngineDebugger debugger; + debugger.attachTo(&engine); +//! [0] + +//! [1] + engine.evaluate("debugger"); +//! [1] diff --git a/doc/src/snippets/code/src_script_qscriptable.cpp b/doc/src/snippets/code/src_script_qscriptable.cpp new file mode 100644 index 0000000..997f14f --- /dev/null +++ b/doc/src/snippets/code/src_script_qscriptable.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] +class MyScriptableObject: public QObject, + protected QScriptable +{ + Q_OBJECT +... + +public slots: + void doSomething(); + double doSomethingElse(); +} +//! [0] + + +//! [1] +void MyScriptableObject::doSomething() +{ + context()->throwError("Threw an error from a slot"); +} + +double MyScriptableObject::doSomethingElse() +{ + return qscriptvalue_cast<double>(thisObject()); +} +//! [1] diff --git a/doc/src/snippets/code/src_script_qscriptclass.cpp b/doc/src/snippets/code/src_script_qscriptclass.cpp new file mode 100644 index 0000000..dde13cf --- /dev/null +++ b/doc/src/snippets/code/src_script_qscriptclass.cpp @@ -0,0 +1,50 @@ +/**************************************************************************** +** +** 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] +if (extension == Callable) { + QScriptContext *context = qvariant_cast<QScriptContext*>(argument); + QScriptEngine *engine = context->engine(); + double sum = 0; + for (int i = 0; i < context->argumentCount(); ++i) + sum += context->argument(i).toNumber(); + return sum; +} +//! [0] diff --git a/doc/src/snippets/code/src_script_qscriptcontext.cpp b/doc/src/snippets/code/src_script_qscriptcontext.cpp new file mode 100644 index 0000000..09c58cf --- /dev/null +++ b/doc/src/snippets/code/src_script_qscriptcontext.cpp @@ -0,0 +1,68 @@ +/**************************************************************************** +** +** 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] +foo(20.5, "hello", new Object()) +//! [0] + + +//! [1] +QScriptValue Person_prototype_fullName(QScriptContext *context, QScriptEngine *engine) +{ + QScriptValue self = context->thisObject(); + QString result; + result += self.property("firstName").toString(); + result += QLatin1String(" "); + result += self.property("lastName").toString(); + return result; +} +//! [1] + + +//! [2] +QScriptValue myInclude(QScriptContext *ctx, QScriptEngine *eng) +{ + QString fileName = ctx->argument(0).toString(); + QString contents = readTheFile(fileName); + ctx->setActivationObject(ctx->parentContext()->activationObject()); + ctx->setThisObject(ctx->parentContext()->thisObject()); + return eng->evaluate(contents, fileName); +} +//! [2] diff --git a/doc/src/snippets/code/src_script_qscriptengine.cpp b/doc/src/snippets/code/src_script_qscriptengine.cpp new file mode 100644 index 0000000..2c02973 --- /dev/null +++ b/doc/src/snippets/code/src_script_qscriptengine.cpp @@ -0,0 +1,332 @@ +/**************************************************************************** +** +** 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] +QScriptEngine myEngine; +QScriptValue three = myEngine.evaluate("1 + 2"); +//! [0] + + +//! [1] +QScriptValue fun = myEngine.evaluate("(function(a, b) { return a + b; })"); +QScriptValueList args; +args << 1 << 2; +QScriptValue threeAgain = fun.call(QScriptValue(), 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); +... +QScriptValue myNumberPlusOne = myEngine.evaluate("myNumber + 1"); +//! [3] + + +//! [4] +QScriptValue result = myEngine.evaluate(...); +if (myEngine.hasUncaughtException()) { + int line = myEngine.uncaughtExceptionLineNumber(); + qDebug() << "uncaught exception at line" << line << ":" << result.toString(); +} +//! [4] + + +//! [5] +QPushButton button; +QScriptValue 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] + + +//! [6] +QScriptValue myAdd(QScriptContext *context, QScriptEngine *engine) +{ + QScriptValue a = context->argument(0); + QScriptValue b = context->argument(1); + return a.toNumber() + b.toNumber(); +} +//! [6] + + +//! [7] +QScriptValue fun = myEngine.newFunction(myAdd); +myEngine.globalObject().setProperty("myAdd", fun); +//! [7] + + +//! [8] +QScriptValue result = myEngine.evaluate("myAdd(myNumber, 1)"); +//! [8] + + +//! [9] +QScriptValue Foo(QScriptContext *context, QScriptEngine *engine) +{ + if (context->calledAsConstructor()) { + // initialize the new object + context->thisObject().setProperty("bar", ...); + // ... + // return a non-object value to indicate that the + // thisObject() should be the result of the "new Foo()" expression + return engine->undefinedValue(); + } else { + // not called as "new Foo()", just "Foo()" + // create our own object and return that one + QScriptValue object = engine->newObject(); + object.setPrototype(context->callee().property("prototype")); + object.setProperty("baz", ...); + return object; + } +} + +... + +QScriptValue fooProto = engine->newObject(); +fooProto.setProperty("whatever", ...); +engine->globalObject().setProperty("Foo", engine->newFunction(Foo, fooProto)); +//! [9] + + +//! [10] +class Bar { ... }; + +Q_DECLARE_METATYPE(Bar) + +QScriptValue constructBar(QScriptContext *context, QScriptEngine *engine) +{ + Bar bar; + // initialize from arguments in context, if desired + ... + return engine->toScriptValue(bar); +} + +class BarPrototype : public QObject, public QScriptable +{ +// provide the scriptable interface of this type using slots and properties +... +}; + +... + +// create and register the Bar prototype and constructor in the engine +BarPrototype *barPrototypeObject = new BarPrototype(...); +QScriptValue barProto = engine->newQObject(barPrototypeObject); +engine->setDefaultPrototype(qMetaTypeId<Bar>, barProto); +QScriptValue barCtor = engine->newFunction(constructBar, barProto); +engine->globalObject().setProperty("Bar", barCtor); +//! [10] + + +//! [11] +static QScriptValue getSetFoo(QScriptContext *context, QScriptEngine *engine) +{ + QScriptValue callee = context->callee(); + if (context->argumentCount() == 1) // writing? + callee.setProperty("value", context->argument(0)); + return callee.property("value"); +} + +.... + +QScriptValue object = engine.newObject(); +object.setProperty("foo", engine.newFunction(getSetFoo), + QScriptValue::PropertyGetter | QScriptValue::PropertySetter); +//! [11] + + +//! [12] +QScriptValue object = engine.newObject(); +object.setProperty("foo", engine.newFunction(getFoo), QScriptValue::PropertyGetter); +object.setProperty("foo", engine.newFunction(setFoo), QScriptValue::PropertySetter); +//! [12] + + +//! [13] +Q_SCRIPT_DECLARE_QMETAOBJECT(QLineEdit, QWidget*) + +... + +QScriptValue lineEditClass = engine.scriptValueFromQMetaObject<QLineEdit>(); +engine.globalObject().setProperty("QLineEdit", lineEditClass); +//! [13] + + +//! [14] +if (hello && world) + print("hello world"); +//! [14] + + +//! [15] +if (hello && +//! [15] + + +//! [16] +0 = 0 +//! [16] + + +//! [17] +./test.js +//! [17] + + +//! [18] +foo["bar"] +//! [18] + + +//! [19] +QScriptEngine engine; +QScriptContext *context = engine.pushContext(); +context->activationObject().setProperty("myArg", 123); +engine.evaluate("var tmp = myArg + 42"); +... +engine.popContext(); +//! [19] + + +//! [20] +struct MyStruct { + int x; + int y; +}; +//! [20] + + +//! [21] +Q_DECLARE_METATYPE(MyStruct) +//! [21] + + +//! [22] +QScriptValue toScriptValue(QScriptEngine *engine, const MyStruct &s) +{ + QScriptValue obj = engine->newObject(); + obj.setProperty("x", s.x); + obj.setProperty("y", s.y); + return obj; +} + +void fromScriptValue(const QScriptValue &obj, MyStruct &s) +{ + s.x = obj.property("x").toInt32(); + s.y = obj.property("y").toInt32(); +} +//! [22] + + +//! [23] +qScriptRegisterMetaType(engine, toScriptValue, fromScriptValue); +//! [23] + + +//! [24] +MyStruct s = qscriptvalue_cast<MyStruct>(context->argument(0)); +... +MyStruct s2; +s2.x = s.x + 10; +s2.y = s.y + 20; +QScriptValue v = engine->toScriptValue(s2); +//! [24] + + +//! [25] +QScriptValue createMyStruct(QScriptContext *, QScriptEngine *engine) +{ + MyStruct s; + s.x = 123; + s.y = 456; + return engine->toScriptValue(s); +} +... +QScriptValue ctor = engine.newFunction(createMyStruct); +engine.globalObject().setProperty("MyStruct", ctor); +//! [25] + + +//! [26] +Q_DECLARE_METATYPE(QVector<int>) + +... + +qScriptRegisterSequenceMetaType<QVector<int> >(engine); +... +QVector<int> v = qscriptvalue_cast<QVector<int> >(engine->evaluate("[5, 1, 3, 2]")); +qSort(v.begin(), v.end()); +QScriptValue a = engine->toScriptValue(v); +qDebug() << a.toString(); // outputs "[1, 2, 3, 5]" +//! [26] + +//! [27] +QScriptValue mySpecialQObjectConstructor(QScriptContext *context, + QScriptEngine *engine) +{ + QObject *parent = context->argument(0).toQObject(); + QObject *object = new QObject(parent); + return engine->newQObject(object, QScriptEngine::ScriptOwnership); +} + +... + +QScriptValue ctor = engine.newFunction(mySpecialQObjectConstructor); +QScriptValue metaObject = engine.newQMetaObject(&QObject::staticMetaObject, ctor); +engine.globalObject().setProperty("QObject", metaObject); + +QScriptValue result = engine.evaluate("new QObject()"); +//! [27] diff --git a/doc/src/snippets/code/src_script_qscriptengineagent.cpp b/doc/src/snippets/code/src_script_qscriptengineagent.cpp new file mode 100644 index 0000000..361a287 --- /dev/null +++ b/doc/src/snippets/code/src_script_qscriptengineagent.cpp @@ -0,0 +1,52 @@ +/**************************************************************************** +** +** 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] +var a = Math.random() + 2; +//! [0] + + +//! [1] +function cube(a) { + return a * a * a; +} + +var a = cube(3); +//! [1] diff --git a/doc/src/snippets/code/src_script_qscriptvalue.cpp b/doc/src/snippets/code/src_script_qscriptvalue.cpp new file mode 100644 index 0000000..e02a523 --- /dev/null +++ b/doc/src/snippets/code/src_script_qscriptvalue.cpp @@ -0,0 +1,80 @@ +/**************************************************************************** +** +** 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] +QScriptEngine myEngine; +QScriptValue myObject = myEngine.newObject(); +QScriptValue myOtherObject = myEngine.newObject(); +myObject.setProperty("myChild", myOtherObject); +myObject.setProperty("name", "John Doe"); +//! [0] + + +//! [1] +QScriptValue val(&myEngine, 123); +myObject.setProperty("myReadOnlyProperty", val, QScriptValue::ReadOnly); +//! [1] + + +//! [2] +QScriptEngine engine; +engine.evaluate("function fullName() { return this.firstName + ' ' + this.lastName; }"); +engine.evaluate("somePerson = { firstName: 'John', lastName: 'Doe' }"); + +QScriptValue global = engine.globalObject(); +QScriptValue fullName = global.property("fullName"); +QScriptValue who = global.property("somePerson"); +qDebug() << fullName.call(who).toString(); // "John Doe" + +engine.evaluate("function cube(x) { return x * x * x; }"); +QScriptValue cube = global.property("cube"); +QScriptValueList args; +args << 3; +qDebug() << cube.call(QScriptValue(), args).toNumber(); // 27 +//! [2] + + +//! [3] +QScriptValue myNativeFunction(QScriptContext *ctx, QScriptEngine *) +{ + QScriptValue otherFunction = ...; + return otherFunction.call(ctx->thisObject(), ctx->argumentsObject()); +} +//! [3] diff --git a/doc/src/snippets/code/src_script_qscriptvalueiterator.cpp b/doc/src/snippets/code/src_script_qscriptvalueiterator.cpp new file mode 100644 index 0000000..f72e918 --- /dev/null +++ b/doc/src/snippets/code/src_script_qscriptvalueiterator.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/qtscript/evaluation/main.cpp b/doc/src/snippets/qtscript/evaluation/main.cpp new file mode 100644 index 0000000..01e06b6 --- /dev/null +++ b/doc/src/snippets/qtscript/evaluation/main.cpp @@ -0,0 +1,50 @@ +/**************************************************************************** +** +** 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 <QtScript> + +int main(int argc, char *argv[]) +{ + //! [0] + QScriptEngine engine; + qDebug() << "the magic number is:" << engine.evaluate("1 + 2").toNumber(); + //! [0] + return 0; +} diff --git a/doc/src/snippets/qtscript/registeringobjects/main.cpp b/doc/src/snippets/qtscript/registeringobjects/main.cpp new file mode 100644 index 0000000..9dab25a --- /dev/null +++ b/doc/src/snippets/qtscript/registeringobjects/main.cpp @@ -0,0 +1,56 @@ +/**************************************************************************** +** +** 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 <QObject> +#include <QtScript> +#include "myobject.h" + +int main(int argc, char *argv[]) +{ + //! [0] + QScriptEngine engine; + QObject *someObject = new MyObject; + QScriptValue 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/qtscript/registeringvalues/main.cpp b/doc/src/snippets/qtscript/registeringvalues/main.cpp new file mode 100644 index 0000000..6dc5b7c --- /dev/null +++ b/doc/src/snippets/qtscript/registeringvalues/main.cpp @@ -0,0 +1,52 @@ +/**************************************************************************** +** +** 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 <QtScript> + +int main(int argc, char *argv[]) +{ + QScriptEngine engine; + //! [0] + engine.globalObject().setProperty("foo", 123); + qDebug() << "foo times two is:" << engine.evaluate("foo * 2").toNumber(); + //! [0] + return 0; +} + diff --git a/doc/src/snippets/scriptdebugger.cpp b/doc/src/snippets/scriptdebugger.cpp new file mode 100644 index 0000000..2630706 --- /dev/null +++ b/doc/src/snippets/scriptdebugger.cpp @@ -0,0 +1,103 @@ +/**************************************************************************** +** +** 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 <QtGui> +#include <QtScript> +#include <QtScriptTools> + +// Perhaps shpw entire example for getting debugger up with script +int main(int argv, char **args) +{ + QApplication app(argv, args); + + QString fileName("helloscript.qs"); + QFile scriptFile(fileName); + scriptFile.open(QIODevice::ReadOnly); + QTextStream stream(&scriptFile); + QString contents = stream.readAll(); + scriptFile.close(); + + QScriptEngine *engine = new QScriptEngine(); + + QScriptEngineDebugger *debugger = new QScriptEngineDebugger(); + debugger->attachTo(engine); + + // Set up configuration with only stack and code + QWidget *widget = new QWidget; +//![0] + QWidget *codeWindow = debugger->widget(QScriptEngineDebugger::CodeWidget); + QWidget *stackWidget = debugger->widget(QScriptEngineDebugger::StackWidget); + + QLayout *layout = new QHBoxLayout; + layout->addWidget(codeWindow); + layout->addWidget(stackWidget); +//![0] + +//![1] + QAction *continueAction = debugger->action(QScriptEngineDebugger::ContinueAction); + QAction *stepOverAction = debugger->action(QScriptEngineDebugger::StepOverAction); + QAction *stepIntoAction = debugger->action(QScriptEngineDebugger::StepIntoAction); + + QToolBar *toolBar = new QToolBar; + toolBar->addAction(continueAction); +//![1] + toolBar->addAction(stepOverAction); + toolBar->addAction(stepIntoAction); + + layout->addWidget(toolBar); + continueAction->setIcon(QIcon("copy.png")); + + debugger->setAutoShowStandardWindow(false); + + widget->setLayout(layout); + widget->show(); + + QPushButton button; + QScriptValue scriptButton = engine->newQObject(&button); + engine->globalObject().setProperty("button", scriptButton); + +//![2] + debugger->action(QScriptEngineDebugger::InterruptAction)->trigger(); + engine->evaluate(contents, fileName); +//![2] + + return app.exec(); +} + |
