[generator] Emit events for addListener(Listener,Handler) pattern (dotnet#458)

When [generating events][0], given a Java `Listener` interface and an
"add" method which takes the listener, `generator` will emit an event
for each method on the listener interface, and all method parameters
will become properties on a generated `EventArgs`.  For example,
consider [`android.view.TextureView`][1]:

	// Java
	public class TextureView {
	  public interface SurfaceTextureListener {
	    void onSurfaceTextureAvailable (SurfaceTexture surface, int width, int height);
	    void onSurfaceTextureDestroyed (SurfaceTexture surface);
	    void onSurfaceTextureChanged (SurfaceTexture surface, int width, int height);
	    void onSurfaceTextureUpdated (SurfaceTexture surface);
	  }
	  public void setSurfaceTextureListener(SurfaceTextureListener listener);
	}

`generator` will ["eventify" `TextureView` into][2]:

	// C#
	public partial class TextureView {
	  public interface ISurfaceTextureListener {
	    void OnSurfaceTextureAvailable (SurfaceTexture surface, int width, int height);
	    void OnSurfaceTextureDestroyed (SurfaceTexture surface);
	    void OnSurfaceTextureChanged (SurfaceTexture surface, int width, int height);
	    void OnSurfaceTextureUpdated (SurfaceTexture surface);
	  }
	  
	  public partial class SurfaceTextureAvailableEventArgs {
	    public SurfaceTexture  Surface  {get;}
	    public int             Width    {get;}
	    pbulic int             Height   {get;}
	  }
	  public event EventHandler<SurfaceTextureAvailableEventArgs> SurfaceTextureAvailable;
	  
	  public partial class SurfaceTextureDestroyedEventArgs {
	    public SurfaceTexture  Surface  {get;}
	  }
	  public event EventHandler<SurfaceTextureDestroyedEventArgs> SurfaceTextureDestroyed;
	  
	  public partial class SurfaceTextureChangedEventArgs {
	    public SurfaceTexture  Surface  {get;}
	    public int             Width    {get;}
	    pbulic int             Height   {get;}
	  }
	  public event EventHandler<SurfaceTextureChangedEventArgs> SurfaceTextureChanged;
	  
	  public partial class SurfaceTextureUpdatedEventArgs {
	    public SurfaceTexture  Surface  {get;}
	  }
	  public event EventHandler<SurfaceTextureUpdatedEventArgs> SurfaceTextureUpdated;
	}

A requirement of the "event pattern" was that the "add" method must:

 1. Start with `add` or `set`, e.g. `setSurfaceTextureListener()`.
 2. Have a return type of `void`.
 3. Have a *single* parameter which is an interface containing
    `Listener` as a suffix.

As time has gone on, we've found a slight variation on this pattern
that we believe `generator` should natively support:

 4. *Or*, the "add" method should have *two* parameters, the first
    being an interface type with a `Listener` suffix, and the second
    parameter is of type `Android.OS.Handler`.

When we encounter (4), we can emit a "Event_With_Handler_Helper"
method which calls the "add" method, passing `null` as the `Handler`
parameter.

The addition of (4) allows us to generate events for the
[`android.media.AudioRouting.OnRoutingChangedListener`][3]
interface on the [`android.media.AudioRecord`][4] type, which
provides the method:

	// Java
	class AudioRecord {
	  public void addOnRoutingChangedListener(AudioRouting.OnRoutingChangedListener listener, Handler handler);
	}

This would allow `generator` to emit an `AudioRecord.RoutingChanged`
event, a'la:

	public event EventHandler<Android.Media.AudioRoutingOnRoutingChangedEventArgs> RoutingChanged {
	  add {
	    global::Java.Interop.EventHelper.AddEventHandler<Android.Media.IAudioRoutingOnRoutingChangedListener, Android.Media.IAudioRoutingOnRoutingChangedListenerImplementor>(
	        ref weak_implementor_AddOnRoutingChangedListener,
	        __CreateIAudioRoutingOnRoutingChangedListenerImplementor,
	        AddOnRoutingChangedListener_Event_With_Handler_Helper,
	        __h => __h.Handler += value);
	  }
	  remove {
	    global::Java.Interop.EventHelper.RemoveEventHandler<Android.Media.IAudioRoutingOnRoutingChangedListener, Android.Media.IAudioRoutingOnRoutingChangedListenerImplementor>(
	        ref weak_implementor_AddOnRoutingChangedListener,
	        Android.Media.IAudioRoutingOnRoutingChangedListenerImplementor.__IsEmpty,
	        __v => RemoveOnRoutingChangedListener (__v),
	        __h => __h.Handler -= value);
	  }
	}
	
	void AddOnRoutingChangedListener_Event_With_Handler_Helper (Android.Media.IAudioRoutingOnRoutingChangedListener value)
	{
	  AddOnRoutingChangedListener (value, null);
	}

Additionally, update `generate.sh` script to include API-29.

[0]: https://docs.microsoft.com/en-us/xamarin/android/internals/api-design#events-and-listeners
[1]: https://developer.android.com/reference/android/view/TextureView
[2]: https://docs.microsoft.com/en-us/dotnet/api/android.views.textureview?view=xamarin-android-sdk-9#events
[3]: https://developer.android.com/reference/android/media/AudioRouting.OnRoutingChangedListener.html
[4]: https://developer.android.com/reference/android/media/AudioRecord.html
[5]: https://developer.android.com/reference/android/media/AudioRecord.html#addOnRoutingChangedListener(android.media.AudioRouting.OnRoutingChangedListener,%20android.os.Handler)

Author: gugavaro

build-tools/xamarin-android-docimporter-ng/generate.sh

@@ -3,7 +3,7 @@
 ANDROID_TOOLCHAIN=~/android-toolchain
 
 DROID_DOC_API_LEVELS="10 15 16 17 18 19 20 21 22 23"
-JAVA_STUB_API_LEVELS="24 25 26 27 28 Q"
+JAVA_STUB_API_LEVELS="24 25 26 27 28 29"
 
 
 for n in $JAVA_STUB_API_LEVELS
@@ -15,4 +15,3 @@ for API_LEVEL in $DROID_DOC_API_LEVELS
 do
 	time mono --debug xamarin-android-docimporter-ng/bin/Debug/xamarin-android-docimporter-ng.exe -droiddoc=$ANDROID_TOOLCHAIN/docs/docs-api-$API_LEVEL/ -output-text=api-$API_LEVEL.params.txt -output-xml=api-$API_LEVEL.params.xml -verbose -framework-only
 done
-

tools/generator/Java.Interop.Tools.Generator.CodeGeneration/CodeGenerator.cs

@@ -804,15 +804,15 @@ public void WriteInterfaceInvoker (InterfaceGen @interface, string indent)
 			writer.WriteLine ();
 		}
 
