From 29c98fa7f839bbeb82be4cc64df41dba62ce9b73 Mon Sep 17 00:00:00 2001
From: "Brant K. Kyser" <brantkyser@gmail.com>
Date: Tue, 22 Oct 2013 11:52:00 -0500
Subject: Update documentation to reflect fully qualifying the use of .NET
 types in the generated code.

---
 Doc/Manual/CSharp.html | 146 +++++++++++++++++++++++++------------------------
 1 file changed, 76 insertions(+), 70 deletions(-)

(limited to 'Doc/Manual')

diff --git a/Doc/Manual/CSharp.html b/Doc/Manual/CSharp.html
index 6df2594c4..b620b3513 100644
--- a/Doc/Manual/CSharp.html
+++ b/Doc/Manual/CSharp.html
@@ -10,6 +10,9 @@
 <div class="sectiontoc">
 <ul>
 <li><a href="#CSharp_introduction">Introduction</a>
+<ul>
+<li><a href="#CSharp_introduction_swig2_compatability">SWIG 2 Compatability</a>
+</ul>
 <li><a href="#CSharp_differences_java">Differences to the Java module</a>
 <li><a href="#CSharp_void_pointers">Void pointers</a>
 <li><a href="#CSharp_arrays">C# Arrays</a>
@@ -69,6 +72,12 @@ The <a href="http://msdn.microsoft.com">Microsoft Developer Network (MSDN)</a> h
 Monodoc, available from the Mono project, has a very useful section titled <a href="http://www.mono-project.com/Interop_with_Native_Libraries">Interop with native libraries</a>.
 </p>
 
+<H3><a name="CSharp_introduction_swig2_compatability"></a>19.1.1 SWIG 2 Compatability</H3>
+
+<p>
+In order to minimize name collisions between names generated based on input to SWIG and names used in the generated code from the .NET framework, SWIG 3 fully qualifies the use of all .NET types. Furthermore, SWIG 3 avoids <tt>using</tt> directives in generated code. This breaks backwards compatability with typemaps, pragmas, etc written for use with SWIG 2 that assume the presence of <tt>using System;</tt> or <tt>using System.Runtime.InteropServices;</tt> directives in the intermediate class imports, module imports, or proxy imports. SWIG 3 supports backwards compatability though the use of the <tt>SWIG2_CSHARP</tt> macro. If <tt>SWIG2_CSHARP</tt> is defined, SWIG 3 generates <tt>using</tt> directives in the intermediate class, module class, and proxy class code similar to those generated by SWIG 2. This can be done without modifying any of the input code by passing the <tt>-DSWIG2_CSHARP</tt> commandline parameter when executing <tt>swig</tt>.
+</p>
+
 <H2><a name="CSharp_differences_java"></a>19.2 Differences to the Java module</H2>
 
 
@@ -262,7 +271,7 @@ An example shows that <tt>char *</tt> could be marshalled in different ways,
 
 <div class="code">
 <pre>
-%typemap(imtype, out="IntPtr") char * "string"
+%typemap(imtype, out="global::System.IntPtr") char * "string"
 char * function(char *);
 </pre>
 </div>
@@ -273,7 +282,7 @@ The output type is thus IntPtr and the input type is string. The resulting inter
 
 <div class="code">
 <pre>
-public static extern IntPtr function(string jarg1);
+public static extern global::System.IntPtr function(string jarg1);
 </pre>
 </div>
 
@@ -294,8 +303,8 @@ For example:
 <div class="code">
 <pre>
 %typemap(imtype,
-         inattributes="[MarshalAs(UnmanagedType.LPStr)]",
-         outattributes="[return: MarshalAs(UnmanagedType.LPStr)]") const char * "String"
+         inattributes="[global::System.Runtime.InteropServices.MarshalAs(UnmanagedType.LPStr)]",
+         outattributes="[return: global::System.Runtime.InteropServices.MarshalAs(UnmanagedType.LPStr)]") const char * "String"
 
 const char * GetMsg() {}
 void SetMsg(const char *msg) {}
