Code-behind fragment and widget access fixes

Fragment handling code partially taken from dotnet#1302

Fragments are treated as normal widget, with the difference that they have to be
found using `FragmentManager.FindFragmentById` instead of the usual
`Activity.FindViewById` method.

Each generated class also gets a property named `Widget` which returns the
actual Android widget as found in the layout file. This allows us to keep
hierarchical nature of the XML code (thus handling nested widgets with duplicate
ids gracefully) while being able to access the parent widget itself.

The commit introduces a new attribute called `tools:managedType` which is used
to specify the element associated property's type. We cannot use `tools:class`
for this purpose since the layout root element already uses it to specify the
name of the generated code-behind class and if the element had `android:id` on
it, we would end up using the activity's type for the root element's property in
the generated code, instead of its actual type.

Author: grendello

Documentation/guides/LayoutCodeBehind.md

@@ -11,28 +11,45 @@ dateupdated: 2018-01-29
 Xamarin.Android supports the auto generation of "Code Behind" classes. These classes
 can reduce the amount code a developer writes. You can end up replacing code like
 
-    SetContentView (Resource.Layout.Main);
-    var button = FindViewById<Button> (Resource.Id.myButton);
-        button.Click += delegate {
-    };
+```csharp
+SetContentView (Resource.Layout.Main);
+var button = FindViewById<Button> (Resource.Id.myButton);
+   button.Click += delegate {
+};
+```
 
 with
 
-    InitializeContentView ();
-    myButton.Click += delegate {
-    };
+```csharp
+InitializeContentView ();
+myButton.Click += delegate {
+};
+```
 
+or, with nested layouts:
+
+```csharp
+InitializeContentView ();
+myParentLayout.myButton.Widget.Click += delegate {
+};
+```
 
 <a name="" class="injected"/></a>
 
 # Preparing to use Code Behind
 
 In order to make use of this new feature there are a few changes which are required. 
-An axml/xml file that you want to associate with an activity needs to be modified to 
-include a few extra xml attributes on the root layout element.
+An ``axml/xml`` file that you want to associate with an activity needs to be modified to 
+include a few extra xml attributes on the root layout element. 
+
+Additionally, **only*** elements which have the `android:id` attribute will be accessible via 
+the generated code.
+
 
-    xmlns:tools="http://schemas.xamarin.com/android/tools"
-    tools:class="$(Namespace).$(ClassName)"
+```xml
+xmlns:tools="http://schemas.xamarin.com/android/tools"
+tools:class="$(Namespace).$(ClassName)"
+```
 
 The `class` attribute defines the Namespace and ClassName of the code which will be
 generated. For example if you have a layout for your `MainActivity` you would set
@@ -42,35 +59,46 @@ qualified name, not just the class name on its own.
 The next thing we need to do is to make the `MainActivity` a `partial` class. This
 allows the genereted code to extend the current class which you have written.
 So 
-    public class MainActivity : Activity {
-    }
+
+```csharp
+public class MainActivity : Activity {
+}
+```
 
 will become 
 
-    public partial class MainActivity : Activity {
-    }
+```csharp
+public partial class MainActivity : Activity {
+}
+```
 
 You then need to make sure you initialize the layout properties by calling
 `InitializeContentView ()` in the `OnCreate()` method of your activity.
 
-    protected override void OnCreate (Bundle bundle)
-    {
-        base.OnCreate (bundle);
-        InitializeContentView ();
-    }
+```csharp
+protected override void OnCreate (Bundle bundle)
+{
+   base.OnCreate (bundle);
+   InitializeContentView ();
+}
+```
 
 For those of you familiar with System.Windows.Forms this is akin
 to `InitializeComponent`. Once this has been done you can now access
 your layout items via the properties.
 
-    myButton.Click += delegate {
-    };
+```csharp
+myButton.Click += delegate {
+};
+```
 
 There is a partial method available which can be implemented to handle
 situations where the View is not found. The method is
 
-    void OnLayoutViewNotFound<T> (int resourceId, ref T type)
-        where T : global::Android.Views.View;
+```csharp
+void OnLayoutViewNotFound<T> (int resourceId, ref T type)
+   where T : global::Android.Views.View;
+```
 
 If `FindViewById` returns `null` then the `OnLayoutViewNotFound` method
 will be called (if it is implemented). This is done BEFORE we throw the
@@ -79,6 +107,96 @@ situation in a manner which fits the app they are writing. For example
 you might want to switch to a backup view, or just log some additional
 diagnostic information.
 
+Another partial method exists to handle fragments:
+
+```csharp
+void OnLayoutFragmentNotFound<T> (int resourceId, ref T type)
+  where T : global::Android.App.Fragment;
+```
+
+It works in exactly the same way as `OnLayoutViewNotFound` above, just for fragments.
+
+## Generated code structure
+
+The generated code-behind is laid out in a hierarchical fashion, reflecting the parent-child
+relationship found in the layout file. The way it is done is that each element which has any
+child elements **with** the `android:id` attribute (that is, ones which will also have code
+generated for them) will have a nested class generated for it which will have a property for
+each child element as well as the `Widget` property which refers to this element's actual 
+Android widget/view. Each element which does **not** have any child elements with the 
+`android:id` attribute, however, will become a *leaf node* and will have an associated property
+in its parent widget's class directly typed to the actual Android type (e.g. `TextView`) instead
+of the class described before. For instance, given this layout:
+
+```xml
+<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android" xmlns:tools="http://schemas.xamarin.com/android/tools"
+   tools:class="MyActivity">
+   <ScrollView android:id="@+id/myScrollView">
+      <TextView android:id="@+id/myTextView"/>
+   </ScrollView>
+</LinearLayout>
+```
+
+The code-behind will have this rough structure (class names are different to keep the documentation clear):
+
+```csharp
+myScrollView_Class myScrollView { 
+   get { return new myScrollView_Class (this); }
+}
+
+class myScrollView_Class 
+{
+   public ScrollView Widget { 
+      get { /* ... */ }
+   }
+   
+   public TextView myTextView {
+      get { /* ... */ }
+    }
+	
+   public myScrollView_Class (MyActivity parent) {}
+}
+```
+
+So in order to access the widgets you'd use code similar to:
+
+```csharp
+InitializeContentView ();
+myScrollView.Widget.Fling (100);
+myScrollView.myTextView.AutoSizeMaxTextSize = 40;
+```
+
+## Managed types
+
+By default each element for which we generate code-behind has its managed type set to
+its local name, for instance 
+
+```xml
+<TextView android:id=""@+id/textView" />
+```
+
+Will generate a property named `textView` of type `TextView`. It works fine in most cases
+but sometimes you might find code which either refers to a custom widget using the package
+name or a fragment which uses the case-insensitive `android:name` attribute syntax, for
+instance:
+
+```xml
+<fragment
+   android:name="commonsamplelibrary.LogFragment"
+   android:id="@+id/log_fragment" />
+```
+
+In this case the generated property would have the managed type `commonsamplelibrary.LogFragment`, 
+however the actual managed type fully qualified name is `CommonSampleLibrary.LogFragment` and thus
+the generated code would fail to compile. The solution is to add the `tools:managedType` attribute
+which specifies the element's (all elements support this attribute) managed type.
+
+One may wonder why we didn't reuse the `tools:class` attribute to specify the managed type? It is
+because that attribute is used to specify the code-behind partial class name on the root element of
+the layout and should the element had the `android:id` attribute present we'd end up with generated 
+code that would use the **activity** type for the element's associated property instead of its
+actual type and the code wouldn't build.
+
 # How it works
 
 There are a couple of new MSBuild Tasks which generate the code behind.