Monday, June 30, 2014

Xamarin.Forms Custom Controls ImageSource

Xamarin.Forms has a great way to handle images cross platform in controls with the ImageSource.  The ImageSource allows you to specify the file name or URI of an image and a Xamarin.Forms handler will figure out how to load them correctly on the appropriate platform.  The following Xamarin site explains how to use the ImageSource for the stock controls that come with Xamarin.Forms

Working with Images

What if you want to make your own custom control, can you write it to use an ImageSource property?  This was the question I faced when creating an ImageButton control for the Xamarin Forms Labs project.  As it turns out it isn't as straightforward as I hoped, but it is possible.

To make this work first I created an ImageButton class that derived from the normal Button as so:

public class ImageButton : Button
{
    public static readonly BindableProperty SourceProperty =
        BindableProperty.Create<ImageButton, ImageSource>(
        p => p.Source, null);
        
    [TypeConverter(typeof(ImageSourceConverter))] 
    public ImageSource Source
    {
        get { return (ImageSource)GetValue(SourceProperty); }
        set { SetValue(SourceProperty, value); }
    }
}

One thing to note is that there is a TypeConverter on the Source property.  That is because the ImageSource cannot be created through a normal constructor passing in the string.  Instead there are factory methods, FromFile and FromUri to create instances of the ImageSource class.  Xamarin.Forms has a ImageSourceConverter class as a TypeConverter for this purpose; unfortunately this class is internal and can't be used directly.  Instead I made my own implementation as below.

public class ImageSourceConverter : TypeConverter
{
    public override bool CanConvertFrom(Type sourceType)
    {
        return sourceType == typeof(string);
    }

    public override object ConvertFrom(CultureInfo culture, object value)
    {
        if (value == null)
        {
            return null;
        }

        var str = value as string;
        if (str != null)
        {
            Uri result;
            if (!Uri.TryCreate(str, UriKind.Absolute, out result) || !(result.Scheme != "file"))
            {
                return ImageSource.FromFile(str);
            }
            return ImageSource.FromUri(result);
        }
        throw new InvalidOperationException(
            string.Format("Conversion failed: \"{0}\" into {1}",
                new[] { value, typeof(ImageSource) }));
    }
}

We need one more thing before we can create our custom renderers.  There are three handlers that convert our ImageSource to the proper platform specific image depending on if a UriImageSource, FileImageSource or StreamImageSource is being used.  Internally Xamarin.Forms uses the Xamarin.Forms.Registrar to resolve out the proper handler.  Unfortunately this class is also internal and can't be used by our custom renderers.  To solve this I created a class and linked it to my platform specific projects where my custom renderers will reside.  This is the class I used to resolve out the proper handler:

#if __Android__
using Xamarin.Forms.Platform.Android;

namespace Xamarin.Forms.Labs.Droid.Controls.ImageButton
#elif __IOS__
using Xamarin.Forms.Platform.iOS;

namespace Xamarin.Forms.Labs.iOS.Controls.ImageButton
#elif WINDOWS_PHONE
using Xamarin.Forms.Platform.WinPhone;

namespace Xamarin.Forms.Labs.WP8.Controls.ImageButton
#endif
{
    public partial class ImageButtonRenderer
    {
        private static IImageSourceHandler GetHandler(ImageSource source)
        {
            IImageSourceHandler returnValue = null;
            if (source is UriImageSource)
            {
                returnValue = new ImageLoaderSourceHandler();
            }
            else if (source is FileImageSource)
            {
                returnValue = new FileImageSourceHandler();
            }
            else if (source is StreamImageSource)
            {
                returnValue = new StreamImagesourceHandler();
            }
            return returnValue;
        }
    }
}

Then I implemented my custom renderers.  I'm not going to show all of their code here and if you want to see the full code check out the Xamarin.Forms.Labs project on Github.  For the iOS platform renderer i resolved out the ImageSource into a iOS UIImage like this:

private async static Task SetImageAsync(ImageSource source, int widthRequest, int heightRequest, UIButton targetButton)
{
    var handler = GetHandler(source);
    using (UIImage image = await handler.LoadImageAsync(source))
    {
        UIGraphics.BeginImageContext(new SizeF(widthRequest, heightRequest));
        image.Draw(new RectangleF(0, 0, widthRequest, heightRequest));
        using (var resultImage = UIGraphics.GetImageFromCurrentImageContext())
        {
            UIGraphics.EndImageContext();
            using (var resizableImage =
                resultImage.CreateResizableImage(new UIEdgeInsets(0, 0, widthRequest, heightRequest)))
            {
                targetButton.SetImage(
                    resizableImage.ImageWithRenderingMode(UIImageRenderingMode.AlwaysOriginal),
                    UIControlState.Normal);
            }
        }
    }
}

On the Android platform's custom renderer for the ImageButton I resolved it out like this:

private async Task<Bitmap> GetBitmapAsync(ImageSource source)
{
    var handler = GetHandler(source);
    var returnValue = (Bitmap)null;

    returnValue = await handler.LoadImageAsync(source, this.Context);

    return returnValue;
}

On the Windows Phone platform I resolved out the ImageSource like this:

private async static Task<System.Windows.Controls.Image> GetImageAsync(ImageSource source, int height, int width)
{
    var image = new System.Windows.Controls.Image();
    var handler = GetHandler(source);
    var imageSource = await handler.LoadImageAsync(source);

    image.Source = imageSource;
    image.Height = Convert.ToDouble(height / 2);
    image.Width = Convert.ToDouble(width / 2);
    return image;
}

That's how I implemented the Source property on my custom ImageButton control and now I get all the cross platform image handling goodness.  I hope this helps if you need to make a Xamarin.Forms custom control that needs to implement a cross platform image.

Wednesday, June 11, 2014

Xamarin - Xamarin.Forms Renderer Reference

Now that I've spent some time working with writing custom renderers with Xamarin.Forms I've found that one of the easiest ways to extend an existing control is to also extend the an existing platform renderers.  For example, when I created an ImageButton for the Xforms-Toolkit, I extended the existing ButtonRenderers for the three platforms.  This seemed easier to me than extending the base renderers for the three platforms and starting from scratch.  What I found as I continued to work creating custom renderers is that I was being frustrated by not always knowing what renderer was associated with a particular Xamarin.Forms control for a given platform and what native control or controls were being created under the covers by the renderer.

To help with this I put together this guide to list what renderers are associated with what Xamarin.Forms controls and what native control or controls are being created by the platform specific renderers.

This guide was update using Xamarin.Forms version 1.1.1.6206, which is the latest version at the time of this page's last edit.

Platform Specific renderers can be found in the following namespaces:

iOS: Xamarin.Forms.Platform.iOS
Android: Xamarin.Forms.Platform.Android
Windows Phone: Xamarin.Forms.Platform.WinPhone

With the 6201 release many of the inconsistencies in the controls have been address but some still exist.  Sometimes the Windows Phone renderers were creating the native controls by loading an Xaml file or pulling the native control out of Application.CurrentResources.  In these cases I was not able to tell exactly what native controls were being created.

Base Renderer
To start with, all renders usually derive from a platform specific base renderer class that in turn inherit from a platform specific control.  If you want to create platform specific renderers from scratch you are probably going to be deriving them from the correct platform's base renderer class.  These have been substantially standardized in version 6201 with all controls inheriting from a generic version of ViewRenderer.  There is also a non-generic version that appears to be used sometimes by navigation controls.  The methods on these classes are also more in line with each other than they had been but still not the same.  For example the iOS version has a method called ViewOnUnfocusRequested while the Android's version of the same method is called OnUnfocusRequested.

iOS:
Renderer: Xamarin.Forms.Platform.iOS.ViewRenderer<TView, TNavitveView>
Platform Specific Control: types deriving from MonoTouch.UIKit.UIView
Android
Renderer: Xamarin.Forms.Platform.Android.ViewRenderer<TView, TNavitveView>
Platform Specific Control: types deriving from Android.Views.ViewGroup
Windows Phone
Renderer: Xamarin.Forms.Platform.WinPhone.ViewRenderer<TElement, TNativeElement>
Platform Specific Control: types deriving from System.Windows.FrameworkElement

Layout Renderers
ContentPage
iOS
Renderer: Xamarin.Forms.Platform.iOS.PageRenderer
Platform Specific Control: MonoTouch.UIKit.UIView
Android
Renderer: Xamarin.Forms.Platform.Android.PageRenderer
Platform Specific Control: Android.Views.ViewGroup
Windows Phone
Renderer: Xamarin.Forms.Platform.WinPhone.PageRenderer
Platform Specific Control: System.Windows.Controls.Panel