-		public void WriteInterfaceListenerEvent (InterfaceGen @interface, string indent, string name, string nameSpec, string methodName, string full_delegate_name, bool needs_sender, string wrefSuffix, string add, string remove)
+		public void WriteInterfaceListenerEvent (InterfaceGen @interface, string indent, string name, string nameSpec, string methodName, string full_delegate_name, bool needs_sender, string wrefSuffix, string add, string remove, bool hasHandlerArgument = false)
 		{
 			writer.WriteLine ("{0}public event {1} {2} {{", indent, opt.GetOutputName (full_delegate_name), name);
 			writer.WriteLine ("{0}\tadd {{", indent);
 			writer.WriteLine ("{0}\t\tglobal::Java.Interop.EventHelper.AddEventHandler<{1}, {1}Implementor>(",
 					indent, opt.GetOutputName (@interface.FullName));
 			writer.WriteLine ("{0}\t\t\t\tref weak_implementor_{1},", indent, wrefSuffix);
 			writer.WriteLine ("{0}\t\t\t\t__Create{1}Implementor,", indent, @interface.Name);
-			writer.WriteLine ("{0}\t\t\t\t{1},", indent, add);
+			writer.WriteLine ("{0}\t\t\t\t{1},", indent, add + (hasHandlerArgument ? "_Event_With_Handler_Helper" : null));
 			writer.WriteLine ("{0}\t\t\t\t__h => __h.{1}Handler += value);", indent, nameSpec);
 			writer.WriteLine ("{0}\t}}", indent);
 			writer.WriteLine ("{0}\tremove {{", indent);
@@ -825,6 +825,14 @@ public void WriteInterfaceListenerEvent (InterfaceGen @interface, string indent,
 			writer.WriteLine ("{0}\t}}", indent);
 			writer.WriteLine ("{0}}}", indent);
 			writer.WriteLine ();
+
+			if (hasHandlerArgument) {
+				writer.WriteLine ("{0}void {1} ({2} value)", indent, add + "_Event_With_Handler_Helper", opt.GetOutputName (@interface.FullName));
+				writer.WriteLine ("{0}{{", indent);
+				writer.WriteLine ("{0}\t{1} (value, null);", indent, add);
+				writer.WriteLine ("{0}}}", indent);
+				writer.WriteLine ();
+			}
 		}
 
 		public void WriteInterfaceListenerEventsAndProperties (InterfaceGen @interface, string indent, ClassGen target, string name, string connector_fmt, string add, string remove)
@@ -847,7 +855,7 @@ public void WriteInterfaceListenerEventsAndProperties (InterfaceGen @interface,
 			var methods = target.Methods.Concat (target.Properties.Where (p => p.Setter != null).Select (p => p.Setter));
 			var props = new HashSet<string> ();
 			var refs = new HashSet<string> ();
-			var eventMethods = methods.Where (m => m.IsListenerConnector && m.EventName != String.Empty && m.ListenerType == @interface).Distinct ();
+			var eventMethods = methods.Where (m => m.IsListenerConnector && m.EventName != String.Empty && m.ListenerType == @interface).OrderBy (m => m.Parameters.Count).GroupBy (m => m.Name).Select (g => g.First ()).Distinct ();
 			foreach (var method in eventMethods) {
 				string name = method.CalculateEventName (target.ContainsName);
 				if (String.IsNullOrEmpty (name)) {
@@ -914,8 +922,11 @@ public void WriteInterfaceListenerEventOrProperty (InterfaceGen @interface, Meth
 				if (opt.GetSafeIdentifier (name) != name) {
 					Report.Warning (0, Report.WarningInterfaceGen + 5, "event name for {0}.{1} is invalid. `eventName' or `argsType` can be used to assign a valid member name.", @interface.FullName, name);
 					return;
-				} else
-					WriteInterfaceListenerEvent (@interface, indent, name, nameSpec, m.AdjustedName, full_delegate_name, !m.Parameters.HasSender, connector_fmt, add, remove);
+				} else {
+					var mt = target.Methods.Where (method => string.Compare (method.Name, connector_fmt, StringComparison.OrdinalIgnoreCase) == 0 && method.IsListenerConnector).FirstOrDefault ();
+					var hasHandlerArgument = mt != null && mt.IsListenerConnector && mt.Parameters.Count == 2 && mt.Parameters [1].Type == "Android.OS.Handler";
+					WriteInterfaceListenerEvent (@interface, indent, name, nameSpec, m.AdjustedName, full_delegate_name, !m.Parameters.HasSender, connector_fmt, add, remove, hasHandlerArgument);
+				}
 			} else {
 				if (opt.GetSafeIdentifier (name) != name) {
 					Report.Warning (0, Report.WarningInterfaceGen + 6, "event property name for {0}.{1} is invalid. `eventName' or `argsType` can be used to assign a valid member name.", @interface.FullName, name);

tools/generator/Java.Interop.Tools.Generator.ObjectModel/Method.cs

@@ -64,7 +64,8 @@ public string AutoDetectEnumifiedOverrideReturn (AncestorDescendantCache cache)
 
 		public bool CanAdd {
 			get {
-				return Name.Length > 3 && Name.StartsWith ("Add") && Name.EndsWith ("Listener") && Parameters.Count == 1 && IsVoid &&
+				return Name.Length > 3 && Name.StartsWith ("Add") && Name.EndsWith ("Listener") &&  IsVoid &&
+					(Parameters.Count == 1 || (Parameters.Count == 2 && Parameters [1].Type == "Android.OS.Handler")) &&
 					!(Parameters [0].IsArray);
 			}
 		}

tools/generator/Tests/Unit-Tests/CodeGeneratorExpectedResults/Common/WriteInterfaceListenerEventWithHandlerArgument.txt

@@ -0,0 +1,22 @@
+public event MyFullDelegateName MyName {
+	add {
+		global::Java.Interop.EventHelper.AddEventHandler<java.code.IMyInterface, java.code.IMyInterfaceImplementor>(
+				ref weak_implementor_MyWrefSuffix,
+				__CreateIMyInterfaceImplementor,
+				AddMyName_Event_With_Handler_Helper,
+				__h => __h.MyNameSpecHandler += value);
+	}
+	remove {
+		global::Java.Interop.EventHelper.RemoveEventHandler<java.code.IMyInterface, java.code.IMyInterfaceImplementor>(
+				ref weak_implementor_MyWrefSuffix,
+				java.code.IMyInterfaceImplementor.__IsEmpty,
+				RemoveMyName,
+				__h => __h.MyNameSpecHandler -= value);
+	}
+}
+
+void AddMyName_Event_With_Handler_Helper (java.code.IMyInterface value)
+{
+	AddMyName (value, null);
+}
+

tools/generator/Tests/Unit-Tests/CodeGeneratorTests.cs

@@ -528,6 +528,18 @@ public void WriteInterfaceListenerEvent ()
 			Assert.AreEqual (GetExpected (nameof (WriteInterfaceListenerEvent)), writer.ToString ().NormalizeLineEndings ());
 		}
 
+		[Test]
+		public void WriteInterfaceListenerEventWithHandlerArgument ()
+		{
+			var iface = SupportTypeBuilder.CreateInterface ("java.code.IMyInterface", options);
+
+			generator.Context.ContextTypes.Push (iface);
+			generator.WriteInterfaceListenerEvent (iface, string.Empty, "MyName", "MyNameSpec", "MyMethodName", "MyFullDelegateName", true, "MyWrefSuffix", "AddMyName", "RemoveMyName", true);
+			generator.Context.ContextTypes.Pop ();
+
+			Assert.AreEqual (GetExpected (nameof (WriteInterfaceListenerEventWithHandlerArgument)), writer.ToString ().NormalizeLineEndings ());
+		}
+
 		[Test]
 		public void WriteInterfaceListenerProperty ()
 		{

tools/generator/Tests/generator-Tests.csproj

@@ -503,6 +503,9 @@
     <Content Include="Unit-Tests\CodeGeneratorExpectedResults\Common\WriteInterfaceListenerEvent.txt">
       <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
     </Content>
+    <Content Include="Unit-Tests\CodeGeneratorExpectedResults\Common\WriteInterfaceListenerEventWithHandlerArgument.txt">
+      <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
+    </Content>
     <Content Include="Unit-Tests\CodeGeneratorExpectedResults\Common\WriteInterfaceListenerProperty.txt">
       <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
     </Content>