Consuming Platform-Specifics

PDF for offline use
Sample Code:
Related Articles:

Let us know how you feel about this

Translation Quality


0/250

last updated: 2016-11

Platform-specifics allow you to consume functionality that's only available on a specific platform, without implementing custom renderers or effects. This article demonstrates how to consume the platform-specifics that are built into Xamarin.Forms.

Overview

The following platform-specific functionality is built into Xamarin.Forms:

The process for consuming a platform-specific through XAML, or through a fluent code API is as follows:

  1. Add a xmlns declaration or using directive for the Xamarin.Forms.PlatformConfiguration namespace.
  2. Add a xmlns declaration or using directive for the namespace that contains the platform-specific functionality:
    1. On iOS, this is the Xamarin.Forms.PlatformConfiguration.iOSSpecific namespace.
    2. On Android, this is the Xamarin.Forms.PlatformConfiguration.AndroidSpecific namespace.
    3. On the Universal Windows Platform, this is the Xamarin.Forms.PlatformConfiguration.WindowsSpecific namespace.
  3. Apply the platform-specific from XAML, or from code with the On<T> fluent API. The value of T can be the iOS, Android, or Windows types from the Xamarin.Forms.PlatformConfiguration namespace.

Note that attempting to consume a platform-specific on a platform where it is unavailable will not result in an error. Instead, the code will execute without the platform-specific being applied.

Platform-specifics consumed through the On<T> fluent code API return IPlatformElementConfiguration objects. This allows multiple platform-specifics to be invoked on the same object with method cascading.

In addition, vendors can create their own platform-specifics with Effects. For more information, see Creating Platform-Specifics.

Platform Specifics

The following sections demonstrate the platform-specifics that are available on each platform.

iOS

On iOS, Xamarin.Forms contains platform-specifics for blur support on any VisualElement instances, and a translucent navigation bar.

Applying Blur

This platform-specific is used to blur the content layered beneath it, and is consumed in XAML by setting the VisualElement.BlurEffect attached property to a value of the BlurEffectStyle enumeration:

<ContentPage ...
             xmlns:ios="clr-namespace:Xamarin.Forms.PlatformConfiguration.iOSSpecific;assembly=Xamarin.Forms.Core">
  ...
  <AbsoluteLayout HorizontalOptions="Center">
    <Image Source="monkeyface.png" />
    <BoxView x:Name="boxView" ios:VisualElement.BlurEffect="ExtraLight" HeightRequest="300" WidthRequest="300" />
  </AbsoluteLayout>
  ...
</ContentPage>

Alternatively, it can be consumed from C# using the fluent API:

using Xamarin.Forms.PlatformConfiguration;
using Xamarin.Forms.PlatformConfiguration.iOSSpecific;

...

boxView.On<iOS>().UseBlurEffect(BlurEffectStyle.ExtraLight);

The BoxView.On<iOS> method specifies that this platform-specific will only run on iOS. The VisualElement.UseBlurEffect method, in the Xamarin.Forms.PlatformConfiguration.iOSSpecific namespace, is used to apply the blur effect, with the BlurEffectStyle enumeration providing four values: None, ExtraLight, Light, and Dark.

The result is that a specified BlurEffectStyle is applied to the BoxView instance, which blurs the Image layered beneath it:

Making the Navigation Bar Translucent

This platform-specific is used to change the transparency of the navigation bar, and is consumed in XAML by setting the NavigationPage.IsNavigationBarTranslucent attached property to a boolean value:

<NavigationPage ...
                xmlns:ios="clr-namespace:Xamarin.Forms.PlatformConfiguration.iOSSpecific;assembly=Xamarin.Forms.Core"
                BackgroundColor="Blue"
                ios:NavigationPage.IsNavigationBarTranslucent="true">
  ...
</NavigationPage>

Alternatively, it can be consumed from C# using the fluent API:

using Xamarin.Forms.PlatformConfiguration;
using Xamarin.Forms.PlatformConfiguration.iOSSpecific;

...

(App.Current.MainPage as Xamarin.Forms.NavigationPage).BackgroundColor = Color.Blue;
(App.Current.MainPage as Xamarin.Forms.NavigationPage).On<iOS>().EnableTranslucentNavigationBar();

The NavigationPage.On<iOS> method specifies that this platform-specific will only run on iOS. The NavigationPage.EnableTranslucentNavigationBar method, in the Xamarin.Forms.PlatformConfiguration.iOSSpecific namespace, is used to make the navigation bar translucent. In addition, the NavigationPage class in the Xamarin.Forms.PlatformConfiguration.iOSSpecific namespace also has a DisableTranslucentNavigationBar method that restores the navigation bar to its default state, and a SetIsNavigationBarTranslucent method which can be used to toggle the navigation bar transparency by calling the IsNavigationBarTranslucent method:

(App.Current.MainPage as Xamarin.Forms.NavigationPage)
  .On<iOS>()
  .SetIsNavigationBarTranslucent(!(App.Current.MainPage as Xamarin.Forms.NavigationPage).On<iOS>().IsNavigationBarTranslucent());