MasterDetailPage
iOS
Renderer: Xamarin.Forms.Platform.iOS.PhoneMasterDetailRenderer for iPhone and Xamarin.Forms.Platform.iOS.TabletMasterDetailRenderer for iPad
Platform Specific Control: custom flyout on iPhone and MonoTouch.UIKit.UISplitViewController for iPad
Android
Renderer: Xamarin.Forms.Platform.Android.MasterDetailRenderer
Platform Specific Control: Android.Support.V4.Widget.DrawerLayout
Windows Phone
Renderer: Xamarin.Forms.Platform.WinPhone.MasterDetailRenderer
Platform Specific Control: System.Windows.Controls.Panel

NavigationPage
iOS
Renderer: Xamarin.Forms.Platform.iOS.NavigationRenderer
Platform Specific Control: MonoTouch.UIKit.UIToolbar and derives from MonoTouch.UIKit.UINavigationController
Android
Renderer: Xamarin.Forms.Platform.Android.NavigationRenderer
Platform Specific Control: No View of its own, deals with switching content derived from Android.Views.View
Windows Phone
Renderer: Xamarin.Forms.Platform.WinPhone.NavigationPageRenderer
Platform Specific Control: No View of its own, deals with switching content derived from System.Windows.FrameworkElements

TabbedPage
iOS
Renderer: Xamarin.Forms.Platform.iOS.TabbedRenderer
Platform Specific Control: MonoTouch.UIKit.UIViewController with contained MonoTouch.UIKit.UIView
Android
Renderer: Xamarin.Forms.Platform.Android.TabbedRenderer
Platform Specific Control: No View of its own, deals with switching content derived from Android.Views.View
Windows Phone
Renderer: Xamarin.Forms.Platform.WinPhone.TabbedPageRenderer
Platform Specific Control: inherits from Microsoft.Phone.Controls.Pivot

CarouselPage
iOS
Renderer: Xamarin.Forms.Platform.iOS.CarouselPageRenderer
Platform Specific Control: MonoTouch.UIKit.UIScrollView
Android
Renderer: Xamarin.Forms.Platform.Android.CarouselPageRenderer
Platform Specific Control: Android.Views.View
Windows Phone
Renderer: Xamarin.Forms.Platform.WinPhone.CarouselPageRenderer
Platform Specific Control: Microsoft.Phone.Controls.PanoramaItem

Frame
iOS
Renderer: Xamarin.Forms.Platform.iOS.FrameRenderer
Platform Specific Control: MonoTouch.UIKit.UIView
Android
Renderer: Xamarin.Forms.Platform.Android.FrameRenderer
Platform Specific Control: Android.Graphics.Drawables.Drawable
Windows Phone
Renderer: Xamarin.Forms.Platform.WinPhone.FrameRenderer
Platform Specific Control: System.Windows.UIElement

ScrollView
iOS
Renderer: Xamarin.Forms.Platform.iOS.ScrollViewRenderer
Platform Specific Control: MonoTouch.UIKit.UIScrollView
Android
Renderer: Xamarin.Forms.Platform.Android.ScrollViewRenderer
Platform Specific Control: Android.Widget.ScrollView
Windows Phone
Renderer: Xamarin.Forms.Platform.WinPhone.ScrollViewRenderer
Platform Specific Control: System.Windows.Controls.ScrollViewer

AbsoluteLayout
iOS
Renderer: Unsure
Platform Specific Control: Unsure
Android
Renderer: Unsure
Platform Specific Control: Unsure
Windows Phone
Renderer: Unsure
Platform Specific Control: Unsure

Grid
iOS
Renderer: Unsure
Platform Specific Control: Unsure
Android
Renderer: Unsure
Platform Specific Control: Unsure
Windows Phone
Renderer: Unsure
Platform Specific Control: Unsure

RelativeLayout
iOS
Renderer: Unsure
Platform Specific Control: Unsure
Android
Renderer: Unsure
Platform Specific Control: Unsure
Windows Phone
Renderer: Unsure
Platform Specific Control: Unsure

