/tags/Root-branch-php-utl/SWIG/Examples/python/class/index.html
HTML | 218 lines | 170 code | 48 blank | 0 comment | 0 complexity | 36dc5b147011ce0011e710682c94db73 MD5 | raw file
Possible License(s): LGPL-2.1, Cube, GPL-3.0, 0BSD, GPL-2.0
1<html>
2<head>
3<title>SWIG:Examples:python:class</title>
4</head>
5
6<body bgcolor="#ffffff">
7
8
9<tt>SWIG/Examples/python/class/</tt>
10<hr>
11
12<H2>Wrapping a simple C++ class</H2>
13
14<tt>$Header$</tt><br>
15
16<p>
17This example illustrates the most primitive form of C++ class wrapping performed
18by SWIG. In this case, C++ classes are simply transformed into a collection of
19C-style functions that provide access to class members.
20
21<h2>The C++ Code</h2>
22
23Suppose you have some C++ classes described by the following (and admittedly lame)
24header file:
25
26<blockquote>
27<pre>
28/* File : example.h */
29
30class Shape {
31public:
32 Shape() {
33 nshapes++;
34 }
35 virtual ~Shape() {
36 nshapes--;
37 };
38 double x, y;
39 void move(double dx, double dy);
40 virtual double area() = 0;
41 virtual double perimeter() = 0;
42 static int nshapes;
43};
44
45class Circle : public Shape {
46private:
47 double radius;
48public:
49 Circle(double r) : radius(r) { };
50 virtual double area();
51 virtual double perimeter();
52};
53
54class Square : public Shape {
55private:
56 double width;
57public:
58 Square(double w) : width(w) { };
59 virtual double area();
60 virtual double perimeter();
61};
62</pre>
63</blockquote>
64
65<h2>The SWIG interface</h2>
66
67A simple SWIG interface for this can be built by simply grabbing the header file
68like this:
69
70<blockquote>
71<pre>
72/* File : example.i */
73%module example
74
75%{
76#include "example.h"
77%}
78
79/* Let's just grab the original header file here */
80%include "example.h"
81</pre>
82</blockquote>
83
84Note: when creating a C++ extension, you must run SWIG with the <tt>-c++</tt> option like this:
85<blockquote>
86<pre>
87% swig -c++ -python example.i
88</pre>
89</blockquote>
90
91<h2>A sample Python script</h2>
92
93Click <a href="example.py">here</a> to see a script that calls the C++ functions from Python.
94
95<h2>Key points</h2>
96
97<ul>
98<li>To create a new object, you call a constructor like this:
99
100<blockquote>
101<pre>
102c = example.new_Circle(10.0)
103</pre>
104</blockquote>
105
106<p>
107<li>To access member data, a pair of accessor functions are used.
108For example:
109
110<blockquote>
111<pre>
112example.Shape_x_set(c,15) # Set member data
113x = example.Shape_x_get(c) # Get member data
114</pre>
115</blockquote>
116
117Note: when accessing member data, the name of the class in which
118the member data was must be used. In this case, <tt>Shape_x_get()</tt>
119and <tt>Shape_x_set()</tt> are used since 'x' was defined in Shape.
120
121<p>
122<li>To invoke a member function, you simply do this
123
124<blockquote>
125<pre>
126print "The area is ", example.Shape_area(c)
127</pre>
128</blockquote>
129
130<p>
131<li>Type checking knows about the inheritance structure of C++. For example:
132
133<blockquote>
134<pre>
135example.Shape_area(c) # Works (c is a Shape)
136example.Circle_area(c) # Works (c is a Circle)
137example.Square_area(c) # Fails (c is definitely not a Square)
138</pre>
139</blockquote>
140
141<p>
142<li>To invoke a destructor, simply do this
143
144<blockquote>
145<pre>
146example.delete_Shape(c) # Deletes a shape
147</pre>
148</blockquote>
149
150(Note: destructors are currently not inherited. This might change later).
151
152<p>
153<li>Static member variables are wrapped as C global variables. For example:
154
155<blockquote>
156<pre>
157n = example.cvar.Shape_nshapes # Get a static data member
158example.cvar.Shapes_nshapes = 13 # Set a static data member
159</pre>
160</blockquote>
161
162</ul>
163
164<h2>General Comments</h2>
165
166<ul>
167<li>This low-level interface is not the only way to handle C++ code.
168Shadow classes provide a much higher-level interface.
169
170<p>
171<li>SWIG *does* know how to properly perform upcasting of objects in
172an inheritance hierarchy (including multiple inheritance). Therefore
173it is perfectly safe to pass an object of a derived class to any
174function involving a base class.
175
176<p>
177<li>A wide variety of C++ features are not currently supported by SWIG. Here is the
178short and incomplete list:
179
180<p>
181<ul>
182<li>Overloaded methods and functions. SWIG wrappers don't know how to resolve name
183conflicts so you must give an alternative name to any overloaded method name using the
184%name directive like this:
185
186<blockquote>
187<pre>
188void foo(int a);
189%name(foo2) void foo(double a, double b);
190</pre>
191</blockquote>
192
193<p>
194<li>Overloaded operators. Not supported at all. The only workaround for this is
195to write a helper function. For example:
196
197<blockquote>
198<pre>
199%inline %{
200 Vector *vector_add(Vector *a, Vector *b) {
201 ... whatever ...
202 }
203%}
204</pre>
205</blockquote>
206
207<p>
208<li>Namespaces. Not supported at all. Won't be supported until SWIG2.0 (if at all).
209
210<p>
211<li>Dave's snide remark: Like a large bottle of strong Tequilla, it's better to
212use C++ in moderation.
213
214</ul>
215
216<hr>
217</body>
218</html>