/tags/rel-1-3-24/SWIG/Examples/tcl/variables/index.html

# · HTML · 78 lines · 63 code · 15 blank · 0 comment · 0 complexity · 018de4f4552a9976faace3a80d6a6036 MD5 · raw file 

    

  1. <html>
    2. 

  2. <head>
    3. 

  3. <title>SWIG:Examples:tcl:variables</title>
    4. 

  4. </head>
    5. 

  5. 

  6. <body bgcolor="#ffffff">
    7. 

  7. 

  8. <tt>SWIG/Examples/tcl/variables/</tt>
    9. 

  9. <hr>
    10. 

  10. 

  11. <H2>Wrapping C Global Variables</H2>
    12. 

  12. 

  13. <tt>$Header$</tt><br>
    14. 

  14. 

  15. <p>
    16. 

  16. When a C global variable appears in an interface file, SWIG tries to wrap it using a technique
    17. 

  17. known as "variable linking."  The idea is pretty simple---we try to create a Tcl
    18. 

  18. variable that works exactly like you would expect in a Tcl script, but which magically 
    19. 

  19. retrieves or updates the value of the underlying C variable.  
    20. 

  20. Click <a href="example.i">here</a> to see a SWIG interface with some variable declarations in it.
    21. 

  21. 

  22. <h2>Manipulating Variables from Tcl</h2>
    23. 

  23. 

  24. Click <a href="runme.tcl">here</a> to see a script that updates and prints out the values of
    25. 

  25. the variables defined in the above file.  Notice how the C global variables work just
    26. 

  26. like normal Tcl variables.
    27. 

  27. 

  28. <h2>Key points</h2>
    29. 

  29. 

  30. <ul>
    31. 

  31. <li>The <tt>set</tt> statement changes the value of the corresponding C global variable.
    32. 

  32. <li>Whenever you access the value of a variable such as <tt>$ivar</tt>, the value
    33. 

  33. of the C global variable is read. 
    34. 

  34. <li>If a C program changes a global variable independently of Tcl, this change is
    35. 

  35. automatically reflected in the Tcl variable (i.e., reads will always return the
    36. 

  36. most up to date value of the variable).
    37. 

  37. <li>When a global variable has the type "<tt>char *</tt>", SWIG manages it as a character
    38. 

  38. string.   However, whenever the value of such a variable is set from Tcl, the old
    39. 

  39. value is destroyed using <tt>free()</tt> or <tt>delete</tt> (the choice of which depends
    40. 

  40. on whether or not SWIG was run with the -c++ option).
    41. 

  41. <li><tt>signed char</tt> and <tt>unsigned char</tt> are handled as small 8-bit integers.
    42. 

  42. <li>String array variables such as '<tt>char name[256]</tt>' are managed as Tcl strings, but
    43. 

  43. when setting the value, the result is truncated to the maximum length of the array.  Furthermore, the string is assumed to be null-terminated.
    44. 

  44. <li>When structures and classes are used as global variables, they are mapped into pointers.
    45. 

  45. 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.
    46. 

  46. </ul>
    47. 

  47. 

  48. <h2>Creating read-only variables</h2>
    49. 

  49. 

  50. The <tt>%immutable</tt> and <tt>%mutable</tt> directives can be used to
    51. 

  51. specify a collection of read-only variables.  For example:
    52. 

  52. 

  53. <blockquote>
    54. 

  54. <pre>
    55. 

  55. %immutable;
    56. 

  56. int    status;
    57. 

  57. double blah;
    58. 

  58. ...
    59. 

  59. %mutable;
    60. 

  60. </pre>
    61. 

  61. </blockquote>
    62. 

  62. 

  63. The <tt>%immutable</tt> directive remains in effect until it is explicitly disabled
    64. 

  64. using the <tt>%mutable</tt> directive.
    65. 

  65. 

  66. <h2>Comments</h2>
    67. 

  67. <ul>
    68. 

  68. <li>Management of global variables is one of the most problematic aspects 
    69. 

  69. of C/C++ wrapping because the scripting interface and resulting memory management
    70. 

  70. is much trickier than simply creating a wrapper function.
    71. 

  71. <p>
    72. 

  72. <li>You may be better off hiding global variables behind a function based
    73. 

  73. interface.
    74. 

  74. </ul>
    75. 

  75. 

  76. </body>
    77. 

  77. </html>
    78. 

  78. <hr>
    79.