StackLayout
iOS
Renderer: Unsure
Platform Specific Control: Unsure
Android
Renderer: Unsure
Platform Specific Control: Unsure
Windows Phone
Renderer: 
Platform Specific Control: Unsure

TableView
iOS
Renderer: Xamarin.Forms.Platform.iOS.TableViewRenderer
Platform Specific Control: MonoTouch.UIKit.UITableView
Android
Renderer: Xamarin.Forms.Platform.Android.TableViewRenderer (Table),  Xamarin.Forms.Platform.Android.TableViewModelRenderer (Rows)
Platform Specific Control: Android.Widget.ListView (Table), Android.Views.View (Row)
Windows Phone
Renderer: Xamarin.Forms.Platform.WinPhone.TableViewRenderer
Platform Specific Control: Microsoft.Phone.Controls.LongListSelector

Control Renderers
ActivityIndicator
iOS
Renderer: Xamarin.Forms.Platform.iOS.ActivityIndicatorRenderer
Platform Specific Control: MonoTouch.UIKit.UIActivityIndicatorView
Android
Renderer: Xamarin.Forms.Platform.Android.ActivityIndicatorRenderer
Platform Specific Control: Android.Widget.ProgressBar
Windows Phone
Renderer: Xamarin.Forms.Platform.WinPhone.ActivityIndicatorRenderer
Platform Specific Control: System.Windows.Controls.ProgressBar

BoxView
iOS
Renderer: Xamarin.Forms.Platform.iOS.BoxRenderer
Platform Specific Control: MonoTouch.CoreGrahics.CGContext
Android
Renderer: Xamarin.Forms.Platform.Android.BoxRenderer
Platform Specific Control: Android.Views.ViewGroup
Windows Phone
Renderer: Xamarin.Forms.Platform.WinPhone.BoxViewRenderer
Platform Specific Control: System.Windows.Shapes.Rectangle

Button
iOS
Renderer: Xamarin.Forms.Platform.iOS.ButtonRenderer
Platform Specific Control: MonoTouch.UIKit.UIButton
Android
Renderer: Xamarin.Forms.Platform.Android.ButtonRenderer
Platform Specific Control: Android.Widget.Button
Windows Phone
Renderer: Xamarin.Forms.Platform.WinPhone.ButtonRenderer
Platform Specific Control: System.Windows.Controls.Button

DatePicker
iOS
Renderer: Xamarin.Forms.Platform.iOS.DatePickerRenderer
Platform Specific Control: MonoTouch.UIKit.UIToolbar with MonoTouch.UIKit.UIBarButtonItems
Android
Renderer: Xamarin.Forms.Platform.Android.DatePickerRenderer
Platform Specific Control: Android.App.DatePickerDialog
Windows Phone
Renderer: Xamarin.Forms.Platform.WinPhone.DatePickerRenderer
Platform Specific Control: Microsoft.Phone.Controls.DateTimePickerBase

Editor
iOS
Renderer: Xamarin.Forms.Platform.iOS.EditorRenderer
Platform Specific Control: MonoTouch.UIKit.UITextView
Android
Renderer: Xamarin.Forms.Platform.Android.EditorRenderer
Platform Specific Control: Android.Widget.EditText
Windows Phone
Renderer: Xamarin.Forms.Platform.WinPhone.EditorRenderer
Platform Specific Control: System.Windows.Controls.TextBox

Entry
iOS
Renderer: Xamarin.Forms.Platform.iOS.EntryRenderer
Platform Specific Control: MonoTouch.UIKit.UITextField
Android
Renderer: Xamarin.Forms.Platform.Android.EntryRenderer
Platform Specific Control: Android.Widget.EditText
Windows Phone
Renderer: Xamarin.Forms.Platform.WinPhone.EntryRenderer
Platform Specific Control: Microsoft.Phone.Controls.PhoneTextBox or System.Windows.Controls.PasswordBox

Image
iOS
Renderer: Xamarin.Forms.Platform.iOS.ImageRenderer
Platform Specific Control: MonoTouch.UIKit.UIImageView
Android
Renderer: Xamarin.Forms.Platform.Android.ImageRenderer
Platform Specific Control: Android.Widget.ImageView
Windows Phone
Renderer: Xamarin.Forms.Platform.WinPhone.ImageRenderer
Platform Specific Control: System.Windows.Controls.Image

