diff options
author | Frederik Gladhorn <frederik.gladhorn@theqtcompany.com> | 2015-02-13 13:10:52 +0100 |
---|---|---|
committer | Frederik Gladhorn <frederik.gladhorn@theqtcompany.com> | 2015-02-13 13:10:52 +0100 |
commit | a6826cbe243a22f25b451d0aaa5ae4536f9f3656 (patch) | |
tree | 2900595e38fdf730aae6f37c82473d43cc3b0f65 /examples/script/defaultprototypes/doc | |
parent | 6c387974ab827e53d96d9106a44df29584c1e2be (diff) | |
parent | c3d90662dfc65dd5f0dd8e5cd31d1bafb3328e7c (diff) |
Merge remote-tracking branch 'origin/5.4' into dev
Change-Id: Ic32f5bd17782285305aaa01694f1a78851b882eb
Diffstat (limited to 'examples/script/defaultprototypes/doc')
-rw-r--r-- | examples/script/defaultprototypes/doc/images/defaultprototypes-example.png | bin | 0 -> 5840 bytes | |||
-rw-r--r-- | examples/script/defaultprototypes/doc/src/defaultprototypes.qdoc | 124 |
2 files changed, 124 insertions, 0 deletions
diff --git a/examples/script/defaultprototypes/doc/images/defaultprototypes-example.png b/examples/script/defaultprototypes/doc/images/defaultprototypes-example.png Binary files differnew file mode 100644 index 0000000..72fe3c4 --- /dev/null +++ b/examples/script/defaultprototypes/doc/images/defaultprototypes-example.png diff --git a/examples/script/defaultprototypes/doc/src/defaultprototypes.qdoc b/examples/script/defaultprototypes/doc/src/defaultprototypes.qdoc new file mode 100644 index 0000000..98e6805 --- /dev/null +++ b/examples/script/defaultprototypes/doc/src/defaultprototypes.qdoc @@ -0,0 +1,124 @@ +/**************************************************************************** +** +** Copyright (C) 2015 The Qt Company Ltd. +** Contact: http://www.qt.io/licensing/ +** +** 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 The Qt Company. For licensing terms +** and conditions see http://www.qt.io/terms-conditions. For further +** information use the contact form at http://www.qt.io/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. +*/ |