iOS Platform-Specifics

Download Sample Download the sample

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.

VisualElements

On iOS, the following platform-specific functionality is provided for Xamarin.Forms views, pages, and layouts:

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:

Note

When adding a blur effect to a VisualElement, touch events will still be received by the VisualElement.

Disabling Legacy Color Mode

Some of the Xamarin.Forms views feature a legacy color mode. In this mode, when the IsEnabled property of the view is set to false, the view will override the colors set by the user with the default native colors for the disabled state. For backwards compatibility, this legacy color mode remains the default behavior for supported views.

This platform-specific disables this legacy color mode, so that colors set on a view by the user remain even when the view is disabled. It's consumed in XAML by setting the VisualElement.IsLegacyColorModeEnabled attached property to false:

<ContentPage ...
             xmlns:ios="clr-namespace:Xamarin.Forms.PlatformConfiguration.iOSSpecific;assembly=Xamarin.Forms.Core">
    <StackLayout>
        ...
        <Button Text="Button"
                TextColor="Blue"
                BackgroundColor="Bisque"
                ios:VisualElement.IsLegacyColorModeEnabled="False" />
        ...
    </StackLayout>
</ContentPage>

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

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

_legacyColorModeDisabledButton.On<iOS>().SetIsLegacyColorModeEnabled(false);

The VisualElement.On<iOS> method specifies that this platform-specific will only run on iOS. The VisualElement.SetIsLegacyColorModeEnabled method, in the Xamarin.Forms.PlatformConfiguration.iOSSpecific namespace, is used to control whether the legacy color mode is disabled. In addition, the VisualElement.GetIsLegacyColorModeEnabled method can be used to return whether the legacy color mode is disabled.

The result is that the legacy color mode can be disabled, so that colors set on a view by the user remain even when the view is disabled:

Note

When setting a VisualStateGroup on a view, the legacy color mode is completely ignored. For more information about visual states, see The Xamarin.Forms Visual State Manager.

Enabling a Drop Shadow

This platform-specific is used to enable a drop shadow on a VisualElement. It's consumed in XAML by setting the VisualElement.IsShadowEnabled attached property to true, along with a number of additional optional attached properties that control the drop shadow:

<ContentPage ...
             xmlns:ios="clr-namespace:Xamarin.Forms.PlatformConfiguration.iOSSpecific;assembly=Xamarin.Forms.Core">
    <StackLayout Margin="20">
        <BoxView ...
                 ios:VisualElement.IsShadowEnabled="true"
                 ios:VisualElement.ShadowColor="Purple"
                 ios:VisualElement.ShadowOpacity="0.7"
                 ios:VisualElement.ShadowRadius="12">
            <ios:VisualElement.ShadowOffset>
                <Size>
                    <x:Arguments>
                        <x:Double>10</x:Double>
                        <x:Double>10</x:Double>
                    </x:Arguments>
                </Size>
            </ios:VisualElement.ShadowOffset>
         </BoxView>
        ...
    </StackLayout>
</ContentPage>

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

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

var boxView = new BoxView { Color = Color.Aqua, WidthRequest = 100, HeightRequest = 100 };
boxView.On<iOS>()
       .SetIsShadowEnabled(true)
       .SetShadowColor(Color.Purple)
       .SetShadowOffset(new Size(10,10))
       .SetShadowOpacity(0.7)
       .SetShadowRadius(12);

The VisualElement.On<iOS> method specifies that this platform-specific will only run on iOS. The VisualElement.SetIsShadowEnabled method, in the Xamarin.Forms.PlatformConfiguration.iOSSpecific namespace, is used to control whether a drop shadow is enabled on the VisualElement. In addition, the following methods can be invoked to control the drop shadow:

  • SetShadowColor – sets the color of the drop shadow. The default color is Color.Default.
  • SetShadowOffset – sets the offset of the drop shadow. The offset changes the direction the shadow is cast, and is specified as a Size value. The Size structure values are expressed in device-independent units, with the first value being the distance to the left (negative value) or right (positive value), and the second value being the distance above (negative value) or below (positive value). The default value of this property is (0.0, 0.0), which results in the shadow being cast around every side of the VisualElement.
  • SetShadowOpacity – sets the opacity of the drop shadow, with the value being in the range 0.0 (transparent) to 1.0 (opaque). The default opacity value is 0.5.
  • SetShadowRadius – sets the blur radius used to render the drop shadow. The default radius value is 10.0.

Note

The state of a drop shadow can be queried by calling the GetIsShadowEnabled, GetShadowColor, GetShadowOffset, GetShadowOpacity, and GetShadowRadius methods.

The result is that a drop shadow can be enabled on a VisualElement:

Views

On iOS, the following platform-specific functionality is provided for Xamarin.Forms views:

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:

<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:

Setting the Entry Cursor Color

This platform-specific sets the cursor color in an Entry to a specified color. It's consumed in XAML by setting the Entry.CursorColor bindable property to a Color:

<ContentPage ...
             xmlns:ios="clr-namespace:Xamarin.Forms.PlatformConfiguration.iOSSpecific;assembly=Xamarin.Forms.Core">
	<StackLayout>
		<Entry ... ios:Entry.CursorColor="LimeGreen" />
	</StackLayout>
</ContentPage>

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

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

var entry = new Xamarin.Forms.Entry();
entry.On<iOS>().SetCursorColor(Color.LimeGreen);

The Entry.On<iOS> method specifies that this platform-specific will only run on iOS. The Entry.SetCursorColor method, in the Xamarin.Forms.PlatformConfiguration.iOSSpecific namespace, sets the cursor color to a specified Color. In addition, the Entry.GetCursorColor method can be used to retrieve the current cursor color.

The result is that the cursor color in a Entry can be set to a specific Color:

Setting the Separator Style on a ListView

This platform-specific controls whether the separator between cells in a ListView uses the full width of the ListView. It's consumed in XAML by setting the ListView.SeparatorStyle attached property to a value of the SeparatorStyle enumeration:

<ContentPage ...
             xmlns:ios="clr-namespace:Xamarin.Forms.PlatformConfiguration.iOSSpecific;assembly=Xamarin.Forms.Core">
    <StackLayout Margin="20">
        <ListView ... ios:ListView.SeparatorStyle="FullWidth">
            ...
        </ListView>
    </StackLayout>
</ContentPage>

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

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

listView.On<iOS>().SetSeparatorStyle(SeparatorStyle.FullWidth);

The ListView.On<iOS> method specifies that this platform-specific will only run on iOS. The ListView.SetSeparatorStyle method, in the Xamarin.Forms.PlatformConfiguration.iOSSpecific namespace, is used to control whether the separator between cells in the ListView uses the full width of the ListView, with the SeparatorStyle enumeration providing two possible values:

  • Default – indicates the default iOS separator behavior. This is the default behavior in Xamarin.Forms.
  • FullWidth – indicates that separators will be drawn from one edge of the ListView to the other.

The result is that a specified SeparatorStyle value is applied to the ListView, which controls the width of the separator between cells:

Note

Once the separator style has been set to FullWidth, it cannot be changed back to Default at runtime.

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:

Enabling a Slider Thumb to Move on Tap

This platform-specific enables the Slider.Value property to be set by tapping on a position on the Slider bar, rather than by having to drag the Slider thumb. It's consumed in XAML by setting the Slider.UpdateOnTap bindable property to true:

<ContentPage ...
             xmlns:ios="clr-namespace:Xamarin.Forms.PlatformConfiguration.iOSSpecific;assembly=Xamarin.Forms.Core">
    <StackLayout ...>
        <Slider ... ios:Slider.UpdateOnTap="true" />
        ...
    </StackLayout>
</ContentPage>

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

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

var slider = new Xamarin.Forms.Slider();
slider.On<iOS>().SetUpdateOnTap(true);

The Slider.On<iOS> method specifies that this platform-specific will only run on iOS. The Slider.SetUpdateOnTap method, in the Xamarin.Forms.PlatformConfiguration.iOSSpecific namespace, is used to control whether a tap on the Slider bar will set the Slider.Value property. In addition, the Slider.GetUpdateOnTap method can be used to return whether a tap on the Slider bar will set the Slider.Value property.

The result is that a tap on the Slider bar can move the Slider thumb and set the Slider.Value property:

Pages

On iOS, the following platform-specific functionality is provided for Xamarin.Forms pages:

Hiding the Navigation Bar Separator on a NavigationPage

This platform-specific hides the separator line and shadow that is at the bottom of the navigation bar on a NavigationPage. It's consumed in XAML by setting the NavigationPage.HideNavigationBarSeparator bindable property to false:

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

</NavigationPage>

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

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

public class iOSTitleViewNavigationPageCS : Xamarin.Forms.NavigationPage
{
    public iOSTitleViewNavigationPageCS()
    {
        On<iOS>().SetHideNavigationBarSeparator(true);
    }
}

The NavigationPage.On<iOS> method specifies that this platform-specific will only run on iOS. The NavigationPage.SetHideNavigationBarSeparator method, in the Xamarin.Forms.PlatformConfiguration.iOSSpecific namespace, is used to control whether the navigation bar separator is hidden. In addition, the NavigationPage.HideNavigationBarSeparator method can be used to return whether the navigation bar separator is hidden.

The result is that the navigation bar separator on a NavigationPage can be hidden:

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:

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:

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:

<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:

Note

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.

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;
}

