iOS Platform-Specifics

PDF for offline use
Sample Code:
Related Articles:
Related APIs:

Let us know how you feel about this

Translation Quality


0/250

last updated: 2017-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 iOS platform-specifics that are built into Xamarin.Forms.

On iOS, Xamarin.Forms contains the following platform-specifics:

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:

Displaying Large Titles

This platform-specific is used to display the page title as a large title on the navigation bar, for devices that use iOS 11 or greater. A large title is left aligned and uses a larger font, and transitions to a standard title as the user begins scrolling content, so that the screen real estate is used efficiently. However, in landscape orientation, the title will return to the center of the navigation bar to optimize content layout. It's consumed in XAML by setting the NavigationPage.PrefersLargeTitles attached property to a boolean value:

<NavigationPage xmlns="http://xamarin.com/schemas/2014/forms"
                xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
                xmlns:ios="clr-namespace:Xamarin.Forms.PlatformConfiguration.iOSSpecific;assembly=Xamarin.Forms.Core"
                ...
                ios:NavigationPage.PrefersLargeTitles="true">
  ...
</NavigationPage>

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

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

var navigationPage = new Xamarin.Forms.NavigationPage(new iOSLargeTitlePageCS());
navigationPage.On<iOS>().SetPrefersLargeTitles(true);

The NavigationPage.On<iOS> method specifies that this platform-specific will only run on iOS. The NavigationPage.SetPrefersLargeTitle method, in the Xamarin.Forms.PlatformConfiguration.iOSSpecific namespace, controls whether large titles are enabled.

Provided that large titles are enabled on the NavigationPage, all pages in the navigation stack will display large titles. This behavior can be overridden on pages by setting the Page.LargeTitleDisplay attached property to a value of the LargeTitleDisplayMode enumeration:

<ContentPage ...
             xmlns:ios="clr-namespace:Xamarin.Forms.PlatformConfiguration.iOSSpecific;assembly=Xamarin.Forms.Core"
             Title="Large Title"
             ios:Page.LargeTitleDisplay="Never">
  ...
</ContentPage>

Alternatively, the page behavior can be overridden from C# using the fluent API:

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

public class iOSLargeTitlePageCS : ContentPage
{
    public iOSLargeTitlePageCS(ICommand restore)
    {
        On<iOS>().SetLargeTitleDisplay(LargeTitleDisplayMode.Never);
        ...
    }
    ...
}

The Page.On<iOS> method specifies that this platform-specific will only run on iOS. The Page.SetLargeTitleDisplay method, in the Xamarin.Forms.PlatformConfiguration.iOSSpecific namespace, controls the large title behavior on the Page, with the LargeTitleDisplayMode enumeration providing three possible values:

  • Always – force the navigation bar and font size to use the large format.
  • Automatic – use the same style (large or small) as the previous item in the navigation stack.
  • Never – force the use of the regular, small format navigation bar.

In addition, the SetLargeTitleDisplay method can be used to toggle the enumeration values by calling the LargeTitleDisplay method, which returns the current LargeTitleDisplayMode:

switch (On<iOS>().LargeTitleDisplay())
{
    case LargeTitleDisplayMode.Always:
        On<iOS>().SetLargeTitleDisplay(LargeTitleDisplayMode.Automatic);
        break;
    case LargeTitleDisplayMode.Automatic:
        On<iOS>().SetLargeTitleDisplay(LargeTitleDisplayMode.Never);
        break;
    case LargeTitleDisplayMode.Never:
        On<iOS>().SetLargeTitleDisplay(LargeTitleDisplayMode.Always);
        break;
}

The result is that a specified LargeTitleDisplayMode is applied to the Page, which controls the large title behavior:

Enabling the Safe Area Layout Guide

This platform-specific is used to ensure that page content is positioned on an area of the screen that is safe for all devices that use iOS 11 and greater. Specifically, it will help to make sure that content isn't clipped by rounded device corners, the home indicator, or the sensor housing on an iPhone X. It's consumed in XAML by setting the Page.UseSafeArea attached property to a boolean value:

<ContentPage ...
             xmlns:ios="clr-namespace:Xamarin.Forms.PlatformConfiguration.iOSSpecific;assembly=Xamarin.Forms.Core"
             Title="Safe Area"
             ios:Page.UseSafeArea="true">
    <StackLayout>
        ...
    </StackLayout>
</ContentPage>

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

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

On<iOS>().SetUseSafeArea(true);

The Page.On<iOS> method specifies that this platform-specific will only run on iOS. The Page.SetUseSafeArea method, in the Xamarin.Forms.PlatformConfiguration.iOSSpecific namespace, controls whether the safe area layout guide is enabled.

The result is that page content can be positioned on an area of the screen that is safe for all iPhones:

ℹ️

Note: The safe area defined by Apple is used in Xamarin.Forms to set the Page.Padding property, and will override any previous values of this property that have been set.

The safe area can be customized by retrieving its Thickness value with the Page.SafeAreaInsets method from the Xamarin.Forms.PlatformConfiguration.iOSSpecific namespace. It can then be modified as required and re-assigned to the Padding property in the page constructor or OnAppearing override:

protected override void OnAppearing()
{
    base.OnAppearing();

    var safeInsets = On<iOS>().SafeAreaInsets();
    safeInsets.Left = 20;
    Padding = safeInsets;
}

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:

Adjusting the Status Bar Text Color Mode

This platform-specific controls whether the status bar text color on a NavigationPage is adjusted to match the luminosity of the navigation bar. It's consumed in XAML by setting the NavigationPage.StatusBarTextColorMode attached property to a value of the StatusBarTextColorMode enumeration:

<MasterDetailPage xmlns="http://xamarin.com/schemas/2014/forms"
    xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
    xmlns:ios="clr-namespace:Xamarin.Forms.PlatformConfiguration.iOSSpecific;assembly=Xamarin.Forms.Core"
    x:Class="PlatformSpecifics.iOSStatusBarTextColorModePage">
    <MasterDetailPage.Master>
        <ContentPage Title="Master Page Title" />
    </MasterDetailPage.Master>
    <MasterDetailPage.Detail>
        <NavigationPage BarBackgroundColor="Blue" BarTextColor="White"
                        ios:NavigationPage.StatusBarTextColorMode="MatchNavigationBarTextLuminosity">
            <x:Arguments>
                <ContentPage>
                    <Label Text="Slide the master page to see the status bar text color mode change." />
                </ContentPage>
            </x:Arguments>
        </NavigationPage>
    </MasterDetailPage.Detail>
</MasterDetailPage>

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

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

IsPresentedChanged += (sender, e) =>
{
    var mdp = sender as MasterDetailPage;
    if (mdp.IsPresented)
        ((Xamarin.Forms.NavigationPage)mdp.Detail)
          .On<iOS>()
          .SetStatusBarTextColorMode(StatusBarTextColorMode.DoNotAdjust);
    else
        ((Xamarin.Forms.NavigationPage)mdp.Detail)
          .On<iOS>()
          .SetStatusBarTextColorMode(StatusBarTextColorMode.MatchNavigationBarTextLuminosity);
};

The NavigationPage.On<iOS> method specifies that this platform-specific will only run on iOS. The NavigationPage.SetStatusBarTextColorMode method, in the Xamarin.Forms.PlatformConfiguration.iOSSpecific namespace, controls whether the status bar text color on the NavigationPage is adjusted to match the luminosity of the navigation bar, with the StatusBarTextColorMode enumeration providing two possible values:

In addition, the GetStatusBarTextColorMode method can be used to retrieve the current value of the StatusBarTextColorMode enumeration that's applied to the NavigationPage.

The result is that the status bar text color on a NavigationPage can be adjusted to match the luminosity of the navigation bar. In this example, the status bar text color changes as the user switches between the Master and Detail pages of a MasterDetailPage:

Adjusting the Font Size of an Entry

This platform-specific is used to scale the font size of an Entry to ensure that the inputted text fits in the control. It's consumed in XAML by setting the Entry.AdjustsFontSizeToFitWidth attached property to a boolean value:

<?xml version="1.0" encoding="UTF-8"?>
<ContentPage ...
             xmlns:ios="clr-namespace:Xamarin.Forms.PlatformConfiguration.iOSSpecific;assembly=Xamarin.Forms.Core"
    <StackLayout Margin="20">
        <Entry x:Name="entry"
               Placeholder="Enter text here to see the font size change"
               FontSize="22"
               ios:Entry.AdjustsFontSizeToFitWidth="true" />
        ...
    </StackLayout>
</ContentPage>

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

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

entry.On<iOS>().EnableAdjustsFontSizeToFitWidth();

The Entry.On<iOS> method specifies that this platform-specific will only run on iOS. The Entry.EnableAdjustsFontSizeToFitWidth method, in the Xamarin.Forms.PlatformConfiguration.iOSSpecific namespace, is used to scale the font size of the inputted text to ensure that it fits in the Entry. In addition, the Entry class in the Xamarin.Forms.PlatformConfiguration.iOSSpecific namespace also has a DisableAdjustsFontSizeToFitWidth method that disables this platform-specific, and a SetAdjustsFontSizeToFitWidth method which can be used to toggle font size scaling by calling the AdjustsFontSizeToFitWidth method:

entry.On<iOS>().SetAdjustsFontSizeToFitWidth(!entry.On<iOS>().AdjustsFontSizeToFitWidth());

The result is that the font size of the Entry is scaled to ensure that the inputted text fits in the control:

Controlling Picker Item Selection

This platform-specific controls when item selection occurs in a Picker, allowing the user to specify that item selection occurs when browsing items in the control, or only once the Done button is pressed. It's consumed in XAML by setting the Picker.UpdateMode attached property to a value of the UpdateMode enumeration:

<ContentPage ...
             xmlns:ios="clr-namespace:Xamarin.Forms.PlatformConfiguration.iOSSpecific;assembly=Xamarin.Forms.Core">
    <StackLayout Margin="20">
        <Picker ... Title="Select a monkey" ios:Picker.UpdateMode="WhenFinished">
          ...
        </Picker>
        ...
    </StackLayout>
</ContentPage>

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

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

picker.On<iOS>().SetUpdateMode(UpdateMode.WhenFinished);

The Picker.On<iOS> method specifies that this platform-specific will only run on iOS. The Picker.SetUpdateMode method, in the Xamarin.Forms.PlatformConfiguration.iOSSpecific namespace, is used to control when item selection occurs, with the UpdateMode enumeration providing two possible values:

  • Immediately – item selection occurs as the user browses items in the Picker. This is the default behavior in Xamarin.Forms.
  • WhenFinished – item selection only occurs once the user has pressed the Done button in the Picker.

In addition, the SetUpdateMode method can be used to toggle the enumeration values by calling the UpdateMode method, which returns the current UpdateMode:

switch (picker.On<iOS>().UpdateMode())
{
    case UpdateMode.Immediately:
        picker.On<iOS>().SetUpdateMode(UpdateMode.WhenFinished);
        break;
    case UpdateMode.WhenFinished:
        picker.On<iOS>().SetUpdateMode(UpdateMode.Immediately);
        break;
}

The result is that a specified UpdateMode is applied to the Picker, which controls when item selection occurs:

Setting the Status Bar Visibility on a Page

This platform-specific is used to set the visibility of the status bar on a Page, and it includes the ability to control how the status bar enters or leaves the Page. It's consumed in XAML by setting the Page.PrefersStatusBarHidden attached property to a value of the StatusBarHiddenMode enumeration, and optionally the Page.PreferredStatusBarUpdateAnimation attached property to a value of the UIStatusBarAnimation enumeration:

