source: trunk/doc/src/qtscriptextensions.qdoc@ 321

Last change on this file since 321 was 2, checked in by Dmitry A. Kuminov, 16 years ago

Initially imported qt-all-opensource-src-4.5.1 from Trolltech.

File size: 6.6 KB
Line 
1/****************************************************************************
2**
3** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
4** Contact: Qt Software Information ([email protected])
5**
6** This file is part of the documentation of the Qt Toolkit.
7**
8** $QT_BEGIN_LICENSE:LGPL$
9** Commercial Usage
10** Licensees holding valid Qt Commercial licenses may use this file in
11** accordance with the Qt Commercial License Agreement provided with the
12** Software or, alternatively, in accordance with the terms contained in
13** a written agreement between you and Nokia.
14**
15** GNU Lesser General Public License Usage
16** Alternatively, this file may be used under the terms of the GNU Lesser
17** General Public License version 2.1 as published by the Free Software
18** Foundation and appearing in the file LICENSE.LGPL included in the
19** packaging of this file. Please review the following information to
20** ensure the GNU Lesser General Public License version 2.1 requirements
21** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
22**
23** In addition, as a special exception, Nokia gives you certain
24** additional rights. These rights are described in the Nokia Qt LGPL
25** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this
26** package.
27**
28** GNU General Public License Usage
29** Alternatively, this file may be used under the terms of the GNU
30** General Public License version 3.0 as published by the Free Software
31** Foundation and appearing in the file LICENSE.GPL included in the
32** packaging of this file. Please review the following information to
33** ensure the GNU General Public License version 3.0 requirements will be
34** met: http://www.gnu.org/copyleft/gpl.html.
35**
36** If you are unsure which license is appropriate for your use, please
37** contact the sales department at [email protected].
38** $QT_END_LICENSE$
39**
40****************************************************************************/
41
42/****************************************************************************
43**
44** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
45** Contact: Qt Software Information ([email protected])
46**
47** This file is part of the Qt GUI Toolkit.
48** EDITIONS: FREE, PROFESSIONAL, ENTERPRISE
49**
50****************************************************************************/
51
52/*!
53 \page qtscriptextensions.html
54 \title Creating QtScript Extensions
55 \ingroup scripting
56 \brief A guide to creating and using QtScript extensions.
57
58 QtScript extensions can make additional functionality available to scripts
59 evaluated by a QScriptEngine. Extensions are imported by calling
60 the QScriptEngine::importExtension() function.
61
62 There are three ways to create an extension:
63
64 \list
65 \o Subclass QScriptExtensionPlugin and implement the desired functionality.
66 \o Implement the functionality in a script file.
67 \o Use a hybrid approach, where part of the functionality is implemented in a
68 QScriptExtensionPlugin, and part is implemented in a script file.
69 \endlist
70
71 The (dot-qualified) extension name is used to determine the path (relative to
72 the application's plugin path) where QScriptEngine will look for the script
73 file that will initialize the extension; if a file called \c{__init__.js}
74 (usually located in \c{[application plugin path]/script/foo/}) is
75 found in the corresponding folder, its contents will be evaluated by the engine
76 when the extension is imported.
77 As an example, if the extension is called \c{"foo.bar.baz"}, the engine will look
78 for \c{__init__.js} in \c{foo/bar/baz}. Additionally, before importing
79 \c{"foo.bar.baz"}, the engine will ensure that the extensions \c{"foo"} and \c{"foo.bar"}
80 are imported, locating and evaluating the corresponding \c{__init__.js}
81 in the same manner (in folders \c{foo} and \c{foo/bar}, respectively).
82
83 The contents of \c{__init__.js} are evaluated in a new QScriptContext,
84 as if it were the body of a function. The engine's Global Object acts as
85 the \c{this} object. The following local variables are initially available
86 to the script:
87
88 \list
89 \o \bold{__extension__}: The name of the extension (e.g. \c{"foo.bar.baz"}).
90 \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().)
91 \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.
92 \endlist
93
94 An example of a simple \c{__init__.js}:
95
96 \snippet doc/src/snippets/code/doc_src_qtscriptextensions.qdoc 0
97
98 QScriptEngine will look for a QScriptExtensionPlugin that provides
99 the relevant extension by querying each plugin for its keys()
100 until a match is found. The plugin's initialize() function will be
101 called \bold{after} the relevant \c{__init__.js} (if any) has been
102 evaluated.
103
104 Continuining with the example of our imaginary extension \c{"foo.bar.baz"},
105 the following steps will be performed by QScriptEngine::importExtension():
106
107 \list
108 \o If it exists, \c{foo/__init__.js} is evaluated.
109 \o If a plugin with \c{"foo"} in its list of keys is found, its initialize() function is called with \c{"foo"} as key.
110 \o If it exists, \c{foo/bar/__init__.js} is evaluated.
111 \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.
112 \o If it exists, \c{foo/bar/baz/__init__.js} is evaluated.
113 \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.
114 \endlist
115
116 \section1 Static Extensions
117
118 When an extension is compiled and linked into your application as a
119 static plugin, Qt Script will look for the optional \c{__init__.js}
120 script in a resource, prefixed by \c{:/qtscriptextension}. For example,
121 if the extension key is "foo.bar", Qt Script will evaluate the contents
122 of the file \c{:/qtscriptextension/foo/bar/__init__.js}, if it
123 exists. Note that if the resource is built into the plugin, you may
124 need to use the Q_INIT_RESOURCE() macro to initialize the resource
125 before importing the extension.
126*/
Note: See TracBrowser for help on using the repository browser.