@@ -310,12 +319,12 @@ The intermediary class will then have the marshalling as specified by everything
 <pre>
 class examplePINVOKE {
   ...
-  [DllImport("example", EntryPoint="CSharp_GetMsg")]
-  [return: MarshalAs(UnmanagedType.LPStr)]
+  [global::System.Runtime.InteropServices.DllImport("example", EntryPoint="CSharp_GetMsg")]
+  [return: global::System.Runtime.InteropServices.MarshalAs(UnmanagedType.LPStr)]
   public static extern String GetMsg();
 
-  [DllImport("example", EntryPoint="CSharp_SetMsg")]
-  public static extern void SetMsg([MarshalAs(UnmanagedType.LPStr)]String jarg1);
+  [global::System.Runtime.InteropServices.DllImport("example", EntryPoint="CSharp_SetMsg")]
+  public static extern void SetMsg([global::System.Runtime.InteropServices.MarshalAs(UnmanagedType.LPStr)]String jarg1);
 }
 </pre>
 </div>
@@ -368,7 +377,7 @@ will generate a C# proxy class:
 <div class="code">
 <pre>
 [ThreadSafe]
-public class AClass : IDisposable {
+public class AClass : global::System.IDisposable {
   ...
   [ThreadSafe(false)]
   public AClass(double a) ...
@@ -392,9 +401,9 @@ An example for attaching attributes to the enum and enum values is shown below.
 
 <div class="code">
 <pre>
-%typemap(csattributes) Couleur "[System.ComponentModel.Description(\"Colours\")]"
-%csattributes Rouge "[System.ComponentModel.Description(\"Red\")]"
-%csattributes Vert "[System.ComponentModel.Description(\"Green\")]"
+%typemap(csattributes) Couleur "[global::System.ComponentModel.Description(\"Colours\")]"
+%csattributes Rouge "[global::System.ComponentModel.Description(\"Red\")]"
+%csattributes Vert "[global::System.ComponentModel.Description(\"Green\")]"
 %inline %{
   enum Couleur { Rouge, Orange, Vert };
 %}
@@ -407,12 +416,12 @@ which will result in the following C# enum:
 
 <div class="code">
 <pre>
-[System.ComponentModel.Description("Colours")]
+[global::System.ComponentModel.Description("Colours")]
 public enum Couleur {
-  [System.ComponentModel.Description("Red")]
+  [global::System.ComponentModel.Description("Red")]
   Rouge,
   Orange,
-  [System.ComponentModel.Description("Green")]
+  [global::System.ComponentModel.Description("Green")]
   Vert
 }
 </pre>
@@ -618,9 +627,9 @@ marshalling for the arrays:
 
 <div class="code">
 <pre>
-[DllImport("example", EntryPoint="CSharp_myArrayCopy")]
-public static extern void myArrayCopy([In, MarshalAs(UnmanagedType.LPArray)]int[] jarg1, 
-                                      [Out, MarshalAs(UnmanagedType.LPArray)]int[] jarg2,
+[global::System.Runtime.InteropServices.DllImport("example", EntryPoint="CSharp_myArrayCopy")]
+public static extern void myArrayCopy([global::System.Runtime.InteropServices.In, global::System.Runtime.InteropServices.MarshalAs(UnmanagedType.LPArray)]int[] jarg1, 
+                                      [global::System.Runtime.InteropServices.Out, global::System.Runtime.InteropServices.MarshalAs(UnmanagedType.LPArray)]int[] jarg2,
                                        int jarg3);
 </pre>
 </div>
@@ -668,9 +677,9 @@ and intermediary class method
 
 <div class="code">
 <pre>
-  [DllImport("example", EntryPoint="CSharp_myArraySwap")]
-  public static extern void myArraySwap([In, Out, MarshalAs(UnmanagedType.LPArray)]int[] jarg1, 
-                                        [In, Out, MarshalAs(UnmanagedType.LPArray)]int[] jarg2,
+  [global::System.Runtime.InteropServices.DllImport("example", EntryPoint="CSharp_myArraySwap")]
+  public static extern void myArraySwap([global::System.Runtime.InteropServices.In, global::System.Runtime.InteropServices.Out, global::System.Runtime.InteropServices.MarshalAs(UnmanagedType.LPArray)]int[] jarg1, 
+                                        [global::System.Runtime.InteropServices.In, global::System.Runtime.InteropServices.Out, global::System.Runtime.InteropServices.MarshalAs(UnmanagedType.LPArray)]int[] jarg2,
                                          int jarg3);
 </pre>
 </div>
@@ -743,7 +752,7 @@ As a result, we get the following method in the module class:
     fixed ( int *swig_ptrTo_sourceArray = sourceArray ) {
     fixed ( int *swig_ptrTo_targetArray = targetArray ) {
     {
-      examplePINVOKE.myArrayCopy((IntPtr)swig_ptrTo_sourceArray, (IntPtr)swig_ptrTo_targetArray,
+      examplePINVOKE.myArrayCopy((global::System.IntPtr)swig_ptrTo_sourceArray, (global::System.IntPtr)swig_ptrTo_targetArray,
                                  nitems);
     }
     }
@@ -764,8 +773,8 @@ example - the method is expecting an IntPtr as the parameter type.
 
 <div class="code">
 <pre>
-[DllImport("example", EntryPoint="CSharp_myArrayCopy")]
-public static extern void myArrayCopy(IntPtr jarg1, IntPtr jarg2, int jarg3);
+[global::System.Runtime.InteropServices.DllImport("example", EntryPoint="CSharp_myArrayCopy")]
+public static extern void myArrayCopy(global::System.IntPtr jarg1, global::System.IntPtr jarg2, int jarg3);
 </pre>
 </div>
 
@@ -1220,7 +1229,7 @@ the C# code can be generated into the intermediary class using the <tt>imclassco
     static CustomExceptionDelegate customDelegate =
                                    new CustomExceptionDelegate(SetPendingCustomException);
 
-    [DllImport("$dllimport", EntryPoint="CustomExceptionRegisterCallback")]
+    [global::System.Runtime.InteropServices.DllImport("$dllimport", EntryPoint="CustomExceptionRegisterCallback")]
     public static extern
            void CustomExceptionRegisterCallback(CustomExceptionDelegate customCallback);
 
@@ -1264,7 +1273,7 @@ The boiler plate code above must be used in addition to a handcrafted <tt>Custom
 <div class="code">
 <pre>
 // Custom C# Exception
-class CustomApplicationException : System.ApplicationException {
+class CustomApplicationException : global::System.ApplicationException {
   public CustomApplicationException(string message) 
     : base(message) {
   }
@@ -1457,20 +1466,17 @@ Below is the generated C# <tt>Base</tt> director class.
 
 <div class="code">
 <pre>
-using System;
-using System.Runtime.InteropServices;
-
-public class Base : IDisposable {
-  private HandleRef swigCPtr;
+public class Base : global::System.IDisposable {
+  private global::System.Runtime.InteropServices.HandleRef swigCPtr;
   protected bool swigCMemOwn;
 
-  internal Base(IntPtr cPtr, bool cMemoryOwn) {
+  internal Base(global::System.IntPtr cPtr, bool cMemoryOwn) {
     swigCMemOwn = cMemoryOwn;
-    swigCPtr = new HandleRef(this, cPtr);
+    swigCPtr = new global::System.Runtime.InteropServices.HandleRef(this, cPtr);
   }
 
-  internal static HandleRef getCPtr(Base obj) {
-    return (obj == null) ? new HandleRef(null, IntPtr.Zero) : obj.swigCPtr;
+  internal static global::System.Runtime.InteropServices.HandleRef getCPtr(Base obj) {
+    return (obj == null) ? new global::System.Runtime.InteropServices.HandleRef(null, global::System.IntPtr.Zero) : obj.swigCPtr;
   }
 
   ~Base() {
@@ -1479,12 +1485,12 @@ public class Base : IDisposable {
 
   public virtual void Dispose() {
     lock(this) {
-      if(swigCPtr.Handle != IntPtr.Zero &amp;&amp; swigCMemOwn) {
+      if(swigCPtr.Handle != global::System.IntPtr.Zero &amp;&amp; swigCMemOwn) {
         swigCMemOwn = false;
         examplePINVOKE.delete_Base(swigCPtr);
       }
-      swigCPtr = new HandleRef(null, IntPtr.Zero);
-      GC.SuppressFinalize(this);
+      swigCPtr = new global::System.Runtime.InteropServices.HandleRef(null, global::System.IntPtr.Zero);
+      global::System.GC.SuppressFinalize(this);
     }
   }
 
@@ -1511,7 +1517,7 @@ public class Base : IDisposable {
     examplePINVOKE.Base_director_connect(swigCPtr, swigDelegate0, swigDelegate1);
   }
 
-  private bool SwigDerivedClassHasMethod(string methodName, Type[] methodTypes) {
+  private bool SwigDerivedClassHasMethod(string methodName, global::System.global::System.Type[] methodTypes) {
     System.Reflection.MethodInfo methodInfo = this.GetType().GetMethod(methodName, methodTypes);
     bool hasDerivedMethod = methodInfo.DeclaringType.IsSubclassOf(typeof(Base));
     return hasDerivedMethod;
@@ -1521,18 +1527,18 @@ public class Base : IDisposable {
     return UIntMethod(x);
   }
 
-  private void SwigDirectorBaseBoolMethod(IntPtr b, bool flag) {
+  private void SwigDirectorBaseBoolMethod(global::System.IntPtr b, bool flag) {
     BaseBoolMethod(new Base(b, false), flag);
   }
 
   internal delegate uint SwigDelegateBase_0(uint x);
-  internal delegate void SwigDelegateBase_1(IntPtr b, bool flag);
+  internal delegate void SwigDelegateBase_1(global::System.IntPtr b, bool flag);
 
   private SwigDelegateBase_0 swigDelegate0;
   private SwigDelegateBase_1 swigDelegate1;
 
-  private static Type[] swigMethodTypes0 = new Type[] { typeof(uint) };
-  private static Type[] swigMethodTypes1 = new Type[] { typeof(Base), typeof(bool) };
+  private static global::System.Type[] swigMethodTypes0 = new global::System.Type[] { typeof(uint) };
+  private static global::System.Type[] swigMethodTypes1 = new global::System.Type[] { typeof(Base), typeof(bool) };
 }
 </pre>
 </div>
@@ -1755,9 +1761,9 @@ and the following usage from C# after running the code through SWIG:
       Wheel wheel = new Bike(10).getWheel();
       Console.WriteLine("wheel size: " + wheel.size);
       // Simulate a garbage collection
-      System.GC.Collect();
-      System.GC.WaitForPendingFinalizers();
-      Console.WriteLine("wheel size: " + wheel.size);
+      global::System.GC.Collect();
+      global::System.GC.WaitForPendingFinalizers();
+      global::System.Console.WriteLine("wheel size: " + wheel.size);
 </pre>
 </div>
 
@@ -1795,9 +1801,9 @@ is called using the following typemaps.
 // of dangling C++ pointer. Intended for methods that return pointers or
 // references to a member variable.
 %typemap(csout, excode=SWIGEXCODE) Wheel&amp; getWheel {
-    IntPtr cPtr = $imcall;$excode
+    global::System.IntPtr cPtr = $imcall;$excode
     $csclassname ret = null;
-    if (cPtr != IntPtr.Zero) {
+    if (cPtr != global::System.IntPtr.Zero) {
       ret = new $csclassname(cPtr, $owner);
       ret.addReference(this);
     }
@@ -1813,7 +1819,7 @@ The code in the second typemap constitutes the bulk of the code in the generated
 
 <div class="code">
 <pre>
-public class Wheel : IDisposable {
+public class Wheel : global::System.IDisposable {
   ...
   // Ensure that the GC doesn't collect any Bike instance set from C#
   private Bike bikeReference;
@@ -1822,12 +1828,12 @@ public class Wheel : IDisposable {
   }
 }
 
-public class Bike : IDisposable {
+public class Bike : global::System.IDisposable {
   ...
   public Wheel getWheel() {
-    IntPtr cPtr = examplePINVOKE.Bike_getWheel(swigCPtr);
+    global::System.IntPtr cPtr = examplePINVOKE.Bike_getWheel(swigCPtr);
     Wheel ret = null;
-    if (cPtr != IntPtr.Zero) {
+    if (cPtr != global::System.IntPtr.Zero) {
       ret = new Wheel(cPtr, false);
       ret.addReference(this);
     }
@@ -1904,9 +1910,9 @@ In order to understand why, consider a garbage collection occuring...
       container.setElement(element);
       Console.WriteLine("element.value: " + container.getElement().value);
       // Simulate a garbage collection
-      System.GC.Collect();
-      System.GC.WaitForPendingFinalizers();
-      Console.WriteLine("element.value: " + container.getElement().value);
+      global::System.GC.Collect();
+      global::System.GC.WaitForPendingFinalizers();
+      global::System.Console.WriteLine("element.value: " + container.getElement().value);
 </pre>
 </div>
 
@@ -1918,14 +1924,14 @@ One solution is to add in the appropriate references in the C# layer...
 
 <div class="code">
 <pre>
-public class Container : IDisposable {
+public class Container : global::System.IDisposable {
 
   ...
 
   // Ensure that the GC doesn't collect any Element set from C#
   // as the underlying C++ class stores a shallow copy
   private Element elementReference;
-  private HandleRef getCPtrAndAddReference(Element element) {
+  private global::System.Runtime.InteropServices.HandleRef getCPtrAndAddReference(Element element) {
     elementReference = element;
     return Element.getCPtr(element);
   }
@@ -1951,7 +1957,7 @@ The 'cscode' typemap simply adds in the specified code into the C# proxy class.
   // Ensure that the GC doesn't collect any Element set from C#
   // as the underlying C++ class stores a shallow copy
   private Element elementReference;
-  private HandleRef getCPtrAndAddReference(Element element) {
+  private global::System.Runtime.InteropServices.HandleRef getCPtrAndAddReference(Element element) {
     elementReference = element;
     return Element.getCPtr(element);
   }
@@ -2000,7 +2006,7 @@ First let's look at the code that is generated by default, where the C# proxy cl
 
 <div class="code">
 <pre>
-public class Action : IDisposable {
+public class Action : global::System.IDisposable {
   ...
   public Action(CDate dateIn, CDate dateOut) 
       : this(examplePINVOKE.new_Action(CDate.getCPtr(dateIn), CDate.getCPtr(dateOut)), true) {
@@ -2081,7 +2087,7 @@ The resulting generated proxy code in the <tt>Action</tt> class follows:
 
 <div class="code">
 <pre>
-public class Action : IDisposable {
+public class Action : global::System.IDisposable {
   ...
   public int doSomething(System.DateTime dateIn, out System.DateTime dateOut) {
     CDate tempdateIn = new CDate(dateIn.Year, dateIn.Month, dateIn.Day);
@@ -2099,7 +2105,7 @@ public class Action : IDisposable {
     }
   }
 
-  static private IntPtr SwigConstructAction(System.DateTime dateIn, out System.DateTime dateOut) {
+  static private global::System.IntPtr SwigConstructAction(System.DateTime dateIn, out System.DateTime dateOut) {
     CDate tempdateIn = new CDate(dateIn.Year, dateIn.Month, dateIn.Day);
     CDate tempdateOut = new CDate();
     try {
@@ -2299,8 +2305,8 @@ The typemap type required is thus <tt>CDate *</tt>. Given that the previous sect
 %typemap(csvarout, excode=SWIGEXCODE2) CDate * %{
     /* csvarout typemap code */
     get {
-      IntPtr cPtr = $imcall;
-      CDate tempDate = (cPtr == IntPtr.Zero) ? null : new CDate(cPtr, $owner);$excode
+      global::System.IntPtr cPtr = $imcall;
+      CDate tempDate = (cPtr == global::System.IntPtr.Zero) ? null : new CDate(cPtr, $owner);$excode
       return new System.DateTime(tempDate.getYear(), tempDate.getMonth(), tempDate.getDay(),
                                  0, 0, 0);
     } %}
@@ -2322,8 +2328,8 @@ public class example {
     } 
     /* csvarout typemap code */
     get {
-      IntPtr cPtr = examplePINVOKE.ImportantDate_get();
-      CDate tempDate = (cPtr == IntPtr.Zero) ? null : new CDate(cPtr, false);
+      global::System.IntPtr cPtr = examplePINVOKE.ImportantDate_get();
+      CDate tempDate = (cPtr == global::System.IntPtr.Zero) ? null : new CDate(cPtr, false);
       return new System.DateTime(tempDate.getYear(), tempDate.getMonth(), tempDate.getDay(),
                                  0, 0, 0);
     } 
@@ -2389,7 +2395,7 @@ The generated proxy class code will then contain the following wrapper for calli
 
 <div class="code"><pre>
 ...
-  private void SwigDirectorsomeCallback(IntPtr date) {
+  private void SwigDirectorsomeCallback(global::System.IntPtr date) {
     System.DateTime tempdate = new System.DateTime();
     try {
       someCallback(out tempdate);
@@ -2432,7 +2438,7 @@ The default C# proxy class generated is:
 
 <div class="code">
 <pre>
-public class ExtendMe : IDisposable {
+public class ExtendMe : global::System.IDisposable {
   ...
   public int Part1() {
     ...
@@ -2468,7 +2474,7 @@ The C# proxy class becomes a partial class:
 
 <div class="code">
 <pre>
-public partial class ExtendMe : IDisposable {
+public partial class ExtendMe : global::System.IDisposable {
   ...
   public int Part1() {
     ...
@@ -2483,7 +2489,7 @@ You can then of course declare another part of the partial class elsewhere, for
 
 <div class="code">
 <pre>
-public partial class ExtendMe : IDisposable {
+public partial class ExtendMe : global::System.IDisposable {
   public int Part2() {
     return 2;
   }
@@ -2535,7 +2541,7 @@ The generated C# proxy class will instead be:
 
 <div class="code">
 <pre>
-public class ExtendMe : IDisposable {
+public class ExtendMe : global::System.IDisposable {
   ...
   public int Part3() {
     return 3;
-- 
cgit v1.2.3