← Back to branch summary

~ubuntu-branches/ubuntu/maverick/swig1.3/maverick

« back to all changes in this revision

Viewing changes to Examples/python/class/index.html

  • Committer: Bazaar Package Importer
  • Author(s): Torsten Landschoff
  • Date: 2002-03-29 01:56:07 UTC
  • Revision ID: james.westby@ubuntu.com-20020329015607-c0wt03xu8oy9ioj7
Tags: upstream-1.3.11
Import upstream version 1.3.11

Show diffs side-by-side

added added

removed removed

Lines of Context:
Examples/python/class/index.html
 
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: /cvs/projects/SWIG/Examples/python/class/index.html,v 1.1.4.1 2001/08/30 04:12:40 beazley Exp $</tt><br>
 
15
 
 
16
<p>
 
17
This example illustrates the most primitive form of C++ class wrapping performed
 
18
by SWIG.  In this case, C++ classes are simply transformed into a collection of
 
19
C-style functions that provide access to class members.
 
20
 
 
21
<h2>The C++ Code</h2>
 
22
 
 
23
Suppose you have some C++ classes described by the following (and admittedly lame) 
 
24
header file:
 
25
 
 
26
<blockquote>
 
27
<pre>
 
28
/* File : example.h */
 
29
 
 
30
class Shape {
 
31
public:
 
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
 
 
45
class Circle : public Shape {
 
46
private:
 
47
  double radius;
 
48
public:
 
49
  Circle(double r) : radius(r) { };
 
50
  virtual double area();
 
51
  virtual double perimeter();
 
52
};
 
53
 
 
54
class Square : public Shape {
 
55
private:
 
56
  double width;
 
57
public:
 
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
 
 
67
A simple SWIG interface for this can be built by simply grabbing the header file
 
68
like 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
 
 
84
Note: 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
 
 
93
Click <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>
 
102
c = 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.
 
108
For example:
 
109
 
 
110
<blockquote>
 
111
<pre>
 
112
example.Shape_x_set(c,15)    # Set member data
 
113
x = example.Shape_x_get(c)    # Get member data
 
114
</pre>
 
115
</blockquote>
 
116
 
 
117
Note: when accessing member data, the name of the class in which
 
118
the member data was must be used.  In this case, <tt>Shape_x_get()</tt>
 
119
and <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>
 
126
print "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>
 
135
example.Shape_area(c)       # Works (c is a Shape)
 
136
example.Circle_area(c)      # Works (c is a Circle)
 
137
example.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>
 
146
example.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>
 
157
n = example.cvar.Shape_nshapes     # Get a static data member
 
158
example.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.
 
168
Shadow classes provide a much higher-level interface.
 
169
 
 
170
<p>
 
171
<li>SWIG *does* know how to properly perform upcasting of objects in
 
172
an inheritance hierarchy (including multiple inheritance).  Therefore
 
173
it is perfectly safe to pass an object of a derived class to any
 
174
function involving a base class.
 
175
 
 
176
<p>
 
177
<li>A wide variety of C++ features are not currently supported by SWIG.  Here is the
 
178
short and incomplete list:
 
179
 
 
180
<p>
 
181
<ul>
 
182
<li>Overloaded methods and functions.  SWIG wrappers don't know how to resolve name
 
183
conflicts so you must give an alternative name to any overloaded method name using the
 
184
%name directive like this:
 
185
 
 
186
<blockquote>
 
187
<pre>
 
188
void 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
 
195
to 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
 
212
use C++ in moderation.
 
213
 
 
214
</ul>
 
215
 
 
216
<hr>
 
217
</body>
 
218
</html>