← Back to branch summary

~oif-team/ubuntu/natty/qt4-x11/xi2.1

« back to all changes in this revision

Viewing changes to doc/src/qtscriptextensions.qdoc

  • Committer: Bazaar Package Importer
  • Author(s): Alessandro Ghersi
  • Date: 2009-11-02 18:30:08 UTC
  • mfrom: (1.2.2 upstream)
  • mto: (15.2.5 experimental)
  • mto: This revision was merged to the branch mainline in revision 88.
  • Revision ID: james.westby@ubuntu.com-20091102183008-b6a4gcs128mvfb3m
Tags: upstream-4.6.0~beta1
Import upstream version 4.6.0~beta1

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/src/qtscriptextensions.qdoc
1
 
/****************************************************************************
2
 
**
3
 
** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
4
 
** Contact: Nokia Corporation (qt-info@nokia.com)
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 http://www.qtsoftware.com/contact.
38
 
** $QT_END_LICENSE$
39
 
**
40
 
****************************************************************************/
41
 
 
42
 
/****************************************************************************
43
 
**
44
 
** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
45
 
** Contact: Nokia Corporation (qt-info@nokia.com)
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
 
*/