feat: StatusBar extensions (#265)

* feat: StatusBar extensions
* fix(ios): status bar padding

Co-authored-by: Jérôme Laban <jerome.laban@nventive.com>

doc/controls-styles.md

@@ -12,6 +12,7 @@ The `Uno.Toolkit.UI` library adds the following controls:
 The `Uno.Toolkit.UI` library adds the following helper classes:
 - `SystemThemeHelper`: Provides a set of helper methods to check the current operating system theme, and manipulate the application dark/light theme.
 - [`AncestorBinding` and `ItemsControlBinding`](helpers\ancestor-itemscontrol-binding.md): These markup extensions provides relative binding based on ancestor type. If you are familiar with WPF, they are very similar to `{RelativeSource Mode=FindAncestor}`.
+- [`StatusBar`](helpers\StatusBar-extensions.md): Provides two attached properties on `Page` to controls the visual of the status bar on mobile platforms.
 
 ## Control Styles
 Control|Style Key|IsDefaultStyle*|

doc/helpers/StatusBar-extensions.md

@@ -0,0 +1,24 @@
+# StatusBar Attached Properties
+Provides two attached properties on `Page` to controls the visual of the status bar on mobile platforms.
+
+## Remarks
+The attached properties do nothing on platforms other than iOS and Android.
+For iOS, `UIViewControllerBasedStatusBarAppearance` should set to false in `info.plist`.
+
+## Properties
+Property|Type|Description
+-|-|-
+Foreground|StatusBarForegroundTheme\*|Sets the foreground color for the text and icons on the status bar. Possible values are: `None, Light, Dark, Auto or AutoInverse`.
+Background|Brush|Sets the background color for the status bar. <br/> note: Due to platform limitations, only `SolidColorBrush`es are accepted.
+
+StatusBarForegroundTheme\*: `Auto` and `AutoInverse` will set the foreground in accordance to the theme, and update itself when the system theme or the app theme changes:
+- Auto: light/white in the dark mode, and dark/black in the light mode
+- AutoInverse: dark/black in the dark mode, and light/white in the light mode
+
+## Usage
+```xml
+<Page ...
+      xmlns:utu="using:Uno.Toolkit.UI"
+      utu:StatusBar.Foreground="Dark"
+      utu:StatusBar.Background="SkyBlue" />
+```

doc/toc.yml

@@ -27,6 +27,8 @@
     items:
     - name: AncestorBinding and ItemsControlBinding
       href: helpers/ancestor-itemscontrol-binding.md
+    - name: StatusBar attached properties
+      href: helpers/StatusBar-extensions.md
   # ***************** Styles **********************
   - name: Styles
     href: controls-styles.md

samples/Uno.Toolkit.Samples/Uno.Toolkit.Samples.Shared/Content/Controls/IExitNestedSampleHandler.cs

@@ -0,0 +1,27 @@
+using System;
+using System.Collections.Generic;
+using System.Text;
+
+#if IS_WINUI
+using Microsoft.UI.Xaml.Controls;
+using Microsoft.UI.Xaml.Navigation;
+#else
+using Windows.UI.Xaml.Controls;
+using Windows.UI.Xaml.Navigation;
+#endif
+
+namespace Uno.Toolkit.Samples.Content.Controls
+{
+	/// <summary>
+	/// Provides a mechanism to handle back navigation (<see cref="Shell.BackNavigateFromNestedSample"/>) that exited the nested sample.
+	/// </summary>
+	/// <remarks>
+	/// <see cref="Page.OnNavigatedTo(NavigationEventArgs)"/> will only work between pages of nested sample which uses frame navigation.
+	/// Between nested sample pages and content pages, it is based on a nested frame visibility.
+	/// Content pages navigation are based on navigation-view's not frame's.
+	/// </remarks>
+	public interface IExitNestedSampleHandler
+	{
+		void OnExitedFromNestedSample(object sender);
+	}
+}

samples/Uno.Toolkit.Samples/Uno.Toolkit.Samples.Shared/Content/Controls/StatusBarSamplePage.xaml

@@ -0,0 +1,21 @@
+<Page x:Class="Uno.Toolkit.Samples.Content.Controls.StatusBarSamplePage"
+	  xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
+	  xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
+	  xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
+	  xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
+	  xmlns:sample="using:Uno.Toolkit.Samples"
+	  xmlns:utu="using:Uno.Toolkit.UI"
+	  mc:Ignorable="d"
+	  Background="{ThemeResource ApplicationPageBackgroundThemeBrush}">
+
+	<sample:SamplePageLayout IsDesignAgnostic="True">
+		<sample:SamplePageLayout.DesignAgnosticTemplate>
+			<DataTemplate>
+				<StackPanel Margin="0,16,0,0">
+					<Button Content="Show Sample"
+							Click="ShowSample" />
+				</StackPanel>
+			</DataTemplate>
+		</sample:SamplePageLayout.DesignAgnosticTemplate>
+	</sample:SamplePageLayout>
+</Page>

samples/Uno.Toolkit.Samples/Uno.Toolkit.Samples.Shared/Content/Controls/StatusBarSamplePage.xaml.cs

@@ -0,0 +1,53 @@
+using System;
+using System.Collections.Generic;
+using System.IO;
+using System.Linq;
+using System.Runtime.InteropServices.WindowsRuntime;
+using Windows.Foundation;
+using Windows.Foundation.Collections;
+using Uno.Toolkit.Samples.Content.NestedSamples;
+using Uno.Toolkit.Samples.Entities;
+using Uno.Toolkit.UI;
+
+#if IS_WINUI
+using Microsoft.UI;
+using Microsoft.UI.Xaml;
+using Microsoft.UI.Xaml.Controls;
+using Microsoft.UI.Xaml.Controls.Primitives;
+using Microsoft.UI.Xaml.Data;
+using Microsoft.UI.Xaml.Input;
+using Microsoft.UI.Xaml.Media;
+using Microsoft.UI.Xaml.Navigation;
+#else
+using Windows.UI;
+using Windows.UI.Xaml;
+using Windows.UI.Xaml.Controls;
+using Windows.UI.Xaml.Controls.Primitives;
+using Windows.UI.Xaml.Data;
+using Windows.UI.Xaml.Input;
+using Windows.UI.Xaml.Media;
+using Windows.UI.Xaml.Navigation;
+#endif
+
+namespace Uno.Toolkit.Samples.Content.Controls
+{
+	[SamplePage(SampleCategory.Behaviors, nameof(Uno.Toolkit.UI.StatusBar), source: SourceSdk.UnoToolkit)]
+	public sealed partial class StatusBarSamplePage : Page, IExitNestedSampleHandler
+	{
+		public StatusBarSamplePage()
+		{
+			this.InitializeComponent();
+		}
+
+		public void OnExitedFromNestedSample(object sender)
+		{
+			StatusBar.SetForeground(StatusBarForegroundTheme.Light);
+			StatusBar.SetBackground(Colors.Gray);
+		}
+
+		private void ShowSample(object sender, RoutedEventArgs e)
+		{
+			Shell.GetForCurrentView().ShowNestedSample<StatusBarSample_NestedPage1>(clearStack: true);
+		}
+	}
+}

samples/Uno.Toolkit.Samples/Uno.Toolkit.Samples.Shared/Content/NestedSamples/StatusBarSample_NestedPage1.xaml

@@ -0,0 +1,45 @@
+<Page x:Class="Uno.Toolkit.Samples.Content.NestedSamples.StatusBarSample_NestedPage1"
+	  xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
+	  xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
+	  xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
+	  xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
+	  xmlns:utu="using:Uno.Toolkit.UI"
+	  mc:Ignorable="d"
+	  utu:StatusBar.Foreground="Light"
+	  utu:StatusBar.Background="DarkRed"
+	  Background="{ThemeResource ApplicationPageBackgroundThemeBrush}">
+
+	<Grid>
+		<Grid.RowDefinitions>
+			<RowDefinition Height="Auto" />
+			<RowDefinition Height="*" />
+		</Grid.RowDefinitions>
+
+		<utu:NavigationBar Grid.Row="0"
+						   Content="StatusBar NestedPage1"
+						   MainCommandMode="Action"
+						   Background="Blue"
+						   Style="{StaticResource MaterialNavigationBarStyle}">
+			<utu:NavigationBar.MainCommand>
+				<AppBarButton Label="Close"
+							  Click="NavigateBack"
+							  Style="{StaticResource MaterialAppBarButtonStyle}">
+					<AppBarButton.Icon>
+						<BitmapIcon UriSource="ms-appx:///Assets/CloseIcon.png" />
+					</AppBarButton.Icon>
+				</AppBarButton>
+			</utu:NavigationBar.MainCommand>
+		</utu:NavigationBar>
+
+		<StackPanel Grid.Row="1"
+					Padding="16"
+					Spacing="8">
+			<TextBlock Text="Light on DarkRed" />
+			<Button Content="Goto NextPage"
+					Click="NavigateToNextPage" />
+			<Button Content="Go Back"
+					Click="NavigateBack" />
+		</StackPanel>
+
+	</Grid>
+</Page>

samples/Uno.Toolkit.Samples/Uno.Toolkit.Samples.Shared/Content/NestedSamples/StatusBarSample_NestedPage1.xaml.cs

@@ -0,0 +1,41 @@
+using System;
+using System.Collections.Generic;
+using System.IO;
+using System.Linq;
+using System.Runtime.InteropServices.WindowsRuntime;
+using Windows.Foundation;
+using Windows.Foundation.Collections;
+
+#if IS_WINUI
+using Microsoft.UI.Xaml;
+using Microsoft.UI.Xaml.Controls;
+using Microsoft.UI.Xaml.Controls.Primitives;
+using Microsoft.UI.Xaml.Data;
+using Microsoft.UI.Xaml.Input;
+using Microsoft.UI.Xaml.Media;
+using Microsoft.UI.Xaml.Navigation;
+#else
+using Windows.UI.Xaml;
+using Windows.UI.Xaml.Controls;
+using Windows.UI.Xaml.Controls.Primitives;
+using Windows.UI.Xaml.Data;
+using Windows.UI.Xaml.Input;
+using Windows.UI.Xaml.Media;
+using Windows.UI.Xaml.Navigation;
+#endif
+
+
+namespace Uno.Toolkit.Samples.Content.NestedSamples
+{
+	public sealed partial class StatusBarSample_NestedPage1 : Page
+	{
+		public StatusBarSample_NestedPage1()
+		{
+			this.InitializeComponent();
+		}
+
+		private void NavigateBack(object sender, RoutedEventArgs e) => Shell.GetForCurrentView().BackNavigateFromNestedSample();
+
+		private void NavigateToNextPage(object sender, RoutedEventArgs e) => Frame.Navigate(typeof(StatusBarSample_NestedPage2));
+	}
+}

samples/Uno.Toolkit.Samples/Uno.Toolkit.Samples.Shared/Content/NestedSamples/StatusBarSample_NestedPage2.xaml

@@ -0,0 +1,43 @@
+<Page x:Class="Uno.Toolkit.Samples.Content.NestedSamples.StatusBarSample_NestedPage2"
+	  xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
+	  xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
+	  xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
+	  xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
+	  xmlns:utu="using:Uno.Toolkit.UI"
+	  mc:Ignorable="d"
+	  utu:StatusBar.Foreground="Dark"
+	  utu:StatusBar.Background="SkyBlue"
+	  Background="{ThemeResource ApplicationPageBackgroundThemeBrush}">
+
+	<Grid>
+		<Grid.RowDefinitions>
+			<RowDefinition Height="Auto" />
+			<RowDefinition Height="*" />
+		</Grid.RowDefinitions>
+
+		<utu:NavigationBar Grid.Row="0"
+						   Content="Second Page"
+						   MainCommandMode="Back"
+						   Background="Blue"
+						   Style="{StaticResource MaterialNavigationBarStyle}">
+			<utu:NavigationBar.MainCommand>
+				<AppBarButton Label="Back"
+							  Click="NavigateBack"
+							  Style="{StaticResource MaterialAppBarButtonStyle}">
+					<AppBarButton.Icon>
+						<BitmapIcon UriSource="ms-appx:///Assets/BackButton.png" />
+					</AppBarButton.Icon>
+				</AppBarButton>
+			</utu:NavigationBar.MainCommand>
+		</utu:NavigationBar>
+
+		<StackPanel Grid.Row="1"
+					Padding="16"
+					Spacing="8">
+			<TextBlock Text="Dark on SkyBlue" />
+			<Button Content="Go Back"
+					Click="NavigateBack" />
+		</StackPanel>
+
+	</Grid>
+</Page>

samples/Uno.Toolkit.Samples/Uno.Toolkit.Samples.Shared/Content/NestedSamples/StatusBarSample_NestedPage2.xaml.cs

@@ -0,0 +1,38 @@
+using System;
+using System.Collections.Generic;
+using System.IO;
+using System.Linq;
+using System.Runtime.InteropServices.WindowsRuntime;
+using Windows.Foundation;
+using Windows.Foundation.Collections;
+
+#if IS_WINUI
+using Microsoft.UI.Xaml;
+using Microsoft.UI.Xaml.Controls;
+using Microsoft.UI.Xaml.Controls.Primitives;
+using Microsoft.UI.Xaml.Data;
+using Microsoft.UI.Xaml.Input;
+using Microsoft.UI.Xaml.Media;
+using Microsoft.UI.Xaml.Navigation;
+#else
+using Windows.UI.Xaml;
+using Windows.UI.Xaml.Controls;
+using Windows.UI.Xaml.Controls.Primitives;
+using Windows.UI.Xaml.Data;
+using Windows.UI.Xaml.Input;
+using Windows.UI.Xaml.Media;
+using Windows.UI.Xaml.Navigation;
+#endif
+
+namespace Uno.Toolkit.Samples.Content.NestedSamples
+{
+	public sealed partial class StatusBarSample_NestedPage2 : Page
+	{
+		public StatusBarSample_NestedPage2()
+		{
+			this.InitializeComponent();
+		}
+
+		private void NavigateBack(object sender, RoutedEventArgs e) => Frame.GoBack();
+	}
+}

samples/Uno.Toolkit.Samples/Uno.Toolkit.Samples.Shared/Entities/SourceSdk.cs

@@ -15,5 +15,7 @@ public enum SourceSdk
 		UnoMaterial,
 		[Description("Uno.Cupertino")]
 		UnoCupertino,
+		[Description("Uno.Toolkit")]
+		UnoToolkit,
 	}
 }

