PageRenderTime 5ms CodeModel.GetById 1ms app.highlight 2ms RepoModel.GetById 1ms app.codeStats 0ms

/trunk/Examples/perl5/class/index.html

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