Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

source: downloads/boost_1_34_1/libs/python/doc/v2/wrapper.html @ 45

Last change on this file since 45 was 29, checked in by landauf, 17 years ago

updated boost from 1_33_1 to 1_34_1
File size: 7.2 KB
Line 
1<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
2    <meta name="generator" content="HTML Tidy, see www.w3.org">
3    <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
4    <link rel="stylesheet" type="text/css" href="../boost.css">
5
6    <title>Boost.Python - &lt;wrapper.hpp&gt;</title>
7
8    <table border="0" cellpadding="7" cellspacing="0" width="100%" summary=
9    "header">
10      <tr>
11        <td valign="top" width="300">
12          <h3><a href="../../../../index.htm"><img height="86" width="277" alt=
13          "C++ Boost" src="../../../../boost.png" border="0"></a></h3>
14
15        <td valign="top">
16          <h1 align="center"><a href="../index.html">Boost.Python</a></h1>
17
18          <h2 align="center">Header &lt;wrapper.hpp&gt;</h2>
19    </table>
20    <hr>
21
22    <h2>Contents</h2>
23
24    <dl class="page-index">
25      <dt><a href="#introduction">Introduction</a></dt>
26
27      <dt><a href="#classes">Classes</a></dt>
28
29      <dd>
30        <dl class="page-index">
31          <dt><a href="#override-spec">Class template
32          <code>override</code></a></dt>
33
34          <dd>
35            <dl class="page-index">
36              <dt><a href="#override-spec-synopsis">Class
37              <code>override</code> synopsis</a></dt>
38
39              <dt><a href="#override-spec-observers">Class
40              <code>override</code> observer functions</a></dt>
41            </dl>
42          </dd>
43
44          <dt><a href="#wrapper-spec">Class template
45          <code>wrapper</code></a></dt>
46
47          <dd>
48            <dl class="page-index">
49              <dt><a href="#wrapper-spec-synopsis">Class <code>wrapper</code>
50              synopsis</a></dt>
51
52              <dt><a href="#wrapper-spec-observers">Class
53              <code>wrapper</code> observer functions</a></dt>
54            </dl>
55          </dd>
56        </dl>
57      </dd>
58
59      <dt><a href="#examples">Example(s)</a></dt>
60    </dl>
61    <hr>
62
63    <h2><a name="introduction"></a>Introduction</h2>
64
65    <p>To wrap a class <code>T</code> such that its virtual functions can be
66    "overridden in Python"&mdash;so that the corresponding method of a Python
67    derived class will be called when the virtual function is invoked from
68    C++&mdash;you must create a C++ wrapper class derived from ``T`` that
69    overrides those virtual functions so that they call into Python. This
70    header contains classes that can be used to make that job easier.</p>
71
72    <h2><a name="classes"></a>Classes</h2>
73
74    <h3><a name="override-spec"></a>Class <code>override</code></h3>
75
76    <p>Encapsulates a Python override of a C++ virtual function. An
77    <code>override</code> object either holds a callable Python object or
78    <code>None</code>.</p>
79
80    <h4><a name="override-spec-synopsis"></a>Class <code>override</code>
81    synopsis</h4>
82<pre>
83namespace boost
84{
85  class override : object
86  {
87   public:
88      <i>unspecified</i> operator() const;
89      template &lt;class A0&gt;
90      <i>unspecified</i> operator(A0) const;
91      template &lt;class A0, class A1&gt;
92      <i>unspecified</i> operator(A0, A1) const;
93      ...
94      template &lt;class A0, class A1, ...class A<i>n</i>&gt;
95      <i>unspecified</i> operator(A0, A1, ...A<i>n</i>) const;
96  };
97};
98</pre>
99
100    <h4><a name="override-spec-observers"></a>Class <code>override</code>
101    observer functions</h4>
102<pre>
103<i>unspecified</i> operator() const;
104template &lt;class A0&gt;
105<i>unspecified</i> operator(A0) const;
106template &lt;class A0, class A1&gt;
107<i>unspecified</i> operator(A0, A1) const;
108...
109template &lt;class A0, class A1, ...class A<i>n</i>&gt;
110<i>unspecified</i> operator(A0, A1, ...A<i>n</i>) const;
111</pre>
112
113    <dl class="function-semantics">
114      <dt><b>Effects:</b> If <code>*this</code> holds a callable Python
115      object, it is invoked with the specified arguments in the manner
116      specified <a href="callbacks.html">here</a>. Otherwise, throws <code><a
117      href="errors.html#error_already_set-spec">error_already_set</a></code>
118      .</dt>
119
120      <dt><b>Returns:</b> An object of unspecified type that holds the Python
121      result of the invocation and, when converted to a C++ type
122      <code>R</code>, attempts to convert that result object to
123      <code>R</code>. If that conversion fails, throws <code><a href=
124      "errors.html#error_already_set-spec">error_already_set</a></code>
125      .</dt>
126    </dl>
127
128    <h3><a name="wrapper-spec"></a>Class template <code>wrapper</code></h3>
129
130    <p>Deriving your wrapper class from both ``T`` <i>and</i>
131    ``wrapper&lt;T&gt; makes writing that derived class easier.</p>
132
133    <h4><a name="wrapper-spec-synopsis"></a>Class template
134    <code>wrapper</code> synopsis</h4>
135<pre>
136namespace boost
137{
138  class wrapper
139  {
140   protected:
141      override get_override(char const* name) const;
142  };
143};
144</pre>
145
146    <h4><a name="wrapper-spec-observers"></a>Class <code>wrapper</code>
147    observer functions</h4>
148<pre>
149override get_override(char const* name) const;
150</pre>
151
152    <dl class="function-semantics">
153      <dt><b>Requires:</b> <code>name</code> is a <a href=
154      "definitions.html#ntbs">ntbs</a>.</dt>
155
156      <dt><b>Returns:</b> If <code>*this</code> is the C++ base class
157      subobject of a Python derived class instance that overrides the named
158      function, returns an <code>override</code> object that delegates to the
159      Python override. Otherwise, returns an <code>override</code> object
160      that holds <code>None</code>.</dt>
161    </dl>
162
163    <h2><a name="examples"></a>Example</h2>
164<pre>
165#include &lt;boost/python/module.hpp&gt;
166#include &lt;boost/python/class.hpp&gt;
167#include &lt;boost/python/wrapper.hpp&gt;
168#include &lt;boost/python/call.hpp&gt;
169
170using namespace boost::python;
171
172// Class with one pure virtual function
173struct P
174{
175    virtual ~P(){}
176    virtual char const* f() = 0;
177    char const* g() { return "P::g()"; }
178};
179
180struct PCallback : P, wrapper&lt;P&gt;
181{
182    char const* f()
183    {
184#if BOOST_WORKAROUND(BOOST_MSVC, &lt;= 1300) // Workaround for vc6/vc7
185        return call&lt;char const*&gt;(this-&gt;get_override("f").ptr());
186#else
187        return this-&gt;get_override("f")();
188#endif
189    }
190};
191
192// Class with one non-pure virtual function
193struct A
194{
195    virtual ~A(){}
196    virtual char const* f() { return "A::f()"; }
197};
198
199struct ACallback :  A, wrapper&lt;A&gt;
200{
201    char const* f()
202    {
203        if (override f = this-&gt;get_override("f"))
204#if BOOST_WORKAROUND(BOOST_MSVC, &lt;= 1300) // Workaround for vc6/vc7
205            return call&lt;char const*&gt;(f.ptr());
206#else
207            return f();
208#endif
209
210        return A::f();
211    }
212
213    char const* default_f() { return this-&gt;A::f(); }
214};
215
216BOOST_PYTHON_MODULE_INIT(polymorphism)
217{
218    class_&lt;PCallback,boost::noncopyable&gt;("P")
219        .def("f", pure_virtual(&amp;P::f))
220        ;
221
222    class_&lt;ACallback,boost::noncopyable&gt;("A")
223        .def("f", &amp;A::f, &amp;ACallback::default_f)
224        ;
225}
226</pre>
227
228    <p>Revised
229    <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->
230     31 October, 2004
231    <!--webbot bot="Timestamp" endspan i-checksum="39359" -->
232
233
234    <p><i>&copy; Copyright <a href="../../../../people/dave_abrahams.htm">Dave
235    Abrahams</a> 2004</i> Distributed under the Boost Software License,
236  Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at
237  http://www.boost.org/LICENSE_1_0.txt)</p>
238
Note: See TracBrowser for help on using the repository browser.