From 0445e84888cd0d2f9a8c90f3a88317ab05c690d7 Mon Sep 17 00:00:00 2001 From: Nico Vertriest Date: Fri, 16 Jan 2015 11:54:36 +0100 Subject: Doc: Moved the example documentation to correct locations MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit And fix the \snippet commands to use the correct paths. Also edited dependencies qdocconf files Task-number: QTBUG-43810 Change-Id: I3c2fb6d2a48900a9b5651225381707c9ec25065a Reviewed-by: Martin Smith Reviewed-by: Topi Reiniö --- .../doc/images/context2d-example-smileysmile.png | Bin 0 -> 3457 bytes .../context2d/doc/images/context2d-example.png | Bin 0 -> 14160 bytes examples/script/context2d/doc/src/context2d.qdoc | 339 +++++++++++++++++++++ .../doc/images/defaultprototypes-example.png | Bin 0 -> 5840 bytes .../doc/src/defaultprototypes.qdoc | 124 ++++++++ .../script/helloscript/doc/src/helloscript.qdoc | 128 ++++++++ 6 files changed, 591 insertions(+) create mode 100644 examples/script/context2d/doc/images/context2d-example-smileysmile.png create mode 100644 examples/script/context2d/doc/images/context2d-example.png create mode 100644 examples/script/context2d/doc/src/context2d.qdoc create mode 100644 examples/script/defaultprototypes/doc/images/defaultprototypes-example.png create mode 100644 examples/script/defaultprototypes/doc/src/defaultprototypes.qdoc create mode 100644 examples/script/helloscript/doc/src/helloscript.qdoc (limited to 'examples') diff --git a/examples/script/context2d/doc/images/context2d-example-smileysmile.png b/examples/script/context2d/doc/images/context2d-example-smileysmile.png new file mode 100644 index 0000000..369f32e Binary files /dev/null and b/examples/script/context2d/doc/images/context2d-example-smileysmile.png differ diff --git a/examples/script/context2d/doc/images/context2d-example.png b/examples/script/context2d/doc/images/context2d-example.png new file mode 100644 index 0000000..0c12754 Binary files /dev/null and b/examples/script/context2d/doc/images/context2d-example.png differ diff --git a/examples/script/context2d/doc/src/context2d.qdoc b/examples/script/context2d/doc/src/context2d.qdoc new file mode 100644 index 0000000..55c441a --- /dev/null +++ b/examples/script/context2d/doc/src/context2d.qdoc @@ -0,0 +1,339 @@ +/**************************************************************************** +** +** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/legal +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and Digia. For licensing terms and +** conditions see http://qt.digia.com/licensing. For further information +** use the contact form at http://qt.digia.com/contact-us. +** +** GNU Free Documentation License Usage +** 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. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: http://www.gnu.org/copyleft/fdl.html. +** $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{} + element. It can be used to draw graphics via scripting. A good + resource for learning more about the HTML \c{} 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{} element is typically + used in a web browser. The following HTML snippet defines a + canvas of size 400x400 pixels with id \c{mycanvas}: + + \code + Fallback content goes here. + \endcode + + To draw on the canvas, we must first obtain a reference to the + DOM element corresponding to the \c{} tag and then call + the element's getContext() function. The resulting object + implements the Context2D API that we use to draw. + + \code + + \endcode + + When the page is rendered by a browser that supports the + \c{} 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 + \li Create an Environment. + \li Create a Context2D, and a QContext2DCanvas widget to render it. + \li Add the canvas object to the environment; this will enable + scripts to obtain a reference to it. + \li 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 script/context2d/context2d.h 0 + + The properties define various aspects of the Context2D + configuration. + + \snippet script/context2d/context2d.h 1 + + The slots define the operations that can be performed. + + \snippet 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 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 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 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 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 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 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 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 script/context2d/qcontext2dcanvas.cpp 1 + + The paintEvent() function simply paints the contents that + was last received from the Context2D object. + + \snippet 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 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 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 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 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 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 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 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 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 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 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 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 script/context2d/window.cpp 1 + + The window contains a list widget that is populated with + available scripts (read from a \c{scripts/} folder). + + \snippet script/context2d/window.cpp 2 + + When an item is selected, the corresponding script is + evaluated in the environment. + + \snippet 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 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/examples/script/defaultprototypes/doc/images/defaultprototypes-example.png b/examples/script/defaultprototypes/doc/images/defaultprototypes-example.png new file mode 100644 index 0000000..72fe3c4 Binary files /dev/null and b/examples/script/defaultprototypes/doc/images/defaultprototypes-example.png differ diff --git a/examples/script/defaultprototypes/doc/src/defaultprototypes.qdoc b/examples/script/defaultprototypes/doc/src/defaultprototypes.qdoc new file mode 100644 index 0000000..31de75d --- /dev/null +++ b/examples/script/defaultprototypes/doc/src/defaultprototypes.qdoc @@ -0,0 +1,124 @@ +/**************************************************************************** +** +** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/legal +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and Digia. For licensing terms and +** conditions see http://qt.digia.com/licensing. For further information +** use the contact form at http://qt.digia.com/contact-us. +** +** GNU Free Documentation License Usage +** 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. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: http://www.gnu.org/copyleft/fdl.html. +** $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 Qt Script 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 script/defaultprototypes/prototypes.h 0 + + A single property, \c{text}, is defined, along with a slot, + \c{toString}. + + \snippet 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 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 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 script/defaultprototypes/main.cpp 0 + + The relevant C++ types must be made known to Qt's meta type + system. + + \snippet 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 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 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 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/examples/script/helloscript/doc/src/helloscript.qdoc b/examples/script/helloscript/doc/src/helloscript.qdoc new file mode 100644 index 0000000..aa6563b --- /dev/null +++ b/examples/script/helloscript/doc/src/helloscript.qdoc @@ -0,0 +1,128 @@ +/**************************************************************************** +** +** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/legal +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and Digia. For licensing terms and +** conditions see http://qt.digia.com/licensing. For further information +** use the contact form at http://qt.digia.com/contact-us. +** +** GNU Free Documentation License Usage +** 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. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: http://www.gnu.org/copyleft/fdl.html. +** $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 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 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 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 script/helloscript/main.cpp 3 + + The contents of the script file are read. + + \snippet 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 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 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 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 code/doc_src_examples_hellotr.qdoc 3 + + but instead will have + + \snippet 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!". +*/ -- cgit v1.2.1