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.

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.