mirror of https://github.com/swig/swig
Move the attribute.i docs into Library.html
Per comments on the merge request, this is the appropriate place for it, and add a reference to it from the structures and unions section so someone looking there will see it. Also remove the changes in Contents.html, since that is regenerated and those changes are just noise in the commit. Signed-off-by: Corey Minyard <cminyard@mvista.com>
This commit is contained in:
Corey Minyard
parent
f77af57bd7
commit
562effb50f
|
|
@ -184,7 +184,6 @@
|
|||
<li><a href="SWIG.html#SWIG_nn32">Typedef and structures</a>
|
||||
<li><a href="SWIG.html#SWIG_nn33">Character strings and structures</a>
|
||||
<li><a href="SWIG.html#SWIG_nn34">Array members</a>
|
||||
<li><a href="SWIG.html#Attributes">Attributes and the %attribute directive</a>
|
||||
<li><a href="SWIG.html#SWIG_structure_data_members">Structure data members</a>
|
||||
<li><a href="SWIG.html#SWIG_nn36">C constructors and destructors</a>
|
||||
<li><a href="SWIG.html#SWIG_adding_member_functions">Adding member functions to C structures</a>
|
||||
|
|
|
|||
|
|
@ -44,6 +44,7 @@
|
|||
<li><a href="#Library_nn16">Utility Libraries</a>
|
||||
<ul>
|
||||
<li><a href="#Library_nn17">exception.i</a>
|
||||
<li><a href="#Library_Attributes">attribute.i</a>
|
||||
</ul>
|
||||
</ul>
|
||||
</div>
|
||||
|
|
@ -2108,5 +2109,212 @@ For example:
|
|||
</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>
|
||||
</html>
|
||||
|
|
|
|||
|
|
@ -59,7 +59,6 @@
|
|||
<li><a href="#SWIG_nn32">Typedef and structures</a>
|
||||
<li><a href="#SWIG_nn33">Character strings and structures</a>
|
||||
<li><a href="#SWIG_nn34">Array members</a>
|
||||
<li><a href="#Attributes">Attributes and the %attribute directive</a>
|
||||
<li><a href="#SWIG_structure_data_members">Structure data members</a>
|
||||
<li><a href="#SWIG_nn36">C constructors and destructors</a>
|
||||
<li><a href="#SWIG_adding_member_functions">Adding member functions to C structures</a>
|
||||
|
|
@ -2636,212 +2635,7 @@ discussed in a later chapter. In many cases, the warning message is
|
|||
harmless.
|
||||
</p>
|
||||
|
||||
<H3><a name="Attributes">5.5.4 Attributes and the %attribute directive</a></H3>
|
||||
|
||||
|
||||
<p>
|
||||
Use <tt>%attribute</tt> when you have a pair of get/set methods to a
|
||||
primitive type like in:
|
||||
</p>
|
||||
|
||||
<div class="code">
|
||||
<pre>
|
||||
%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 in:
|
||||
</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 in:
|
||||
</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>
|
||||
|
||||
<H3><a name="SWIG_structure_data_members">5.5.5 Structure data members</a></H3>
|
||||
<H3><a name="SWIG_structure_data_members">5.5.4 Structure data members</a></H3>
|
||||
|
||||
|
||||
<p>
|
||||
|
|
@ -2939,6 +2733,11 @@ void Foo_w_set(FOO *f, WORD value) {
|
|||
</pre>
|
||||
</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>
|
||||
<b>Compatibility Note:</b> SWIG-1.3.11 and earlier releases transformed all non-primitive member datatypes
|
||||
|
|
@ -2947,7 +2746,7 @@ class, or union. This is unlikely to break existing code. However, if you need
|
|||
datatype is really a struct, simply use a forward struct declaration such as <tt>"struct Foo;"</tt>.
|
||||
</p>
|
||||
|
||||
<H3><a name="SWIG_nn36">5.5.6 C constructors and destructors</a></H3>
|
||||
<H3><a name="SWIG_nn36">5.5.5 C constructors and destructors</a></H3>
|
||||
|
||||
|
||||
<p>
|
||||
|
|
@ -3036,7 +2835,7 @@ the target languages, and it is highly recommended you don't use them.
|
|||
</p>
|
||||
|
||||
|
||||
<H3><a name="SWIG_adding_member_functions">5.5.7 Adding member functions to C structures</a></H3>
|
||||
<H3><a name="SWIG_adding_member_functions">5.5.6 Adding member functions to C structures</a></H3>
|
||||
|
||||
|
||||
<p>
|
||||
|
|
@ -3309,7 +3108,7 @@ be used to extend a structure with more than just methods, a more suitable
|
|||
directive name has been chosen.
|
||||
</p>
|
||||
|
||||
<H3><a name="SWIG_nested_structs">5.5.8 Nested structures</a></H3>
|
||||
<H3><a name="SWIG_nested_structs">5.5.7 Nested structures</a></H3>
|
||||
|
||||
|
||||
<p>
|
||||
|
|
@ -3393,7 +3192,7 @@ Finally, note that nesting is handled differently in C++ mode,
|
|||
see <a href="SWIGPlus.html#SWIGPlus_nested_classes">Nested classes</a>.
|
||||
</p>
|
||||
|
||||
<H3><a name="SWIG_nn39">5.5.9 Other things to note about structure wrapping</a></H3>
|
||||
<H3><a name="SWIG_nn39">5.5.8 Other things to note about structure wrapping</a></H3>
|
||||
|
||||
|
||||
<p>
|
||||
|
|
|
|||
Loading…
Reference in New Issue