The result is that the transparency of the navigation bar can be changed:

Android

On Android, Xamarin.Forms contains a platform-specific for setting the operating mode of a soft keyboard.

Setting the Soft Keyboard Input Mode

This platform-specific is used to set the operating mode for a soft keyboard input area, and is consumed in XAML by setting the Application.WindowSoftInputModeAdjust attached property to a value of the WindowSoftInputModeAdjust enumeration:

<Application ...
             xmlns:android="clr-namespace:Xamarin.Forms.PlatformConfiguration.AndroidSpecific;assembly=Xamarin.Forms.Core"
             android:Application.WindowSoftInputModeAdjust="Resize">
  ...
</Application>

Alternatively, it can be consumed from C# using the fluent API:

using Xamarin.Forms.PlatformConfiguration;
using Xamarin.Forms.PlatformConfiguration.AndroidSpecific;

...

App.Current.On<Android>().UseWindowSoftInputModeAdjust(WindowSoftInputModeAdjust.Resize);

The Application.On<Android> method specifies that this platform-specific will only run on Android. The Application.UseWindowSoftInputModeAdjust method, in the Xamarin.Forms.PlatformConfiguration.AndroidSpecific namespace, is used to set the soft keyboard input area operating mode, with the WindowSoftInputModeAdjust enumeration providing two values: Pan and Resize. The Pan value uses the AdjustPan adjustment option, which doesn't resize the window when an input control has focus. Instead, the contents of the window are panned so that the current focus isn't obscured by the soft keyboard. The Resize value uses the AdjustResize adjustment option, which resizes the window when an input control has focus, in order to make room for the soft keyboard.

The result is that the soft keyboard input area operating mode can be set when an input control has focus:

Universal Windows Platform

On the Universal Windows Platform (UWP), Xamarin.Forms contains platform-specifics for control over toolbar placement, and a partially collapsable MasterDetailPage navigation bar.

Changing the Toolbar Placement

This platform-specific is used to change the placement of a toolbar on a Page, and is consumed in XAML by setting the Page.ToolbarPlacement attached property to a value of the ToolbarPlacement enumeration:

<TabbedPage ...
            xmlns:windows="clr-namespace:Xamarin.Forms.PlatformConfiguration.WindowsSpecific;assembly=Xamarin.Forms.Core"
            windows:Page.ToolbarPlacement="Bottom">
  ...
</TabbedPage>

Alternatively, it can be consumed from C# using the fluent API:

using Xamarin.Forms.PlatformConfiguration;
using Xamarin.Forms.PlatformConfiguration.WindowsSpecific;

...

page.On<Windows>().SetToolbarPlacement(ToolbarPlacement.Bottom);

The Page.On<Windows> method specifies that this platform-specific will only run on Windows. The Page.SetToolbarPlacement method, in the Xamarin.Forms.PlatformConfiguration.Windows namespace, is used to set the toolbar placement, with the ToolbarPlacement enumeration providing three values: Default, Top, and Bottom.

The result is that the specified toolbar placement is applied to the Page instance:

Collapsing a MasterDetailPage Navigation Bar

This platform-specific is used to collapse the navigation bar on a MasterDetailPage, and is consumed in XAML by setting the MasterDetailPage.CollapseStyle and MasterDetailPage.CollapsedPaneWidth attached properties:

<MasterDetailPage ...
                  xmlns:windows="clr-namespace:Xamarin.Forms.PlatformConfiguration.WindowsSpecific;assembly=Xamarin.Forms.Core"
                  windows:MasterDetailPage.CollapseStyle="Partial"
                  windows:MasterDetailPage.CollapsedPaneWidth="48">
  ...
</MasterDetailPage>

Alternatively, it can be consumed from C# using the fluent API:

using Xamarin.Forms.PlatformConfiguration;
using Xamarin.Forms.PlatformConfiguration.WindowsSpecific;

...

page.On<Windows>().SetCollapseStyle(CollapseStyle.Partial).CollapsedPaneWidth(148);

The MasterDetailPage.On<Windows> method specifies that this platform-specific will only run on Windows. The Page.SetCollapseStyle method, in the Xamarin.Forms.PlatformConfiguration.WindowsSpecific namespace, is used to specify the collapse style, with the CollapseStyle enumeration providing two values: Full and Partial. The MasterDetailPage.CollapsedPaneWidth method is used to specify the width of a partially collapsed navigation bar.

The result is that a specified CollapseStyle is applied to the MasterDetailPage instance, with the width also being specified:

Summary

This article demonstrated how to consume the platform-specifics that are built into Xamarin.Forms. Platform-specifics allow you to consume functionality that's only available on a specific platform, without implementing custom renderers or effects.

Xamarin Workbook

If it's not already installed, install the Xamarin Workbooks app first. The workbook file should download automatically, but if it doesn't, just click to start the workbook download manually.