Custom Control Renderers with Xamarin.Forms

Using custom control renderers to change the appearance and behavior of controls. Xamarin.Forms user interfaces are rendered using the native controls of the target platform, allowing Xamarin.Forms applications to retain the appropriate look and feel for each platform. Custom Renderers let developers override this process to customize the appearance and behavior of Xamarin.Forms controls on each platform. Custom renderers provide a powerful approach for customizing the appearance and behavior of Xamarin.Forms controls. They can be used for small styling changes or sophisticated platform-specific layout and behavior customization. This article provides an introduction to custom renderers, and outlines the process for creating a custom renderer.

Changing the appearance and behavior of Xamarin.Forms controls

Custom renderers provide a powerful approach for customizing the appearance and behavior of Xamarin.Forms controls. They can be used for small styling changes or sophisticated platform-specific layout and behavior customization. This article provides an introduction to custom renderers, and outlines the process for creating a custom renderer.

Xamarin.Forms Pages, Layouts and Controls present a common API to describe cross-platform mobile user interfaces. Each page, layout, and control is rendered differently on each platform, using a Renderer class that in turn creates a native control (corresponding to the Xamarin.Forms representation), arranges it on the screen, and adds the behavior specified in the shared code.

Developers can implement their own custom Renderer classes to customize the appearance and/or behavior of a control. Custom renderers for a given type can be added to one application project to customize the control in one place while allowing the default behavior on other platforms; or different custom renderers can be added to each application project to create a different look and feel on iOS, Android, and Windows Phone. However, implementing a custom renderer class in order to perform a simple control customization is often a heavy-weight response. Effects simplify this process, and are typically used for small styling changes.

Examining Why Custom Renderers are Necessary

Changing the appearance of a Xamarin.Forms control, without using a custom renderer, is a two-step process that involves creating a custom control through subclassing, and then consuming the custom control in place of the original control. The following code example shows an example of subclassing the Entry control:

public class MyEntry : Entry
{
  public MyEntry ()
  {
    BackgroundColor = Color.Gray;
  }
}

The MyEntry control is an Entry control where the BackgroundColor is set to gray, and can be referenced in Xaml by declaring a namespace for its location and using the namespace prefix on the control element. The following code example shows how the MyEntry custom control can be consumed by a ContentPage:

<ContentPage
    ...
    xmlns:local="clr-namespace:CustomRenderer;assembly=CustomRenderer"
    ...>
    ...
    <local:MyEntry Text="In Shared Code" />
    ...
</ContentPage>

The local namespace prefix can be anything. However, the namespace and assembly values must match the details of the custom control. Once the namespace is declared, the prefix is used to reference the custom control.

Defining the xmlns is much simpler in PCLs than Shared Projects. A PCL is compiled into an assembly so it's easy to determine what the assembly=CustomRenderer value should be. When using Shared Projects, all the shared assets (including the Xaml) are compiled into each of the referencing projects, which means that if the iOS, Android, and Windows Phone projects have their own assembly names it is impossible to to write the xmlns declaration because the value needs to be different for each application. Custom controls in Xaml for Shared Projects will require every application project to be configured with the same assembly name.

Changing the background color of the control on each platform has been accomplished purely through subclassing the control. However, this technique is limited in what it can achieve as it is not possible to take advantage of platform-specific enhancements and customizations. When they are required, custom renderers must be implemented.

Creating a Custom Renderer Class

The process for creating a custom renderer class is as follows:

  1. Create a subclass of the renderer class that renders the native control.
  2. Override the method that renders the native control and write logic to customize the control. Often, the OnElementChanged method is used to render the native control, which is called when the corresponding Xamarin.Forms control is created.
  3. Add an ExportRenderer attribute to the custom renderer class to specify that it will be used to render the Xamarin.Forms control. This attribute is used to register the custom renderer with Xamarin.Forms.

For most Xamarin.Forms elements, it is optional to provide a custom renderer in each platform project. If a custom renderer isn't registered, then the default renderer for the control's base class will be used. However, custom renderers are required in each platform project when rendering a View or ViewCell element.

The topics in this series will provide demonstrations and explanations of this process for different Xamarin.Forms elements.

Troubleshooting

If a custom control is contained in a PCL project that's been added to the solution (i.e. not the PCL created by the Xamarin Studio/Visual Studio Xamarin.Forms App project template), an exception may occur in iOS when attempting to access the custom control. If this issue occurs it can be resolved by creating a reference to the custom control from the AppDelegateclass:

var temp = new ClassInPCL(); // in AppDelegate, but temp not used anywhere

This forces the compiler to recognize the ClassInPCL type by resolving it. Alternatively, the Preserve attribute can be added to the AppDelegate class to achieve the same result:

[assembly: Preserve (typeof (ClassInPCL))]

This creates a reference to the ClassInPCL type, indicating that it's required at runtime.

This section has provided an introduction to custom renderers, and has outlined the process for creating a custom renderer. Custom renderers provide a powerful approach for customizing the appearance and behavior of Xamarin.Forms controls. They can be used for small styling changes or sophisticated platform-specific layout and behavior customization.

Renderer Base Classes and Native Controls

Every Xamarin.Forms control has an accompanying renderer for each platform that creates an instance of a native control. This article lists the renderer and native control classes that implement each Xamarin.Forms page, layout, view, and cell.

Rendering Xamarin.Forms controls

Every Xamarin.Forms control has an accompanying renderer for each platform that creates an instance of a native control. This article lists the renderer and native control classes that implement each Xamarin.Forms page, layout, view, and cell.

With the exception of the MapRenderer class, the platform-specific renderers can be found in the following namespaces:

  • iOS – Xamarin.Forms.Platform.iOS
  • Android – Xamarin.Forms.Platform.Android
  • Android (AppCompat) – Xamarin.Forms.Platform.Android.AppCompat
  • Windows Phone 8 – Xamarin.Forms.Platform.WinPhone
  • WinRT – Xamarin.Forms.Platform.WinRT
  • Universal Windows Platform (UWP) – Xamarin.Forms.Platform.UWP

The MapRenderer class can be found in the following namespaces:

  • iOS – Xamarin.Forms.Maps.iOS
  • Android – Xamarin.Forms.Maps.Android
  • Windows Phone 8 – Xamarin.Forms.Maps.WP8
  • WinRT – Xamarin.Forms.Maps.WinRT
  • Universal Windows Platform (UWP) – Xamarin.Forms.Maps.UWP

Pages

The following table lists the renderer and native control classes that implement each Xamarin.Forms Page type:

Page Renderer iOS Android Android (AppCompat) Windows Phone 8 WinRT / UWP
ContentPage PageRenderer UIViewController ViewGroup Panel FrameworkElement
MasterDetailPage

PhoneMasterDetailRenderer (iOS – Phone)

TabletMasterDetailPageRenderer (iOS – Tablet)

MasterDetailRenderer (Android)

MasterDetailPageRenderer (Android AppCompat)

MasterDetailRenderer (Windows Phone)

MasterDetailPageRenderer (WinRT)

UIViewController (Phone)

UISplitViewController (Tablet)

DrawerLayout (v4) DrawerLayout (v4) FrameworkElement FrameworkElement (Custom Control)
NavigationPage

NavigationRenderer (iOS and Android)

NavigationPageRenderer (Android AppCompat)

NavigationPageRenderer (Windows Phone 8 and WinRT)

UIToolbar ViewGroup ViewGroup FrameworkElement FrameworkElement (Custom Control)
TabbedPage

TabbedRenderer (iOS and Android)

TabbedPageRenderer (Android AppCompat)

TabbedPageRenderer (Windows Phone 8 and WinRT)

UIView ViewPager ViewPager UIElement (Pivot) FrameworkElement (Pivot)
TemplatedPage PageRenderer UIViewController ViewGroup Panel FrameworkElement
CarouselPage CarouselPageRenderer UIScrollView ViewPager ViewPager UIElement (Panorama) FrameworkElement (FlipView)

Layouts

The following table lists the renderer and native control classes that implement each Xamarin.Forms Layout type:

Layout Renderer iOS Android Windows Phone 8 WinRT / UWP
ContentPresenter ViewRenderer UIView View FrameworkElement FrameworkElement
ContentView ViewRenderer UIView View FrameworkElement FrameworkElement
Frame FrameRenderer UIView ViewGroup Border Border
ScrollView ScrollViewRenderer UIScrollView ScrollView ScrollViewer ScrollViewer
TemplatedView ViewRenderer UIView View FrameworkElement FrameworkElement
AbsoluteLayout ViewRenderer UIView View FrameworkElement FrameworkElement
Grid ViewRenderer UIView View FrameworkElement FrameworkElement
RelativeLayout ViewRenderer UIView View FrameworkElement FrameworkElement
StackLayout ViewRenderer UIView View FrameworkElement FrameworkElement

Views

The following table lists the renderer and native control classes that implement each Xamarin.Forms View type:

Views Renderer iOS Android Android (AppCompat) Windows Phone 8 WinRT / UWP
ActivityIndicator ActivityIndicatorRenderer UIActivityIndicator ProgressBar ProgressBar ProgressBar
BoxView

BoxRenderer (iOS and Android)

BoxViewRenderer (Windows Phone and WinRT)

