• Main Page
  • Related Pages
  • Classes
  • Files
  • File List
  • File Members

py_object.h

Go to the documentation of this file.
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

Generated on Mon Sep 12 2011 for Adonthell by  doxygen 1.7.1