Label
iOS
Renderer: Xamarin.Forms.Platform.iOS.LabelRenderer
Platform Specific Control: MonoTouch.UIKit.UILabel
Android
Renderer: Xamarin.Forms.Platform.Android.LabelRenderer
Platform Specific Control: Android.Widget.TextView
Windows Phone
Renderer: Xamarin.Forms.Platform.WinPhone.LabelRenderer
Platform Specific Control: System.Windows.Controls.TextBlock

ListView
iOS
Renderer: Xamarin.Forms.Platform.iOS.ListViewRenderer
Platform Specific Control: MonoTouch.UIKit.UITableView
Android
Renderer: Xamarin.Forms.Platform.Android.ListViewRenderer (currently internal in scope and not derivable)
Platform Specific Control: Android.Widget.ListView
Windows Phone
Renderer: Xamarin.Forms.Platform.WinPhone.ListViewRenderer
Platform Specific Control: Microsoft.Phone.Controls.LongListSelector

OpenGLView
iOS
Renderer: Xamarin.Forms.Platform.iOS.OpenGLViewRenderer
Platform Specific Control: MonoTouch.GLKit.GLKView
Android
Renderer: Xamarin.Forms.Platform.Android.OpenGLRenderer (currently internal in scope and not derivable)
Platform Specific Control: Android.Opengl.GLSurfaceView
Windows Phone
Renderer: Unsure
Platform Specific Control: Unsure

Picker
iOS
Renderer: Xamarin.Forms.Platform.iOS.PickerRenderer
Platform Specific Control: MonoTouch.UIKit.UIPickerView, MonoTouch.UIKit.UIPickerViewModel, MonoTouch.UIKit.UIToolBar, Two MonoTouch.UIKit.UIBarButtonItems, MonoTouch.UIKit.UITextField
Android
Renderer: Xamarin.Forms.Platform.Android.PickerRenderer
Platform Specific Control: Android.Widget.TextView, Android.App.AlertDialog and Android.Widget.NumberPicker
Windows Phone
Renderer: Xamarin.Forms.Platform.WinPhone.PickerRenderer
Platform Specific Control: Microsoft.Phone.Controls.ListPicker

ProgressBar
iOS
Renderer: Xamarin.Forms.Platform.iOS.ProgressBarRenderer
Platform Specific Control: MonoTouch.UIKit.UIProgressView
Android
Renderer: Xamarin.Forms.Platform.Android.ProgressBarRenderer
Platform Specific Control: Android.Widget.ProgressBar
Windows Phone
Renderer: Xamarin.Forms.Platform.WinPhone.ProgressBarRenderer
Platform Specific Control: System.Windows.Controls.ProgressBar

SearchBar
iOS
Renderer: Xamarin.Forms.Platform.iOS.SearchBarRenderer
Platform Specific Control: MonoTouch.UIKit.UISearchBar
Android
Renderer: Xamarin.Forms.Platform.Android.SearchBarRenderer
Platform Specific Control: Android.Widget.SearchView
Windows Phone
Renderer: Xamarin.Forms.Platform.WinPhone.SearchBarRenderer
Platform Specific Control: Microsoft.Phone.Controls.PhoneTextBox

Slider
iOS
Renderer: Xamarin.Forms.Platform.iOS.SliderRenderer
Platform Specific Control: MonoTouch.UIKit.UISlider
Android
Renderer: Xamarin.Forms.Platform.Android.SliderRenderer
Platform Specific Control: Android.Widget.SeekBar
Windows Phone
Renderer: Xamarin.Forms.Platform.WinPhone.SliderRenderer
Platform Specific Control: System.Windows.Controls.Slider

Stepper
iOS
Renderer: Xamarin.Forms.Platform.iOS.StepperRenderer
Platform Specific Control: MonoTouch.UIKit.UIStepper
Android
Renderer: Xamarin.Forms.Platform.Android.StepperRenderer
Platform Specific Control: Android.Widget.LinearLayout with four Android.Widget.Buttons
Windows Phone
Renderer: Xamarin.Forms.Platform.WinPhone.StepperRenderer
Platform Specific Control: System.Windows.Controls.Border with four System.Windows.Controls.Buttons

