| 1 | <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> |
|---|
| 2 | |
|---|
| 3 | <!-- Copyright David Abrahams 2006. Distributed under the Boost --> |
|---|
| 4 | <!-- Software License, Version 1.0. (See accompanying --> |
|---|
| 5 | <!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> |
|---|
| 6 | <html> |
|---|
| 7 | <head> |
|---|
| 8 | <meta name="generator" content= |
|---|
| 9 | "HTML Tidy for Windows (vers 1st August 2002), see www.w3.org"> |
|---|
| 10 | <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> |
|---|
| 11 | <link rel="stylesheet" type="text/css" href="../boost.css"> |
|---|
| 12 | |
|---|
| 13 | <title>Boost.Python - <call_method.hpp></title> |
|---|
| 14 | </head> |
|---|
| 15 | |
|---|
| 16 | <body link="#0000ff" vlink="#800080"> |
|---|
| 17 | <table border="0" cellpadding="7" cellspacing="0" width="100%" summary= |
|---|
| 18 | "header"> |
|---|
| 19 | <tr> |
|---|
| 20 | <td valign="top" width="300"> |
|---|
| 21 | <h3><a href="../../../../index.htm"><img height="86" width="277" |
|---|
| 22 | alt="C++ Boost" src="../../../../boost.png" border="0"></a></h3> |
|---|
| 23 | </td> |
|---|
| 24 | |
|---|
| 25 | <td valign="top"> |
|---|
| 26 | <h1 align="center"><a href="../index.html">Boost.Python</a></h1> |
|---|
| 27 | |
|---|
| 28 | <h2 align="center">Header <call_method.hpp></h2> |
|---|
| 29 | </td> |
|---|
| 30 | </tr> |
|---|
| 31 | </table> |
|---|
| 32 | <hr> |
|---|
| 33 | |
|---|
| 34 | <h2>Contents</h2> |
|---|
| 35 | |
|---|
| 36 | <dl class="page-index"> |
|---|
| 37 | <dt><a href="#introduction">Introduction</a></dt> |
|---|
| 38 | |
|---|
| 39 | <dt><a href="#functions">Functions</a></dt> |
|---|
| 40 | |
|---|
| 41 | <dd> |
|---|
| 42 | <dl class="page-index"> |
|---|
| 43 | <dt><a href="#call_method-spec">call_method</a></dt> |
|---|
| 44 | </dl> |
|---|
| 45 | </dd> |
|---|
| 46 | |
|---|
| 47 | <dt><a href="#examples">Example(s)</a></dt> |
|---|
| 48 | </dl> |
|---|
| 49 | <hr> |
|---|
| 50 | |
|---|
| 51 | <h2><a name="introduction"></a>Introduction</h2> |
|---|
| 52 | |
|---|
| 53 | <p><code><boost/python/call_method.hpp></code> defines the <a href= |
|---|
| 54 | "#call_method-spec"><code>call_method</code></a> family of overloaded |
|---|
| 55 | function templates, used to invoke callable attributes of Python objects |
|---|
| 56 | from C++.</p> |
|---|
| 57 | |
|---|
| 58 | <h2><a name="functions"></a>Functions</h2> |
|---|
| 59 | <pre> |
|---|
| 60 | <a name= |
|---|
| 61 | "call_method-spec">template <class R, class A1, class A2, ... class A<i>n</i>></a> |
|---|
| 62 | R call_method(PyObject* self, char const* method, A1 const&, A2 const&, ... A<i>n</i> const&) |
|---|
| 63 | </pre> |
|---|
| 64 | |
|---|
| 65 | <dl class="function-semantics"> |
|---|
| 66 | <dt><b>Requires:</b> <code>R</code> is a pointer type, reference type, |
|---|
| 67 | or a complete type with an accessible copy constructor</dt> |
|---|
| 68 | |
|---|
| 69 | <dt><b>Effects:</b> Invokes |
|---|
| 70 | <code>self.<i>method</i>(a1, a2, ...a<i>n</i>)</code> in |
|---|
| 71 | Python, where <code>a1</code>...<code>a<i>n</i></code> are the |
|---|
| 72 | arguments to <code>call_method()</code>, converted to Python objects. |
|---|
| 73 | For a complete semantic description, see <a href="callbacks.html">this |
|---|
| 74 | page</a>.</dt> |
|---|
| 75 | |
|---|
| 76 | <dt><b>Returns:</b> The result of the Python call, converted to the C++ |
|---|
| 77 | type <code>R</code>.</dt> |
|---|
| 78 | |
|---|
| 79 | <dt><b>Rationale:</b> <code>call_method</code> is critical to |
|---|
| 80 | implementing C++ virtual functions which are overridable in Python, as |
|---|
| 81 | shown by the example below.</dt> |
|---|
| 82 | </dl> |
|---|
| 83 | |
|---|
| 84 | <h2><a name="examples"></a>Example(s)</h2> |
|---|
| 85 | The following C++ illustrates the use of <code>call_method</code> in |
|---|
| 86 | wrapping a class with a virtual function that can be overridden in |
|---|
| 87 | Python: |
|---|
| 88 | |
|---|
| 89 | <h3>C++ Module Definition</h3> |
|---|
| 90 | <pre> |
|---|
| 91 | #include <boost/python/module.hpp> |
|---|
| 92 | #include <boost/python/class.hpp> |
|---|
| 93 | #include <boost/utility.hpp> |
|---|
| 94 | #include <cstring> |
|---|
| 95 | |
|---|
| 96 | // class to be wrapped |
|---|
| 97 | class Base |
|---|
| 98 | { |
|---|
| 99 | public: |
|---|
| 100 | virtual char const* class_name() const { return "Base"; } |
|---|
| 101 | virtual ~Base(); |
|---|
| 102 | }; |
|---|
| 103 | |
|---|
| 104 | bool is_base(Base* b) |
|---|
| 105 | { |
|---|
| 106 | return !std::strcmp(b->class_name(), "Base"); |
|---|
| 107 | } |
|---|
| 108 | |
|---|
| 109 | // Wrapper code begins here |
|---|
| 110 | using namespace boost::python; |
|---|
| 111 | |
|---|
| 112 | // Callback class |
|---|
| 113 | class Base_callback : public Base |
|---|
| 114 | { |
|---|
| 115 | public: |
|---|
| 116 | Base_callback(PyObject* self) : m_self(self) {} |
|---|
| 117 | |
|---|
| 118 | char const* class_name() const { return <b>call_method</b><char const*>(m_self, "class_name"); } |
|---|
| 119 | char const* Base_name() const { return Base::class_name(); } |
|---|
| 120 | private: |
|---|
| 121 | PyObject* const m_self; |
|---|
| 122 | }; |
|---|
| 123 | |
|---|
| 124 | using namespace boost::python; |
|---|
| 125 | BOOST_PYTHON_MODULE(my_module) |
|---|
| 126 | { |
|---|
| 127 | def("is_base", is_base); |
|---|
| 128 | |
|---|
| 129 | class_<Base,Base_callback, noncopyable>("Base") |
|---|
| 130 | .def("class_name", &Base_callback::Base_name) |
|---|
| 131 | ; |
|---|
| 132 | |
|---|
| 133 | } |
|---|
| 134 | </pre> |
|---|
| 135 | |
|---|
| 136 | <h3>Python Code</h3> |
|---|
| 137 | <pre> |
|---|
| 138 | >>> from my_module import * |
|---|
| 139 | >>> class Derived(Base): |
|---|
| 140 | ... def __init__(self): |
|---|
| 141 | ... Base.__init__(self) |
|---|
| 142 | ... def class_name(self): |
|---|
| 143 | ... return self.__class__.__name__ |
|---|
| 144 | ... |
|---|
| 145 | >>> is_base(Base()) # calls the class_name() method from C++ |
|---|
| 146 | 1 |
|---|
| 147 | >>> is_base(Derived()) |
|---|
| 148 | 0 |
|---|
| 149 | </pre> |
|---|
| 150 | |
|---|
| 151 | <p>Revised |
|---|
| 152 | <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> |
|---|
| 153 | 13 November, 2002 |
|---|
| 154 | <!--webbot bot="Timestamp" endspan i-checksum="39359" --> |
|---|
| 155 | </p> |
|---|
| 156 | |
|---|
| 157 | <p><i>© Copyright <a href= |
|---|
| 158 | "../../../../people/dave_abrahams.htm">Dave Abrahams</a> 2002.</i></p> |
|---|
| 159 | </body> |
|---|
| 160 | </html> |
|---|
| 161 | |
|---|
