Merge branch 'doc-work' into upstream-master
* doc-work: Move the attribute.i docs into Library.html Move %attribute documentation into the manual
This commit is contained in:
William S Fulton
commit
aef4a0f90a
3 changed files with 213 additions and 126 deletions
|
|
@ -44,6 +44,7 @@
|
||||||
<li><a href="#Library_nn16">Utility Libraries</a>
|
<li><a href="#Library_nn16">Utility Libraries</a>
|
||||||
<ul>
|
<ul>
|
||||||
<li><a href="#Library_nn17">exception.i</a>
|
<li><a href="#Library_nn17">exception.i</a>
|
||||||
|
<li><a href="#Library_Attributes">attribute.i</a>
|
||||||
</ul>
|
</ul>
|
||||||
</ul>
|
</ul>
|
||||||
</div>
|
</div>
|
||||||
|
|
@ -2108,5 +2109,212 @@ For example:
|
||||||
</div>
|
</div>
|
||||||
|
|
||||||
|
|
||||||
|
<H3><a name="Library_Attributes">12.5.2 attribute.i</a></H3>
|
||||||
|
|
||||||
|
|
||||||
|
<p>
|
||||||
|
Use <tt>%attribute</tt> when you have a pair of get/set methods to a
|
||||||
|
primitive type like:
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<div class="code">
|
||||||
|
<pre>
|
||||||
|
%include "attribute.i"
|
||||||
|
%attribute(A, int, a, get_a, set_a);
|
||||||
|
|
||||||
|
struct A
|
||||||
|
{
|
||||||
|
int get_a() const;
|
||||||
|
void set_a(int aa);
|
||||||
|
};
|
||||||
|
</pre>
|
||||||
|
</div>
|
||||||
|
|
||||||
|
<p>
|
||||||
|
and you want to provide that variable as an attribute in the target
|
||||||
|
langage. This examples only works for primitive types, not derived
|
||||||
|
types. If you don't provide a 'set' method, a 'read-only' attribute
|
||||||
|
is generated, ie, like:
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<div class="code">
|
||||||
|
<pre>
|
||||||
|
%attribute(A, int, c, get_c);
|
||||||
|
</pre>
|
||||||
|
</div>
|
||||||
|
|
||||||
|
<p>
|
||||||
|
Use <tt>%attributeref</tt> when you have const/non-const reference
|
||||||
|
access methods for primitive types or class/structs, like:
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<div class="code">
|
||||||
|
<pre>
|
||||||
|
%attributeref(A, int, b);
|
||||||
|
|
||||||
|
struct A
|
||||||
|
{
|
||||||
|
const int& b() const;
|
||||||
|
int& b();
|
||||||
|
};
|
||||||
|
|
||||||
|
%attributeref(B, int, c);
|
||||||
|
|
||||||
|
struct B
|
||||||
|
{
|
||||||
|
int& c();
|
||||||
|
};
|
||||||
|
</pre>
|
||||||
|
</div>
|
||||||
|
|
||||||
|
<p>
|
||||||
|
You can also use
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<div class="code">
|
||||||
|
<pre>
|
||||||
|
%attributeref(Class, AttributeType, AttributeName, AccessorMethod)
|
||||||
|
</pre>
|
||||||
|
</div>
|
||||||
|
|
||||||
|
<p>
|
||||||
|
if the internal C++ reference methods have a different name from the
|
||||||
|
attribute you want, so
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<div class="code">
|
||||||
|
<pre>
|
||||||
|
%attributeref(B, int, d, c);
|
||||||
|
</pre>
|
||||||
|
</div>
|
||||||
|
|
||||||
|
<p>
|
||||||
|
is the same as the last example, but instead of the attribute 'c' being
|
||||||
|
called 'c', it is called 'd'.
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<p>
|
||||||
|
Now you can use the attributes like so:
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<div class="code">
|
||||||
|
<pre>
|
||||||
|
x = A()
|
||||||
|
x.a = 3 # calls A::set_a
|
||||||
|
print x.a # calls A::get_a
|
||||||
|
|
||||||
|
x.b = 3 # calls A::b()
|
||||||
|
print x.b # calls A::b() const
|
||||||
|
</pre>
|
||||||
|
</div>
|
||||||
|
|
||||||
|
<p>
|
||||||
|
Use <tt>%attribute2</tt> instead of <tt>%attribute</tt> to indicate
|
||||||
|
that reference-pointer translation is required. You
|
||||||
|
use <tt>%attribute2</tt> instead of <tt>%attribute</tt> in cases like
|
||||||
|
this:
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<div class="code">
|
||||||
|
<pre>
|
||||||
|
%attribute2(MyClass, MyFoo, Foo, GetFoo, SetFoo);
|
||||||
|
%inline %{
|
||||||
|
struct MyFoo {
|
||||||
|
int x;
|
||||||
|
};
|
||||||
|
class MyClass {
|
||||||
|
MyFoo foo;
|
||||||
|
public:
|
||||||
|
MyFoo& GetFoo() { return foo; }
|
||||||
|
void SetFoo(const MyFoo& other) { foo = other; }
|
||||||
|
};
|
||||||
|
%}
|
||||||
|
</pre>
|
||||||
|
</div>
|
||||||
|
|
||||||
|
<p>
|
||||||
|
Here, the data type of the property is a wrapped type (MyFoo) and on
|
||||||
|
the C++ side it is passed by reference. The problem is that the SWIG
|
||||||
|
wrapper will pass around a pointer (MyFoo *) which is not compatible
|
||||||
|
with the reference type of the accessors (MyFoo &). Therefore, if you
|
||||||
|
use <tt>%attribute</tt>, you'll get an error from your C/C++
|
||||||
|
compiler. <tt>%attribute2</tt> translates between a pointer and a
|
||||||
|
reference to eliminate the error. In case you're confused, let's make
|
||||||
|
it simple: just use <tt>%attribute</tt> at first, but if the C/C++
|
||||||
|
compiler gives an error while compiling the wrapper,
|
||||||
|
try <tt>%attribute2</tt> instead.
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<p>
|
||||||
|
NOTE: remember that if the type contains commas, such as
|
||||||
|
'std::pair<int,int>', you need to use the macro like:
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<div class="code">
|
||||||
|
<pre>
|
||||||
|
%attributeref(A, %arg(std::pair<int,int>), pval);
|
||||||
|
</pre>
|
||||||
|
</div>
|
||||||
|
|
||||||
|
<p>
|
||||||
|
where <tt>%arg()</tt> 'normalizes' the type to be understood as a single
|
||||||
|
argument, otherwise the macro will get confused by the comma.
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<p>
|
||||||
|
The <tt>%attributeval</tt> is the same as <tt>%attribute</tt>, but
|
||||||
|
should be used when the type is a class/struct (ie a non-primitive
|
||||||
|
type) and when the get and set methods return/pass by value. The
|
||||||
|
following is very similar to the above example, but note that the
|
||||||
|
access is by value rather than reference.
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<div class="code">
|
||||||
|
<pre>
|
||||||
|
%attributeval(MyClassVal, MyFoo, ReadWriteFoo, GetFoo, SetFoo);
|
||||||
|
%attributeval(MyClassVal, MyFoo, ReadOnlyFoo, GetFoo);
|
||||||
|
%inline %{
|
||||||
|
class MyClassVal {
|
||||||
|
MyFoo foo;
|
||||||
|
public:
|
||||||
|
MyFoo GetFoo() { return foo; }
|
||||||
|
void SetFoo(MyFoo other) { foo = other; }
|
||||||
|
};
|
||||||
|
%}
|
||||||
|
</pre>
|
||||||
|
</div>
|
||||||
|
|
||||||
|
<p>
|
||||||
|
The <tt>%attributestring</tt> is the same as <tt>%attributeval</tt>,
|
||||||
|
but should be used for string class types, which are unusual as they
|
||||||
|
are a class on the C++ side, but normally an immutable/primitive type
|
||||||
|
in the target language. Example usage for std::string:
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<div class="code">
|
||||||
|
<pre>
|
||||||
|
%include <std_string.i>
|
||||||
|
%attributestring(MyStringyClass, std::string, ReadWriteString, GetString, SetString);
|
||||||
|
%attributestring(MyStringyClass, std::string, ReadOnlyString, GetString);
|
||||||
|
%inline %{
|
||||||
|
class MyStringyClass {
|
||||||
|
std::string str;
|
||||||
|
public:
|
||||||
|
MyStringyClass(const std::string &val) : str(val) {}
|
||||||
|
std::string GetString() { return str; }
|
||||||
|
void SetString(std::string other) { str = other; }
|
||||||
|
};
|
||||||
|
%}
|
||||||
|
</pre>
|
||||||
|
</div>
|
||||||
|
|
||||||
|
<p>
|
||||||
|
The <tt>%attributestring</tt> also works for class types that
|
||||||
|
have <tt>%naturalvar</tt> turned on and so is also useful for
|
||||||
|
shared_ptr which has <tt>%naturalvar</tt> turned on in
|
||||||
|
<tt>%shared</tt>_ptr.
|
||||||
|
</p>
|
||||||
|
|
||||||
|
|
||||||
</body>
|
</body>
|
||||||
</html>
|
</html>
|
||||||
|
|
|
||||||
|
|
@ -2773,6 +2773,11 @@ void Foo_w_set(FOO *f, WORD value) {
|
||||||
</pre>
|
</pre>
|
||||||
</div>
|
</div>
|
||||||
|
|
||||||
|
<p>
|
||||||
|
If you have accessor methods that you want to use as attributes in the
|
||||||
|
target language, you can make them appear as data members using
|
||||||
|
<a href="Library.html#Library_Attributes">attributes.i</a>.
|
||||||
|
</p>
|
||||||
|
|
||||||
<p>
|
<p>
|
||||||
<b>Compatibility Note:</b> SWIG-1.3.11 and earlier releases transformed all non-primitive member datatypes
|
<b>Compatibility Note:</b> SWIG-1.3.11 and earlier releases transformed all non-primitive member datatypes
|
||||||
|
|
|
||||||
|
|
@ -7,132 +7,6 @@
|
||||||
/*
|
/*
|
||||||
The following macros convert a pair of set/get methods
|
The following macros convert a pair of set/get methods
|
||||||
into a "native" attribute.
|
into a "native" attribute.
|
||||||
|
|
||||||
Use %attribute when you have a pair of get/set methods to a primitive type
|
|
||||||
like in:
|
|
||||||
|
|
||||||
%attribute(A, int, a, get_a, set_a);
|
|
||||||
|
|
||||||
struct A
|
|
||||||
{
|
|
||||||
int get_a() const;
|
|
||||||
void set_a(int aa);
|
|
||||||
};
|
|
||||||
|
|
||||||
If you don't provide a 'set' method, a 'read-only' attribute
|
|
||||||
is generated, ie, like in:
|
|
||||||
|
|
||||||
%attribute(A, int, c, get_c);
|
|
||||||
|
|
||||||
Use %attributeref when you have const/non-const reference access methods
|
|
||||||
for primitive types or class/structs, like in:
|
|
||||||
|
|
||||||
%attributeref(A, int, b);
|
|
||||||
|
|
||||||
struct A
|
|
||||||
{
|
|
||||||
const int& b() const;
|
|
||||||
int& b();
|
|
||||||
};
|
|
||||||
|
|
||||||
%attributeref(B, int, c);
|
|
||||||
|
|
||||||
struct B
|
|
||||||
{
|
|
||||||
int& c();
|
|
||||||
};
|
|
||||||
|
|
||||||
You can also use
|
|
||||||
|
|
||||||
%attributeref(Class, AttributeType, AttributeName, AccessorMethod)
|
|
||||||
|
|
||||||
if the internal C++ reference methods have a different name from the
|
|
||||||
attribute you want, so
|
|
||||||
|
|
||||||
%attributeref(B, int, d, c);
|
|
||||||
|
|
||||||
is the same as the last example, but instead of the attribute 'c' being
|
|
||||||
called 'c', it is called 'd'.
|
|
||||||
|
|
||||||
Now you can use the attributes like so:
|
|
||||||
|
|
||||||
x = A()
|
|
||||||
x.a = 3 # calls A::set_a
|
|
||||||
print x.a # calls A::get_a
|
|
||||||
|
|
||||||
x.b = 3 # calls A::b()
|
|
||||||
print x.b # calls A::b() const
|
|
||||||
|
|
||||||
Use %attribute2 instead of %attribute to indicate that reference-pointer
|
|
||||||
translation is required. You use %attribute2 instead of %attribute in
|
|
||||||
cases like this:
|
|
||||||
|
|
||||||
%attribute2(MyClass, MyFoo, Foo, GetFoo, SetFoo);
|
|
||||||
%inline %{
|
|
||||||
struct MyFoo {
|
|
||||||
int x;
|
|
||||||
};
|
|
||||||
class MyClass {
|
|
||||||
MyFoo foo;
|
|
||||||
public:
|
|
||||||
MyFoo& GetFoo() { return foo; }
|
|
||||||
void SetFoo(const MyFoo& other) { foo = other; }
|
|
||||||
};
|
|
||||||
%}
|
|
||||||
|
|
||||||
Here, the data type of the property is a wrapped type (MyFoo) and on the
|
|
||||||
C++ side it is passed by reference. The problem is that the SWIG wrapper will
|
|
||||||
pass around a pointer (MyFoo *) which is not compatible with the reference
|
|
||||||
type of the accessors (MyFoo &). Therefore, if you use %attribute, you'll get
|
|
||||||
an error from your C/C++ compiler. %attribute2 translates between a pointer
|
|
||||||
and a reference to eliminate the error. In case you're confused, let's make it
|
|
||||||
simple: just use %attribute at first, but if the C/C++ compiler gives an error
|
|
||||||
while compiling the wrapper, try %attribute2 instead.
|
|
||||||
|
|
||||||
NOTE: remember that if the type contains commas, such as 'std::pair<int,int>',
|
|
||||||
you need to use the macro like:
|
|
||||||
|
|
||||||
%attributeref(A, %arg(std::pair<int,int>), pval);
|
|
||||||
|
|
||||||
where %arg() 'normalizes' the type to be understood as a single
|
|
||||||
argument, otherwise the macro will get confused by the comma.
|
|
||||||
|
|
||||||
The %attributeval is the same as %attribute, but should be used when the type
|
|
||||||
is a class/struct (ie a non-primitive type) and when the get and set methods
|
|
||||||
return/pass by value. The following is very similar to the above example, but
|
|
||||||
note that the access is by value rather than reference.
|
|
||||||
|
|
||||||
%attributeval(MyClassVal, MyFoo, ReadWriteFoo, GetFoo, SetFoo);
|
|
||||||
%attributeval(MyClassVal, MyFoo, ReadOnlyFoo, GetFoo);
|
|
||||||
%inline %{
|
|
||||||
class MyClassVal {
|
|
||||||
MyFoo foo;
|
|
||||||
public:
|
|
||||||
MyFoo GetFoo() { return foo; }
|
|
||||||
void SetFoo(MyFoo other) { foo = other; }
|
|
||||||
};
|
|
||||||
%}
|
|
||||||
|
|
||||||
The %attributestring is the same as %attributeval, but should be used for string
|
|
||||||
class types, which are unusual as they are a class on the C++ side, but normally an
|
|
||||||
immutable/primitive type in the target language. Example usage for std::string:
|
|
||||||
|
|
||||||
%include <std_string.i>
|
|
||||||
%attributestring(MyStringyClass, std::string, ReadWriteString, GetString, SetString);
|
|
||||||
%attributestring(MyStringyClass, std::string, ReadOnlyString, GetString);
|
|
||||||
%inline %{
|
|
||||||
class MyStringyClass {
|
|
||||||
std::string str;
|
|
||||||
public:
|
|
||||||
MyStringyClass(const std::string &val) : str(val) {}
|
|
||||||
std::string GetString() { return str; }
|
|
||||||
void SetString(std::string other) { str = other; }
|
|
||||||
};
|
|
||||||
%}
|
|
||||||
|
|
||||||
The %attributestring also works for class types that have %naturalvar turned
|
|
||||||
on and so is also useful for shared_ptr which has %naturalvar turned on in %shared_ptr.
|
|
||||||
|
|
||||||
*/
|
*/
|
||||||
|
|
||||||
//
|
//
|
||||||
|
|
|
||||||
Loading…
Add table
Add a link
Reference in a new issue