Switch
iOS
Renderer: Xamarin.Forms.Platform.iOS.SwitchRenderer
Platform Specific Control: MonoTouch.UIKit.UISwitch
Android
Renderer: Xamarin.Forms.Platform.Android.SwitchRenderer
Platform Specific Control: Android.Widget.Switch
Windows Phone
Renderer: Xamarin.Forms.Platform.WinPhone.SwitchRenderer
Platform Specific Control: System.Windows.Controls.Primitives.ToggleButton

TimePicker
iOS
Renderer: Xamarin.Forms.Platform.iOS.TimePickerRenderer
Platform Specific Control: MonoTouch.UIKit.UIDatePicker, MonoTouch.UIKit.UITextField, MonoTouch.UIKit.UIToolbar, MonoTouch.UIKit.UIBarButtonItems
Android
Renderer: Xamarin.Forms.Platform.Android.TimePickerRenderer
Platform Specific Control: Two Android.Widget.TextViews and a Android.App.AlertDialog
Windows Phone
Renderer: Xamarin.Forms.Platform.WinPhone.TimePickerRenderer
Platform Specific Control: Microsoft.Phone.Controls.DateTimePickerBase

WebView
iOS
Renderer: Xamarin.Forms.Platform.iOS.WebViewRenderer
Platform Specific Control: MonoTouch.UIKit.UIWebView
Android
Renderer: Xamarin.Forms.Platform.Android.WebRenderer
Platform Specific Control: Android.Webkit.WebView
Windows Phone
Renderer: Xamarin.Forms.Platform.WinPhone.WebViewRenderer
Platform Specific Control: Microsoft.Phone.Controls.WebBrowser

Cell Controls
EntryCell
iOS
Renderer: Xamarin.Forms.Platform.iOS.EntryCellRenderer
Platform Specific Control: MonoTouch.UIKit.UITableViewCell with a MonoTouch.UIKit.UITextField
Android
Renderer: Xamarin.Forms.Platform.Android.EntryCellRenderer
Platform Specific Control: Android.Widget.LinearLayout contianing Android.Widget.TextView and Android.Widget.EditText
Windows Phone
Renderer: Xamarin.Forms.Platform.WinPhone.EntryCellRenderer
Platform Specific Control: Pulls from Application.Current.Resources for name "EntryCell" of type System.Windows.DataTemplate

SwitchCell
iOS
Renderer: Xamarin.Forms.Platform.iOS.SwitchCellRenderer
Platform Specific Control: MonoTouch.UIKit.UITableViewCell with a MonoTouch.UIKit.UISwitch
Android
Renderer: Xamarin.Forms.Platform.Android.SwitchCellRenderer
Platform Specific Control: Android.Widget.Switch
Windows Phone
Renderer: Xamarin.Forms.Platform.WinPhone.SwitchCellRenderer
Platform Specific Control: Pulls from Application.Current.Resources for name "SwitchCell" of type System.Windows.DataTemplate

TextCell
iOS
Renderer: Xamarin.Forms.Platform.iOS.TextCellRenderer
Platform Specific Control: MonoTouch.UIKit.UITableViewCel
Android
Renderer: Xamarin.Forms.Platform.Android.TextCellRenderer
Platform Specific Control: Android.Widget.LinearLayout contianing two Android.Widget.TextViews and Android.Widget.ImageView
Windows Phone
Renderer: Xamarin.Forms.Platform.WinPhone.TextCellRenderer
Platform Specific Control: Pulls from Application.Current.Resources for name "TextCell", or "ListViewHeaderTextCell" or "ListViewTextCell" of type System.Windows.DataTemplate depending on parent/context of the cell.

ImageCell
iOS
Renderer: Xamarin.Forms.Platform.iOS.ImageCellRenderer
Platform Specific Control: MonoTouch.UIKit.UITableViewCell with a MonoTouch.UIKit.UIImage
Android
Renderer: Xamarin.Forms.Platform.Android.ImageCellRenderer
Platform Specific Control: Android.Widget.LinearLayout contianing two Android.Widget.TextViews and Android.Widget.ImageView
Windows Phone
Renderer: Xamarin.Forms.Platform.WinPhone.ImageCellRenderer
Platform Specific Control: Pulls from Application.Current.Resources for name "ListImageCell", or "ImageCell" of type System.Windows.DataTemplate depending on parent/context of the cell.

I hope this helps people trying to understand what these renderers are creating on the native platforms and gives a hint at how they can be extended.