UIView ViewGroup Rectangle Rectangle
Button ButtonRenderer UIButton Button AppCompatButton Button Button
CarouselView CarouselViewRenderer UIScrollView RecyclerView FlipView FlipView
DatePicker DatePickerRenderer UITextField EditText DatePicker DatePicker
Editor EditorRenderer UITextView EditText TextBox TextBox
Entry EntryRenderer UITextField EditText PhoneTextBox/PasswordBox TextBox
Image ImageRenderer UIImageView ImageView Image Image
Label LabelRenderer UILabel TextView TextBlock TextBlock
ListView ListViewRenderer UITableView ListView LongListSelector ListView
Map MapRenderer MKMapView MapView Map MapControl
Picker PickerRenderer UITextField EditText EditText FrameworkElement ComboBox
ProgressBar ProgressBarRenderer UIProgressView ProgressBar ProgressBar ProgressBar
SearchBar SearchBarRenderer UISearchBar SearchView PhoneTextBox

SearchBox (WinRT)

AutoSuggestBox (UWP)

Slider SliderRenderer UISlider SeekBar Slider Slider
Stepper StepperRenderer UIStepper LinearLayout Border with a StackPanel and two Buttons

UserControl (WinRT)

Control (UWP)

Switch SwitchRenderer UISwitch Switch SwitchCompat Border with a ToggleSwitchButton ToggleSwitch
TableView TableViewRenderer UITableView ListView Grid with a TextBlock and ListBox ListView
TimePicker TimePickerRenderer UITextField EditText TimePicker TimePicker
WebView WebViewRenderer UIWebView WebView WebBrowser WebView

Cells

The following table lists the renderer and native control classes that implement each Xamarin.Forms Cell type:

Cells Renderer iOS Android Windows Phone 8 WinRT / UWP
EntryCell EntryCellRenderer UITableViewCell with a UITextField LinearLayout with a TextView and EditText DataTemplate with a Grid containing a TextBlock and a PhoneTextBox DataTemplate with a TextBox
SwitchCell SwitchCellRenderer UITableViewCell with a UISwitch Switch DataTemplate with a ToggleSwitch DataTemplate with a Grid containing a TextBlock and ToggleSwitch
TextCell TextCellRenderer UITableViewCell LinearLayout with two TextViews DataTemplate with a Button containing a StackPanel with two TextBlocks DataTemplate with a StackPanel containing two TextBlocks
ImageCell ImageCellRenderer UITableViewCell with a UIImage LinearLayout with two TextViews and an ImageView DataTemplate with a Button containing a Grid with an Image, and a StackPanel containing two TextBlocks DataTemplate with a Grid containing an Image and two TextBlocks
ViewCell ViewCellRenderer UITableViewCell View DataTemplate with a ContentPresenter DataTemplate with a ContentPresenter

This section listed the renderer and native control classes that implement each Xamarin.Forms page, layout, view, and cell. Every Xamarin.Forms control has an accompanying renderer for each platform that creates an instance of a native control.

Customizing an Entry

The Xamarin.Forms Entry control allows a single line of text to be edited. This article demonstrates how to create a custom renderer for the Entry control, enabling developers to override the default native rendering with their own platform-specific customization.

Customizing a ContentPage

A ContentPage is a visual element that displays a single view and occupies most of the screen. This article demonstrates how to create a custom renderer for the ContentPage page, enabling developers to override the default native rendering with their own platform-specific customization.

Customizing a Map

Xamarin.Forms.Maps provides a cross-platform abstraction for displaying maps that use the native map APIs on each platform, in order to provide a fast and familiar map experience for users. This article demonstrates how to create a custom renderer for the Map control, enabling developers to override the default native rendering with their own platform-specific customization.

Customizing a ListView

A Xamarin.Forms ListView is a view that displays a collection of data as a vertical list. This article demonstrates how to create a custom renderer that encapsulates platform-specific list controls and native cell layouts, allowing more control over native list control performance.

Customizing a ViewCell

A Xamarin.Forms ViewCell is a cell that can be added to a ListView or TableView, which contains a developer-defined view. This article demonstrates how to create a custom renderer for a ViewCell that's hosted inside a Xamarin.Forms ListViewcontrol. This stops the Xamarin.Forms layout calculations from being repeatedly called during ListView scrolling.

Implementing a View

Xamarin.Forms custom user interfaces controls should derive from the View class, which is used to place layouts and controls on the screen. This article demonstrates how to create a custom renderer for a Xamarin.Forms custom control that's used to display a preview video stream from the device's camera.

Implementing a HybridWebView

This article demonstrates how to create a custom renderer for a HybridWebView custom control, which demonstrates how to enhance the platform-specific web controls to allow C# code to be invoked from JavaScript.

No Comments

Add a Comment

As it will appear on the website

Not displayed

Your website