Setting the Modal Page Presentation Style on an iPad

This platform-specific is used to set the presentation style of a modal page on an iPad. It's consumed in XAML by setting the Page.ModalPresentationStyle bindable property to a UIModalPresentationStyle enumeration value:

<ContentPage ...
             xmlns:ios="clr-namespace:Xamarin.Forms.PlatformConfiguration.iOSSpecific;assembly=Xamarin.Forms.Core"
             ios:Page.ModalPresentationStyle="FormSheet">
    ...
</ContentPage>

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

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

public class iOSModalFormSheetPageCS : ContentPage
{
    public iOSModalFormSheetPageCS()
    {
        On<iOS>().SetModalPresentationStyle(UIModalPresentationStyle.FormSheet);
        ...
    }
}

The Page.On<iOS> method specifies that this platform-specific will only run on iOS. The Page.SetModalPresentationStyle method, in the Xamarin.Forms.PlatformConfiguration.iOSSpecific namespace, is used to set the modal presentation style on a Page by specifying one of the following UIModalPresentationStyle enumeration values:

  • FullScreen, which sets the modal presentation style to encompass the whole screen. By default, modal pages are displayed using this presentation style.
  • FormSheet, which sets the modal presentation style to be centered on and smaller than the screen.

In addition, the GetModalPresentationStyle method can be used to retrieve the current value of the UIModalPresentationStyle enumeration that's applied to the Page.

The result is that the modal presentation style on a Page can be set:

Note

Pages that use this platform-specific to set the modal presentation style must use modal navigation. For more information, see Xamarin.Forms Modal Pages.

Layouts

On iOS, the following platform-specific functionality is provided for Xamarin.Forms layouts:

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:

Application

On iOS, the following platform-specific functionality is provided for the Xamarin.Forms Application class:

Handling Control Updates on the Main Thread

This platform-specific enables control layout and rendering updates to be performed on the main thread, instead of being performed on a background thread. It should be rarely needed, but in some cases may prevent crashes. Its consumed in XAML by setting the Application.HandleControlUpdatesOnMainThread bindable property to true:

<Application ...
             xmlns:ios="clr-namespace:Xamarin.Forms.PlatformConfiguration.iOSSpecific;assembly=Xamarin.Forms.Core"
             ios:Application.HandleControlUpdatesOnMainThread="true">
	...
</Application>

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

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

Xamarin.Forms.Application.Current.On<iOS>().SetHandleControlUpdatesOnMainThread(true);

The Application.On<iOS> method specifies that this platform-specific will only run on iOS. The Application.SetHandleControlUpdatesOnMainThread method, in the Xamarin.Forms.PlatformConfiguration.iOSSpecific namespace, is used to control whether control layout and rendering updates are performed on the main thread, instead of being performed on a background thread. In addition, the Application.GetHandleControlUpdatesOnMainThread method can be used to return whether control layout and rendering updates are being performed on the main thread.

Enabling Simultaneous Pan Gesture Recognition

When a PanGestureRecognizer is attached to a view inside a scrolling view, all of the pan gestures are captured by the PanGestureRecognizer and aren't passed to the scrolling view. Therefore, the scrolling view will no longer scroll.

This platform-specific enables a PanGestureRecognizer in a scrolling view to capture and share the pan gesture with the scrolling view. It's consumed in XAML by setting the Application.PanGestureRecognizerShouldRecognizeSimultaneously attached property to true:

<Application ...
             xmlns:ios="clr-namespace:Xamarin.Forms.PlatformConfiguration.iOSSpecific;assembly=Xamarin.Forms.Core"
             ios:Application.PanGestureRecognizerShouldRecognizeSimultaneously="true">
	...
</Application>

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

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

Xamarin.Forms.Application.Current.On<iOS>().SetPanGestureRecognizerShouldRecognizeSimultaneously(true);

The Application.On<iOS> method specifies that this platform-specific will only run on iOS. The Application.SetPanGestureRecognizerShouldRecognizeSimultaneously method, in the Xamarin.Forms.PlatformConfiguration.iOSSpecific namespace, is used to control whether a pan gesture recognizer in a scrolling view will capture the pan gesture, or capture and share the pan gesture with the scrolling view. In addition, the Application.GetPanGestureRecognizerShouldRecognizeSimultaneously method can be used to return whether the pan gesture is shared with the scrolling view that contains the PanGestureRecognizer.

Therefore, with this platform-specific enabled, when a ListView contains a PanGestureRecognizer, both the ListView and the PanGestureRecognizer will receive the pan gesture and process it. However, with this platform-specific disabled, when a ListView contains a PanGestureRecognizer, the PanGestureRecognizer will capture the pan gesture and process it, and the ListView won't receive the pan gesture.

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.