1 |
/* |
/* |
2 |
$Id$ |
$Id$ |
3 |
|
|
4 |
Copyright (C) 1999/2000/2001/2003 Kai Sterker <kaisterker@linuxgames.com> |
Copyright (C) 1999/2000/2001/2003 Kai Sterker <kaisterker@linuxgames.com> |
5 |
Copyright (C) 2001 Alexandre Courbot <alexandrecourbot@linuxgames.com> |
Copyright (C) 2001 Alexandre Courbot <alexandrecourbot@linuxgames.com> |
6 |
Part of the Adonthell Project http://adonthell.linuxgames.com |
Part of the Adonthell Project http://adonthell.linuxgames.com |
7 |
|
|
8 |
Adonthell is free software; you can redistribute it and/or modify |
Adonthell is free software; you can redistribute it and/or modify |
9 |
it under the terms of the GNU General Public License as published by |
it under the terms of the GNU General Public License as published by |
10 |
the Free Software Foundation; either version 2 of the License, or |
the Free Software Foundation; either version 2 of the License, or |
11 |
(at your option) any later version. |
(at your option) any later version. |
12 |
|
|
13 |
Adonthell is distributed in the hope that it will be useful, |
Adonthell is distributed in the hope that it will be useful, |
14 |
but WITHOUT ANY WARRANTY; without even the implied warranty of |
but WITHOUT ANY WARRANTY; without even the implied warranty of |
15 |
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the |
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the |
16 |
GNU General Public License for more details. |
GNU General Public License for more details. |
17 |
|
|
18 |
You should have received a copy of the GNU General Public License |
You should have received a copy of the GNU General Public License |
19 |
along with Adonthell; if not, write to the Free Software |
along with Adonthell; if not, write to the Free Software |
20 |
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA |
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA |
21 |
*/ |
*/ |
22 |
|
|
23 |
|
|
24 |
/** |
/** |
25 |
* @file python/script.h |
* @file python/script.h |
26 |
* @author Kai Sterker <kaisterker@linuxgames.com> |
* @author Kai Sterker <kaisterker@linuxgames.com> |
27 |
* @author Alexandre Courbot <alexandrecourbot@linuxgames.com> |
* @author Alexandre Courbot <alexandrecourbot@linuxgames.com> |
28 |
* |
* |
29 |
* @brief Makes a python script available to C++ code. |
* @brief Makes a python script available to C++ code. |
30 |
*/ |
*/ |
31 |
|
|
32 |
|
|
33 |
#ifndef PYTHON_SCRIPT_H |
#ifndef PYTHON_SCRIPT_H |
34 |
#define PYTHON_SCRIPT_H |
#define PYTHON_SCRIPT_H |
35 |
|
|
36 |
#include "python/python.h" |
#include "python/python.h" |
37 |
|
|
38 |
namespace python |
namespace python |
39 |
{ |
{ |
40 |
/** |
/** |
41 |
* Python script class. |
* Python script class. |
42 |
* |
* |
43 |
* Use this class to create instances of Python classes contained in Python |
* Use this class to create instances of Python classes contained in Python |
44 |
* modules, then control their execution. You can pass an argument tuple to |
* modules, then control their execution. You can pass an argument tuple to |
45 |
* the class constructor and to any method you want to run. It is further |
* the class constructor and to any method you want to run. It is further |
46 |
* possible to access and change attributes of the Python instance. |
* possible to access and change attributes of the Python instance. |
47 |
* |
* |
48 |
*/ |
*/ |
49 |
class script |
class script |
50 |
{ |
{ |
51 |
public: |
public: |
52 |
/** |
/** |
53 |
* Default constructor. |
* Default constructor. |
54 |
* |
* |
55 |
*/ |
*/ |
56 |
script (); |
script (); |
57 |
|
|
58 |
/** |
/** |
59 |
* Destructor. |
* Destructor. |
60 |
* |
* |
61 |
*/ |
*/ |
62 |
virtual ~script (); |
virtual ~script (); |
63 |
|
|
64 |
/** |
/** |
65 |
* Resets the script to it's post-constructor state. |
* Resets the script to it's post-constructor state. |
66 |
* |
* |
67 |
*/ |
*/ |
68 |
void clear (); |
void clear (); |
69 |
|
|
70 |
/** |
/** |
71 |
* @name PyObject creation |
* @name PyObject creation |
72 |
*/ |
*/ |
73 |
//@{ |
//@{ |
74 |
/** |
/** |
75 |
* Creates an instance of a Python class. |
* Creates an instance of a Python class. |
76 |
* |
* |
77 |
* @param file file name of the module to use. |
* @param file file name of the module to use. |
78 |
* @param classname name of the class to import. |
* @param classname name of the class to import. |
79 |
* @param args Python tuple containing the arguments to pass to the |
* @param args Python tuple containing the arguments to pass to the |
80 |
* Python class constructor. |
* Python class constructor. |
81 |
*/ |
*/ |
82 |
bool create_instance (const string & file, const string & classname, PyObject * args = NULL); |
bool create_instance (const string & file, const string & classname, PyObject * args = NULL); |
83 |
|
|
84 |
/** |
/** |
85 |
* Similar to create_instance, except that it will reload the module |
* Similar to create_instance, except that it will reload the module |
86 |
* from disk, in case it has been changed in the meantime. Mainly interesting |
* from disk, in case it has been changed in the meantime. Mainly interesting |
87 |
* for script development or tools like dlgedit. |
* for script development or tools like dlgedit. |
88 |
* |
* |
89 |
* @param file file name of the module to use. |
* @param file file name of the module to use. |
90 |
* @param classname name of the class to import. |
* @param classname name of the class to import. |
91 |
* @param args Python tuple containing the arguments to pass to the |
* @param args Python tuple containing the arguments to pass to the |
92 |
* Python class constructor. |
* Python class constructor. |
93 |
*/ |
*/ |
94 |
bool reload_instance (const string & file, const string & classname, PyObject * args = NULL); |
bool reload_instance (const string & file, const string & classname, PyObject * args = NULL); |
95 |
//@} |
//@} |
96 |
|
|
97 |
/** |
/** |
98 |
* @name PyObject method calling |
* @name PyObject method calling |
99 |
*/ |
*/ |
100 |
//@{ |
//@{ |
101 |
/** |
/** |
102 |
* Call a method of this object. |
* Call a method of this object. |
103 |
* |
* |
104 |
* @param name name of the method to call. |
* @param name name of the method to call. |
105 |
* @param args Python tuple containing the arguments to pass to the method. |
* @param args Python tuple containing the arguments to pass to the method. |
106 |
* @return the return value of the method as PyObject. Needs to be |
* @return the return value of the method as PyObject. Needs to be |
107 |
* Py_DECREF'd when no longer needed. |
* Py_DECREF'd when no longer needed. |
108 |
*/ |
*/ |
109 |
PyObject *call_method_ret (const string &name, PyObject *args = NULL) const; |
PyObject *call_method_ret (const string &name, PyObject *args = NULL) const; |
110 |
|
|
111 |
/** |
/** |
112 |
* Call a method of this object. |
* Call a method of this object. |
113 |
* |
* |
114 |
* @param name name of the method to call. |
* @param name name of the method to call. |
115 |
* @param args Python tuple containing the arguments to pass to the method. |
* @param args Python tuple containing the arguments to pass to the method. |
116 |
*/ |
*/ |
117 |
void call_method (const string & name, PyObject * args = NULL) const |
void call_method (const string & name, PyObject * args = NULL) const |
118 |
{ |
{ |
119 |
PyObject *result = call_method_ret (name, args); |
PyObject *result = call_method_ret (name, args); |
120 |
Py_XDECREF (result); |
Py_XDECREF (result); |
121 |
} |
} |
122 |
//@} |
//@} |
123 |
|
|
124 |
/** |
/** |
125 |
* @name PyObject member access |
* @name PyObject member access |
126 |
*/ |
*/ |
127 |
//@{ |
//@{ |
128 |
/** |
/** |
129 |
* Tests whether the object contains a certain attribute (i.e. method |
* Tests whether the object contains a certain attribute (i.e. method |
130 |
* or variable). |
* or variable). |
131 |
* |
* |
132 |
* @param name Name of the attribute to test for |
* @param name Name of the attribute to test for |
133 |
* @return <b>true</b> if the attribute exists, <b>false</b> otherwise. |
* @return <b>true</b> if the attribute exists, <b>false</b> otherwise. |
134 |
*/ |
*/ |
135 |
bool has_attribute (const string & name) const; |
bool has_attribute (const string & name) const; |
136 |
|
|
137 |
/** |
/** |
138 |
* Returns a new reference to an attribute of this object. |
* Returns a new reference to an attribute of this object. |
139 |
* |
* |
140 |
* @param name Name of the attribute to access |
* @param name Name of the attribute to access |
141 |
* @return New reference to the attribute or NULL on error |
* @return New reference to the attribute or NULL on error |
142 |
*/ |
*/ |
143 |
PyObject* get_attribute (const string & name) const; |
PyObject* get_attribute (const string & name) const; |
144 |
|
|
145 |
/** |
/** |
146 |
* Returns the given attribute as integer value. |
* Returns the given attribute as integer value. |
147 |
* |
* |
148 |
* @param name Name of the attribute to access |
* @param name Name of the attribute to access |
149 |
* @return An integer. |
* @return An integer. |
150 |
*/ |
*/ |
151 |
s_int32 get_attribute_int (const string & name) const; |
s_int32 get_attribute_int (const string & name) const; |
152 |
|
|
153 |
/** |
/** |
154 |
* Returns the given attribute as string value. |
* Returns the given attribute as string value. |
155 |
* |
* |
156 |
* @param name Name of the attribute to access |
* @param name Name of the attribute to access |
157 |
* @return A string. |
* @return A string. |
158 |
*/ |
*/ |
159 |
std::string get_attribute_string (const string & name) const; |
std::string get_attribute_string (const string & name) const; |
160 |
|
|
161 |
/** |
/** |
162 |
* Assign a new attribute to the module, overriding an existing |
* Assign a new attribute to the module, overriding an existing |
163 |
* attribute of the same name. |
* attribute of the same name. |
164 |
* |
* |
165 |
* @param name The attribute's name |
* @param name The attribute's name |
166 |
* @param value The attribute's value |
* @param value The attribute's value |
167 |
*/ |
*/ |
168 |
void set_attribute (const string & name, PyObject *value); |
void set_attribute (const string & name, PyObject *value); |
169 |
|
|
170 |
/** |
/** |
171 |
* Assign a new integer attribute to the module, overriding an |
* Assign a new integer attribute to the module, overriding an |
172 |
* existing attribute of the same name. |
* existing attribute of the same name. |
173 |
* |
* |
174 |
* @param name The attribute's name |
* @param name The attribute's name |
175 |
* @param value The attribute's value |
* @param value The attribute's value |
176 |
*/ |
*/ |
177 |
void set_attribute_int (const string & name, s_int32 value); |
void set_attribute_int (const string & name, s_int32 value); |
178 |
|
|
179 |
/** |
/** |
180 |
* Assign a new string attribute to the module, overriding an |
* Assign a new string attribute to the module, overriding an |
181 |
* existing attribute of the same name. |
* existing attribute of the same name. |
182 |
* |
* |
183 |
* @param name The attribute's name |
* @param name The attribute's name |
184 |
* @param value The attribute's value |
* @param value The attribute's value |
185 |
*/ |
*/ |
186 |
void set_attribute_string (const string & name, const string & value); |
void set_attribute_string (const string & name, const string & value); |
187 |
//@} |
//@} |
188 |
|
|
189 |
/** |
/** |
190 |
* @name Member access |
* @name Member access |
191 |
*/ |
*/ |
192 |
//@{ |
//@{ |
193 |
/** |
/** |
194 |
* Direct access to the instance object. The default behaviour is to |
* Direct access to the instance object. The default behaviour is to |
195 |
* increase the instance's reference count, so that this method can |
* increase the instance's reference count, so that this method can |
196 |
* be safely called from Python scripts. |
* be safely called from Python scripts. |
197 |
* |
* |
198 |
* @param incref whether to increase the reference count. |
* @param incref whether to increase the reference count. |
199 |
* @return the Python class instance. |
* @return the Python class instance. |
200 |
*/ |
*/ |
201 |
PyObject *get_instance (const bool & incref = true) const |
PyObject *get_instance (const bool & incref = true) const |
202 |
{ |
{ |
203 |
if (incref) Py_XINCREF (Instance); |
if (incref) Py_XINCREF (Instance); |
204 |
return Instance; |
return Instance; |
205 |
} |
} |
206 |
|
|
207 |
/** |
/** |
208 |
* Returns the class name of this object. This is the name of the |
* Returns the class name of this object. This is the name of the |
209 |
* wrapped Python class. |
* wrapped Python class. |
210 |
* |
* |
211 |
* @return class name of this object. |
* @return class name of this object. |
212 |
*/ |
*/ |
213 |
std::string class_name () const |
std::string class_name () const |
214 |
{ |
{ |
215 |
return Classname; |
return Classname; |
216 |
} |
} |
217 |
|
|
218 |
/** |
/** |
219 |
* Returns the file name of this object. This is the name of the |
* Returns the file name of this object. This is the name of the |
220 |
* Python module containing the wrapped class. |
* Python module containing the wrapped class. |
221 |
* |
* |
222 |
* @return fiöe name of this object. |
* @return fiöe name of this object. |
223 |
*/ |
*/ |
224 |
std::string file_name () const |
std::string file_name () const |
225 |
{ |
{ |
226 |
return Filename; |
return Filename; |
227 |
} |
} |
228 |
//@} |
//@} |
229 |
|
|
230 |
#ifndef SWIG |
#ifndef SWIG |
231 |
GET_TYPE_NAME_VIRTUAL(python::script); |
/// allow script to be passed through SWIG |
232 |
#endif // SWIG |
GET_TYPE_NAME_VIRTUAL(python::script); |
233 |
|
#endif // SWIG |
234 |
protected: |
|
235 |
/** |
protected: |
236 |
* The python class instance wrapped by %script |
/// The python class instance wrapped by %script |
237 |
*/ |
PyObject *Instance; |
238 |
PyObject *Instance; |
|
239 |
|
private: |
240 |
private: |
/// Helper for create_instance and reload_instance |
241 |
/** |
bool instanciate (PyObject*, const std::string &, const std::string &, PyObject*); |
242 |
* Helper for create_instance and reload_instance |
|
243 |
* |
/// The class name of the current script |
244 |
*/ |
std::string Classname; |
245 |
bool instanciate (PyObject*, const std::string &, const std::string &, PyObject*); |
|
246 |
|
/// The file name of the current script |
247 |
/** |
std::string Filename; |
248 |
* The class name of the current script |
}; |
249 |
*/ |
} |
250 |
std::string Classname; |
#endif // PYTHON_SCRIPT_H |
|
|
|
|
/** |
|
|
* The file name of the current script |
|
|
*/ |
|
|
std::string Filename; |
|
|
}; |
|
|
} |
|
|
#endif // PYTHON_SCRIPT_H |
|