samples/Uno.Toolkit.Samples/Uno.Toolkit.Samples.Shared/Shell.xaml.cs

@@ -3,6 +3,7 @@
 using System.Threading.Tasks;
 using Uno.Toolkit.Samples.Content.NestedSamples;
 using Uno.Toolkit.UI;
+using Uno.Toolkit.Samples.Content.Controls;
 
 
 #if IS_WINUI
@@ -39,7 +40,8 @@ public Shell()
 
 			InitializeSafeArea();
 			this.Loaded += OnLoaded;
-
+			this.SizeChanged += (s, e) => InitializeSafeArea();
+
 			NestedSampleFrame.RegisterPropertyChangedCallback(ContentControl.ContentProperty, OnNestedSampleFrameChanged);
 
 #if !IS_WINUI
@@ -149,6 +151,7 @@ public bool BackNavigateFromNestedSample()
 				return false;
 			}
 
+			var sender = NestedSampleFrame.Content;
 			if (NestedSampleFrame.CanGoBack)
 			{
 				//Let the NavigationBar within the nested page handle the back nav logic
@@ -171,6 +174,14 @@ public bool BackNavigateFromNestedSample()
 #endif
 			}
 
+			if (NavigationView.Content is IExitNestedSampleHandler handler)
+			{
+				// Allows the page to be able to handle back navigation that exited nested sample.
+				// There is no other ways of knowing this, since this "navigation" effectively
+				// just changes the visibility of the nested frame that overlays everything.
+				handler.OnExitedFromNestedSample(sender);
+			}
+
 			return true;
 		}