PageRenderTime 50ms CodeModel.GetById 22ms app.highlight 10ms RepoModel.GetById 1ms app.codeStats 0ms

/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>