00001 /* 00002 $Id: py_object.h,v 1.15 2008/04/22 17:35:03 ksterker Exp $ 00003 00004 Copyright (C) 1999/2000/2001/2003 Kai Sterker <kaisterker@linuxgames.com> 00005 Copyright (C) 2001 Alexandre Courbot <alexandrecourbot@linuxgames.com> 00006 Part of the Adonthell Project http://adonthell.linuxgames.com 00007 00008 This program is free software; you can redistribute it and/or modify 00009 it under the terms of the GNU General Public License. 00010 This program is distributed in the hope that it will be useful, 00011 but WITHOUT ANY WARRANTY. 00012 00013 See the COPYING file for more details. 00014 */ 00015 00016 00017 /** 00018 * @file py_object.h 00019 * @author Kai Sterker <kaisterker@linuxgames.com> 00020 * @author Alexandre Courbot <alexandrecourbot@linuxgames.com> 00021 * 00022 * @brief Declares the py_object class. 00023 */ 00024 00025 00026 #ifndef PY_OBJECT_H 00027 #define PY_OBJECT_H 00028 00029 #include "python_class.h" 00030 00031 00032 /** 00033 * Python object class. 00034 * 00035 * Use this class to create instances of Python classes contained in Python 00036 * modules, then control their execution. You can pass an argument tuple to 00037 * the class constructor and to any method you want to run. It is further 00038 * possible to access and change attributes of the Python instance. 00039 * 00040 */ 00041 class py_object 00042 { 00043 public: 00044 /** 00045 * Default constructor. 00046 * 00047 */ 00048 py_object (); 00049 00050 /** 00051 * Destructor. 00052 * 00053 */ 00054 ~py_object (); 00055 00056 /** 00057 * Resets the script to it's post-constructor state. 00058 * 00059 */ 00060 void clear (); 00061 00062 /** 00063 * @name PyObject creation 00064 */ 00065 //@{ 00066 /** 00067 * Creates an instance of a Python class. 00068 * 00069 * @param file file name of the module to use. 00070 * @param classname name of the class to import. 00071 * @param args Python tuple containing the arguments to pass to the 00072 * Python class constructor. 00073 */ 00074 bool create_instance (string file, string classname, PyObject * args = NULL); 00075 00076 /** 00077 * Similar to create_instance, except that it will reload the module 00078 * from disk, in case it has been changed in the meantime. Mainly interesting 00079 * for script development or tools like dlgedit. 00080 * 00081 * @param file file name of the module to use. 00082 * @param classname name of the class to import. 00083 * @param args Python tuple containing the arguments to pass to the 00084 * Python class constructor. 00085 */ 00086 bool reload_instance (string file, string classname, PyObject * args = NULL); 00087 //@} 00088 00089 /** 00090 * @name PyObject method calling 00091 */ 00092 //@{ 00093 /** 00094 * Call a method of this object. 00095 * 00096 * @param name name of the method to call. 00097 * @param args Python tuple containing the arguments to pass to the method. 00098 * @return the return value of the method as PyObject. Needs to be 00099 * Py_DECREF'd when no longer needed. 00100 */ 00101 PyObject *call_method_ret (const string &name, PyObject *args = NULL) const; 00102 00103 /** 00104 * Call a method of this object. 00105 * 00106 * @param name name of the method to call. 00107 * @param args Python tuple containing the arguments to pass to the method. 00108 */ 00109 void call_method (const string & name, PyObject * args = NULL) const 00110 { 00111 PyObject *result = call_method_ret (name, args); 00112 Py_XDECREF (result); 00113 } 00114 00115 /** 00116 * Calls the run () method of this object. 00117 * Equivalent to call_method ("run", args); 00118 * 00119 * @param args Python tuple containing the arguments to pass to the method. 00120 */ 00121 void run (PyObject * args = NULL) 00122 { 00123 call_method ("run", args); 00124 } 00125 //@} 00126 00127 /** 00128 * @name PyObject member access 00129 */ 00130 //@{ 00131 /** 00132 * Tests whether the object contains a certain attribute (i.e. method 00133 * or variable). 00134 * 00135 * @param name Name of the attribute to test for 00136 * @return <b>true</b> if the attribute exists, <b>false</b> otherwise. 00137 */ 00138 bool has_attribute (const std::string & name); 00139 00140 /** 00141 * Returns a new reference to an attribute of this object. 00142 * 00143 * @param name Name of the attribute to access 00144 * @return New reference to the attribute or NULL on error 00145 */ 00146 PyObject* get_attribute (const string & name) const; 00147 00148 /** 00149 * Returns the given attribute as integer value. 00150 * 00151 * @param name Name of the attribute to access 00152 * @return An integer. 00153 */ 00154 s_int32 get_attribute_int (const string & name); 00155 00156 /** 00157 * Returns the given attribute as string value. 00158 * 00159 * @param name Name of the attribute to access 00160 * @return A string. 00161 */ 00162 string get_attribute_string (const string & name); 00163 00164 /** 00165 * Assign a new attribute to the module, overriding an existing 00166 * attribute of the same name. 00167 * 00168 * @param name The attribute's name 00169 * @param value The attribute's value 00170 */ 00171 void set_attribute (const string & name, PyObject *value); 00172 00173 /** 00174 * Assign a new integer attribute to the module, overriding an 00175 * existing attribute of the same name. 00176 * 00177 * @param name The attribute's name 00178 * @param value The attribute's value 00179 */ 00180 void set_attribute_int (const string & name, s_int32 value); 00181 00182 /** 00183 * Assign a new string attribute to the module, overriding an 00184 * existing attribute of the same name. 00185 * 00186 * @param name The attribute's name 00187 * @param value The attribute's value 00188 */ 00189 void set_attribute_string (const string & name, const string & value); 00190 //@} 00191 00192 /** 00193 * @name Member access 00194 */ 00195 //@{ 00196 /** 00197 * Direct access to the instance object. The default behaviour is to 00198 * increase the instance's reference count, so that this method can 00199 * be safely called from Python scripts. 00200 * 00201 * @param incref whether to increase the reference count. 00202 * @return the Python class instance. 00203 */ 00204 PyObject *get_instance (const bool & incref = true) const 00205 { 00206 if (incref) 00207 { 00208 Py_XINCREF (Instance); 00209 } 00210 return Instance; 00211 } 00212 00213 /** 00214 * Returns the class name of this object. This is the name of the 00215 * wrapped Python class. 00216 * 00217 * @return class name of this object. 00218 */ 00219 std::string class_name () const 00220 { 00221 return Classname; 00222 } 00223 00224 /** 00225 * Returns the file name of this object. This is the name of the 00226 * Python module containing the wrapped class. 00227 * 00228 * @return fiöe name of this object. 00229 */ 00230 std::string file_name () const 00231 { 00232 return Filename; 00233 } 00234 //@} 00235 00236 protected: 00237 /** 00238 * The python class instance wrapped by %py_object 00239 */ 00240 PyObject *Instance; 00241 00242 private: 00243 /** 00244 * Helper for create_instance and reload_instance 00245 * 00246 */ 00247 bool instanciate (PyObject*, string, string, PyObject*); 00248 00249 /** 00250 * The class name of the current script 00251 */ 00252 std::string Classname; 00253 00254 /** 00255 * The file name of the current script 00256 */ 00257 std::string Filename; 00258 }; 00259 00260 #endif // PY_OBJECT_H