source: trunk/src/script/qscriptclass.cpp@ 76

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

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

File size: 21.9 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 QtScript module 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#include "qscriptclass.h"
43
44#ifndef QT_NO_SCRIPT
45
46#include <QtCore/qstringlist.h>
47
48#include "qscriptclasspropertyiterator.h"
49#include "qscriptstring.h"
50#include "qscriptstring_p.h"
51#include "qscriptclass_p.h"
52#include "qscriptclassinfo_p.h"
53#include "qscriptengine_p.h"
54#include "qscriptcontext_p.h"
55#include "qscriptvalueimpl_p.h"
56#include "qscriptmember_p.h"
57#include "qscriptobject_p.h"
58#include "qscriptfunction_p.h"
59
60Q_DECLARE_METATYPE(QScriptContext*)
61Q_DECLARE_METATYPE(QScriptValueList)
62
63QT_BEGIN_NAMESPACE
64
65/*!
66 \since 4.4
67 \class QScriptClass
68
69 \brief The QScriptClass class provides an interface for defining custom behavior of (a class of) Qt Script objects.
70
71 \ingroup script
72 \mainclass
73
74 The QScriptClass class defines an interface for handling various
75 aspects of interaction with the Qt Script objects associated with
76 the class. Such objects are created by calling
77 QScriptEngine::newObject(), passing a pointer to the QScriptClass as
78 argument.
79
80 By subclassing QScriptClass, you can define precisely how access to
81 properties of the objects that use your class is handled. This
82 enables a fully dynamic handling of properties, e.g. it's more
83 powerful than QScriptEngine::newQObject(). For example, you can use
84 QScriptClass to implement array-type objects (i.e. objects that
85 handle the \c{length} property, and properties whose names are valid
86 array indexes, in a special way), or to implement a "live"
87 (runtime-defined) proxy to an underlying object.
88
89 If you just need to handle access to a set of properties that are
90 known at the time an object is created (i.e. "semi-statically"), you
91 might consider using QScriptValue::setProperty() to define
92 getter/setter functions for the relevant properties, rather than
93 subclassing QScriptClass.
94
95 Reimplement queryProperty() to specify which properties are handled
96 in a custom way by your script class (i.e. should be
97 \bold{delegated} to the QScriptClass), and which properties should
98 be handled just like normal Qt Script object properties.
99
100 Reimplement property() and setProperty() to perform the actual
101 access (read or write) to the properties that your class
102 handles. Additionally, you can reimplement propertyFlags() to
103 specify custom flags for your properties.
104
105 Reimplement newIterator() to provide an iterator for objects of your
106 custom class. This is only necessary if objects of your class can
107 have custom properties that you want to be reported when an object
108 is used together with the QScriptValueIterator class, or when an
109 object is used in a for-in enumeration statement in a script.
110
111 When implementing custom classes of objects, you typically use
112 QScriptValue::setData() to store instance-specific data as part of
113 object initialization; the data won't be accessible from scripts
114 directly, but you can access it in e.g. your reimplementations of
115 property() and setProperty() (by calling QScriptValue::data()) to
116 perform custom processing.
117
118 Reimplement prototype() to provide a custom prototype object for
119 your script class.
120
121 Reimplement supportsExtension() and extension() if your custom
122 script class supports one or more of the extensions specified by the
123 Extension enum.
124
125 \sa QScriptClassPropertyIterator, QScriptEngine::newObject(), {Custom Script Class Example}
126*/
127
128/*!
129 \enum QScriptClass::Extension