<?xml version="1.0" encoding="UTF-8"?>
<ContentPage ...
             xmlns:ios="clr-namespace:Xamarin.Forms.PlatformConfiguration.iOSSpecific;assembly=Xamarin.Forms.Core"
             ios:Page.PrefersStatusBarHidden="True"
             ios:Page.PreferredStatusBarUpdateAnimation="Fade">
  ...
</ContentPage>

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

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

On<iOS>().SetPrefersStatusBarHidden(StatusBarHiddenMode.True)
         .SetPreferredStatusBarUpdateAnimation(UIStatusBarAnimation.Fade);

The Page.On<iOS> method specifies that this platform-specific will only run on iOS. The Page.SetPrefersStatusBarHidden method, in the Xamarin.Forms.PlatformConfiguration.iOSSpecific namespace, is used to set the visibility of the status bar on a Page by specifying one of the StatusBarHiddenMode enumeration values: Default, True, or False. The StatusBarHiddenMode.True and StatusBarHiddenMode.False values set the status bar visibility regardless of device orientation, and the StatusBarHiddenMode.Default value hides the status bar in a vertically compact environment.

The result is that the visibility of the status bar on a Page can be set:

ℹ️

On a TabbedPage, the specified StatusBarHiddenMode enumeration value will also update the status bar on all child pages. On all other Page-derived types, the specified StatusBarHiddenMode enumeration value will only update the status bar on the current page.

The Page.SetPreferredStatusBarUpdateAnimation method is used to set how the status bar enters or leaves the Page by specifying one of the UIStatusBarAnimation enumeration values: None, Fade, or Slide. If the Fade or Slide enumeration value is specified, a 0.25 second animation executes as the status bar enters or leaves the Page.

Delaying Content Touches in a ScrollView

An implicit timer is triggered when a touch gesture begins in a ScrollView on iOS and the ScrollView decides, based on the user action within the timer span, whether it should handle the gesture or pass it to its content. By default, the iOS ScrollView delays content touches, but this can cause problems in some circumstances with the ScrollView content not winning the gesture when it should. Therefore, this platform-specific controls whether a ScrollView handles a touch gesture or passes it to its content. It's consumed in XAML by setting the ScrollView.ShouldDelayContentTouches attached property to a boolean value:

<MasterDetailPage ...
                  xmlns:ios="clr-namespace:Xamarin.Forms.PlatformConfiguration.iOSSpecific;assembly=Xamarin.Forms.Core">
    <MasterDetailPage.Master>
        <ContentPage Title="Menu" BackgroundColor="Blue" />
    </MasterDetailPage.Master>
    <MasterDetailPage.Detail>
        <ContentPage>
            <ScrollView x:Name="scrollView" ios:ScrollView.ShouldDelayContentTouches="false">
                <StackLayout Margin="0,20">
                    <Slider />
                    <Button Text="Toggle ScrollView DelayContentTouches" Clicked="OnButtonClicked" />
                </StackLayout>
            </ScrollView>
        </ContentPage>
    </MasterDetailPage.Detail>
</MasterDetailPage>

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

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

scrollView.On<iOS>().SetShouldDelayContentTouches(false);

The ScrollView.On<iOS> method specifies that this platform-specific will only run on iOS. The ScrollView.SetShouldDelayContentTouches method, in the Xamarin.Forms.PlatformConfiguration.iOSSpecific namespace, is used to control whether a ScrollView handles a touch gesture or passes it to its content. In addition, the SetShouldDelayContentTouches method can be used to toggle delaying content touches by calling the ShouldDelayContentTouches method to return whether content touches are delayed:

scrollView.On<iOS>().SetShouldDelayContentTouches(!scrollView.On<iOS>().ShouldDelayContentTouches());

The result is that a ScrollView can disable delaying receiving content touches, so that in this scenario the Slider receives the gesture rather than the Detail page of the MasterDetailPage:

Summary

This article demonstrated how to consume the iOS 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.