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

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:

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

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.

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.