trunk/Examples/tcl/variables/index.html - third_party/swig - Git at Google

 <html>
 <head>
 <title>SWIG:Examples:tcl:variables</title>
 </head>

 <body bgcolor="#ffffff">

 <tt>SWIG/Examples/tcl/variables/</tt>
 <hr>

 <H2>Wrapping C Global Variables</H2>

 <p>
 When a C global variable appears in an interface file, SWIG tries to wrap it using a technique
 known as "variable linking."  The idea is pretty simple---we try to create a Tcl
 variable that works exactly like you would expect in a Tcl script, but which magically
 retrieves or updates the value of the underlying C variable.
 Click <a href="example.i">here</a> to see a SWIG interface with some variable declarations in it.

 <h2>Manipulating Variables from Tcl</h2>

 Click <a href="runme.tcl">here</a> to see a script that updates and prints out the values of
 the variables defined in the above file.  Notice how the C global variables work just
 like normal Tcl variables.

 <h2>Key points</h2>

 <ul>
 <li>The <tt>set</tt> statement changes the value of the corresponding C global variable.
 <li>Whenever you access the value of a variable such as <tt>$ivar</tt>, the value
 of the C global variable is read.
 <li>If a C program changes a global variable independently of Tcl, this change is
 automatically reflected in the Tcl variable (i.e., reads will always return the
 most up to date value of the variable).
 <li>When a global variable has the type "<tt>char *</tt>", SWIG manages it as a character
 string.   However, whenever the value of such a variable is set from Tcl, the old
 value is destroyed using <tt>free()</tt> or <tt>delete</tt> (the choice of which depends
 on whether or not SWIG was run with the -c++ option).
 <li><tt>signed char</tt> and <tt>unsigned char</tt> are handled as small 8-bit integers.
 <li>String array variables such as '<tt>char name[256]</tt>' are managed as Tcl strings, but
 when setting the value, the result is truncated to the maximum length of the array.  Furthermore, the string is assumed to be null-terminated.
 <li>When structures and classes are used as global variables, they are mapped into pointers.
 Getting the "value" returns a pointer to the global variable.  Setting the value of a structure results in a memory copy from a pointer to the global.
 </ul>

 <h2>Creating read-only variables</h2>

 The <tt>%immutable</tt> and <tt>%mutable</tt> directives can be used to
 specify a collection of read-only variables.  For example:

 <blockquote>
 <pre>
 %immutable;
 int    status;
 double blah;
 ...
 %mutable;
 </pre>
 </blockquote>

 The <tt>%immutable</tt> directive remains in effect until it is explicitly disabled
 using the <tt>%mutable</tt> directive.

 <h2>Comments</h2>
 <ul>
 <li>Management of global variables is one of the most problematic aspects
 of C/C++ wrapping because the scripting interface and resulting memory management
 is much trickier than simply creating a wrapper function.
 <p>
 <li>You may be better off hiding global variables behind a function based
 interface.
 </ul>

 </body>
 </html>
 <hr>
	<html>
	<head>
	<title>SWIG:Examples:tcl:variables</title>
	</head>

	<body bgcolor="#ffffff">

	<tt>SWIG/Examples/tcl/variables/</tt>
	<hr>

	<H2>Wrapping C Global Variables</H2>

	<p>
	When a C global variable appears in an interface file, SWIG tries to wrap it using a technique
	known as "variable linking." The idea is pretty simple---we try to create a Tcl
	variable that works exactly like you would expect in a Tcl script, but which magically
	retrieves or updates the value of the underlying C variable.
	Click <a href="example.i">here</a> to see a SWIG interface with some variable declarations in it.

	<h2>Manipulating Variables from Tcl</h2>

	Click <a href="runme.tcl">here</a> to see a script that updates and prints out the values of
	the variables defined in the above file. Notice how the C global variables work just
	like normal Tcl variables.

	<h2>Key points</h2>

	<ul>
	<li>The <tt>set</tt> statement changes the value of the corresponding C global variable.
	<li>Whenever you access the value of a variable such as <tt>$ivar</tt>, the value
	of the C global variable is read.
	<li>If a C program changes a global variable independently of Tcl, this change is
	automatically reflected in the Tcl variable (i.e., reads will always return the
	most up to date value of the variable).
	<li>When a global variable has the type "<tt>char *</tt>", SWIG manages it as a character
	string. However, whenever the value of such a variable is set from Tcl, the old
	value is destroyed using <tt>free()</tt> or <tt>delete</tt> (the choice of which depends
	on whether or not SWIG was run with the -c++ option).
	<li><tt>signed char</tt> and <tt>unsigned char</tt> are handled as small 8-bit integers.
	<li>String array variables such as '<tt>char name[256]</tt>' are managed as Tcl strings, but
	when setting the value, the result is truncated to the maximum length of the array. Furthermore, the string is assumed to be null-terminated.
	<li>When structures and classes are used as global variables, they are mapped into pointers.
	Getting the "value" returns a pointer to the global variable. Setting the value of a structure results in a memory copy from a pointer to the global.
	</ul>

	<h2>Creating read-only variables</h2>

	The <tt>%immutable</tt> and <tt>%mutable</tt> directives can be used to
	specify a collection of read-only variables. For example:

	<blockquote>
	<pre>
	%immutable;
	int status;
	double blah;
	...
	%mutable;
	</pre>
	</blockquote>

	The <tt>%immutable</tt> directive remains in effect until it is explicitly disabled
	using the <tt>%mutable</tt> directive.

	<h2>Comments</h2>
	<ul>
	<li>Management of global variables is one of the most problematic aspects
	of C/C++ wrapping because the scripting interface and resulting memory management
	is much trickier than simply creating a wrapper function.
	<p>
	<li>You may be better off hiding global variables behind a function based
	interface.
	</ul>

	</body>
	</html>
	<hr>