diff --git a/doc/controls/AutoLayoutControl.md b/doc/controls/AutoLayoutControl.md index cb72801af..a8c9c0b5d 100644 --- a/doc/controls/AutoLayoutControl.md +++ b/doc/controls/AutoLayoutControl.md @@ -17,16 +17,26 @@ uid: Toolkit.Controls.AutoLayoutControl public partial class AutoLayout : Control ``` -### XAML +### Usage +# [**XAML**](#tab/xaml) ```xml xmlns:utu="using:Uno.Toolkit.UI" ... - - contents + ``` +# [**C#**](#tab/csharp) +```cs +using Uno.Toolkit.UI; +... +new AutoLayout() + .Children( + // Content + ) +``` +*** ### Inheritance diff --git a/doc/controls/CardAndCardContentControl.md b/doc/controls/CardAndCardContentControl.md index c76e80b6b..76deb9af8 100644 --- a/doc/controls/CardAndCardContentControl.md +++ b/doc/controls/CardAndCardContentControl.md @@ -66,26 +66,49 @@ The Card control comes with all the built-in properties of a `Control`, and also > Consider using [CardContentControl](#cardcontentcontrol) if you need full control over the content layout. ### Usage +# [**XAML**](#tab/xaml) ```xml xmlns:utu="using:Uno.Toolkit.UI" ... + SubHeaderContent="With title and subtitle" + Style="{StaticResource ElevatedCardStyle}" /> + SubHeaderContent="With title and subtitle" + Style="{StaticResource FilledCardStyle}" /> + SubHeaderContent="With title and subtitle" + Style="{StaticResource OutlinedCardStyle}" /> ``` +# [**C#**](#tab/csharp) +```cs +using Uno.Toolkit.UI.Markup; + +// ElevatedCardStyle +new Card() + .HeaderContent("Elevated card") + .SubHeaderContent("With title and subtitle") + .Style(Theme.Card.Styles.Elevated), +// FilledCardStyle +new Card() + .HeaderContent("Elevated card") + .SubHeaderContent("With title and subtitle") + .Style(Theme.Card.Styles.Filled), +// OutlinedCardStyle +new Card() + .HeaderContent("Elevated card") + .SubHeaderContent("With title and subtitle") + .Style(Theme.Card.Styles.Outlined) +``` +*** + ### Examples ![](../assets/card-samples.png) @@ -134,7 +157,9 @@ The `CardContentControl` is based on `ContentControl` and allows you to customiz public partial class CardContentControl : ContentControl ``` -### XAML +### Usage + +# [**XAML**](#tab/xaml) ```xml xmlns:utu="using:Uno.Toolkit.UI" ... @@ -144,12 +169,24 @@ xmlns:utu="using:Uno.Toolkit.UI" - content + ``` +# [**C#**](#tab/csharp) +```cs +new CardContentControl() +... + +new CardContentControl() + .ContentTemplate(() => + // Content + ) +``` +*** + ### Inheritance Object → DependencyObject → UIElement → FrameworkElement → Control → ContentControl → CardContentControl @@ -168,6 +205,7 @@ The Card control comes with all the built-in properties of a `ContentControl`, a | IsClickable | bool | Gets or sets a value indicating whether the control will respond to pointer and focus events. | ### Usage +# [**XAML**](#tab/xaml) ```xml xmlns:utu="using:Uno.Toolkit.UI" ... @@ -205,7 +243,46 @@ xmlns:utu="using:Uno.Toolkit.UI" ``` - +# [**C#**](#tab/csharp) +```cs +// ElevatedCardContentControlStyle +new CardContentControl() + .Style(Theme.CardContentControl.Styles.Elevated) + .ContentTemplate(() => + new Grid() + .Children( + new TextBlock() + .Text("Elevated card") + .MaxLines(1) + .Style(Theme.TextBlock.Styles.HeadlineMedium) + ) + ), + // FilledCardContentControlStyle +new CardContentControl() + .Style(Theme.CardContentControl.Styles.Filled) + .ContentTemplate(() => + new Grid() + .Children( + new TextBlock() + .Text("Filled card") + .MaxLines(1) + .Style(Theme.TextBlock.Styles.HeadlineMedium) + ) + ), +//OutlinedCardContentControlStyle +new CardContentControl() + .Style(Theme.CardContentControl.Styles.Outlined) + .ContentTemplate(() => + new Grid() + .Children( + new TextBlock() + .Text("Outlined card") + .MaxLines(1) + .Style(Theme.TextBlock.Styles.HeadlineMedium) + ) + ) +``` +*** ### Examples ![](../assets/cardcontentcontrol-samples.png) diff --git a/doc/controls/ChipAndChipGroup.md b/doc/controls/ChipAndChipGroup.md index 58af55a97..6c1a9179b 100644 --- a/doc/controls/ChipAndChipGroup.md +++ b/doc/controls/ChipAndChipGroup.md @@ -62,6 +62,7 @@ sealed class ChipRemovingEventArgs : EventArgs ``` ### Usage +# [**XAML**](#tab/xaml) ```xml xmlns:utu="using:Uno.Toolkit.UI" ... @@ -71,14 +72,38 @@ xmlns:utu="using:Uno.Toolkit.UI" - + ``` - +# [**C#**](#tab/csharp) +```cs +new Chip() + .Content("Assist Chip") + .Style(Theme.Chip.Styles.Assist), +new Chip() + .Content("Input Chip") + .Style(Theme.Chip.Styles.Input), +new Chip() + .Content("Filter Chip") + .Style(Theme.Chip.Styles.Filter), +new Chip() + .Content("Suggestion Chip") + .Style(Theme.Chip.Styles.Suggestion), + +// With icon +new Chip() + .Content("Chip") + .Style(Theme.Chip.Styles.Default) + .Icon( + new Image() + .Source("ms-appx:///Assets/Avatar.png") + ) +``` +*** ## Lightweight Styling Key|Type|Value @@ -162,7 +187,8 @@ ElevatedChipBackground|SolidColorBrush|SurfaceBrush public partial class ChipGroup : ItemsControl ``` -### XAML +### Usage +# [**XAML**](#tab/xaml) ```xml xmlns:utu="using:Uno.Toolkit.UI" ... @@ -170,10 +196,20 @@ xmlns:utu="using:Uno.Toolkit.UI" -or- - oneOrMoreItems + ``` +# [**C#**](#tab/csharp) +```cs +new ChipGroup() +... +new ChipGroup() + .Items( + // One or more Items + ) +``` +*** ### Inheritance Object → DependencyObject → UIElement → FrameworkElement → Control → ItemsControl → ChipGroup @@ -226,7 +262,8 @@ class ChipItemRemovingEventHandler : ChipItemEventHandler } ``` -### Usage +#### Usage +# [**XAML**](#tab/xaml) ```xml xmlns:utu="using:Uno.Toolkit.UI" ... @@ -258,3 +295,31 @@ xmlns:utu="using:Uno.Toolkit.UI" SelectionMode="Multiple" Style="{StaticResource SuggestionChipGroupStyle}" /> ``` +# [**C#**](#tab/csharp) +```cs +// example with binding +new ChipGroup() + .ItemsSource(() => vm.ChipsList) + .Style(Theme.ChipGroup.Styles.Suggestion) + .ItemTemplate(item => new TextBlock() + .Text(() => item.Name) + ), + +// single selection with binding +new ChipGroup() + .ItemsSource(() => vm.ChipsList) + .SelectedItem(x => x.Bind(() => vm.SelectedItem).TwoWay()) + .SelectionMode(ChipSelectionMode.Single) + .Style(Theme.ChipGroup.Styles.Suggestion), + +// multi-selection with binding +new ChipGroup() + .ItemsSource(() => vm.ChipsList) + .SelectedItems(x => x.Bind(() => vm.SelectedItems).TwoWay()) + .SelectionMode(ChipSelectionMode.Multiple) + .Style(Theme.ChipGroup.Styles.Suggestion) +``` + +> [!IMPORTANT] +> ItemClick Event are currently not supported in C# Markup. +*** \ No newline at end of file diff --git a/doc/controls/Divider.md b/doc/controls/Divider.md index 9be27375e..277e2f2ca 100644 --- a/doc/controls/Divider.md +++ b/doc/controls/Divider.md @@ -24,6 +24,7 @@ DividerSubHeaderMargin|Thickness|0,4,0,0 DividerHeight|Double|1 ## Usage +# [**XAML**](#tab/xaml) ```xml xmlns:utu="using:Uno.Toolkit.UI" ... @@ -36,3 +37,16 @@ xmlns:utu="using:Uno.Toolkit.UI" SubHeaderForeground="Black" /> ``` +# [**C#**](#tab/csharp) +```cs +new TextBlock() + .Text("Asd"), +new Divider(), +new TextBlock() + .Text("Asd"), +new Divider() + .Foreground(Colors.Gray) + .SubHeader("Separator") + .SubHeaderForeground(Colors.Black) +``` +*** \ No newline at end of file diff --git a/doc/controls/DrawerControl.md b/doc/controls/DrawerControl.md index ead54866d..4c56a7da1 100644 --- a/doc/controls/DrawerControl.md +++ b/doc/controls/DrawerControl.md @@ -17,20 +17,32 @@ Due to the lack of clipping, this control should be used as a full window-sized public partial class DrawerControl : ContentControl ``` -### XAML +### Usage +# [**XAML**](#tab/xaml) ```xml xmlns:utu="using:Uno.Toolkit.UI" ... - content + - drawerContent + ``` +# [**C#**](#tab/csharp) +```cs +new DrawerControl() + .Content( + // content + ) + .DrawerContent( + // drawerContent + ) +``` +*** ### Inheritance Object → DependencyObject → UIElement → FrameworkElement → Control → ContentControl → DrawerControl @@ -55,6 +67,7 @@ OpenDirection|DrawerOpenDirection=Right|Gets or sets the direction in which the ### Usage #### Basic usage +# [**XAML**](#tab/xaml) ```xml xmlns:toolkit="using:Uno.UI.Toolkit" xmlns:utu="using:Uno.Toolkit.UI" @@ -68,15 +81,34 @@ xmlns:utu="using:Uno.Toolkit.UI" - + ``` - +# [**C#**](#tab/csharp) +```cs +new DrawerControl() + .Content( + // Main Content ... + new Frame() + ) + .DrawerContent( + new Grid() + .VisibleBoundsPadding(PaddingMask.All) + .Padding(16) + .Children( + // DrawerControl ... + new TextBlock() + .Text("Drawer") + ) + ) +``` +*** #### NavigationView with drawer The `DrawerControl` can also be used to enhance [`NavigationView` (muxc)](https://docs.microsoft.com/en-us/windows/winui/api/microsoft.ui.xaml.controls.navigationview?view=winui-3.0) with gesture support, using the `DrawerNavigationViewStyle`: +# [**XAML**](#tab/xaml) ```xml xmlns:utu="using:Uno.Toolkit.UI" xmlns:muxc="using:Microsoft.UI.Xaml.Controls" @@ -97,7 +129,28 @@ xmlns:muxc="using:Microsoft.UI.Xaml.Controls" ``` - +# [**C#**](#tab/csharp) +```cs +new NavigationView() + .PaneTitle("Gesture NavView") + .OpenPaneLength(320) + .DrawerControlBehavior(fitToDrawerContent: false) + //TODO Couldnt find Drawer Style + .Style(Theme.NavigationView.Styles.Drawer) + .MenuItems( + new NavigationViewItem() + .Content("Home"), + new NavigationViewItem() + .Content("Page 1"), + new NavigationViewItem() + .Content("Page 2"), + new NavigationViewItem() + .Content("Page 3") + ) + .Content( + new Frame() + ) +``` From the `NavigationView`, the properties of the `DrawerControl` can be accessed through the same/similarly named properties or via attached properties: DrawerControl|NavigationView diff --git a/doc/controls/DrawerFlyoutPresenter.md b/doc/controls/DrawerFlyoutPresenter.md index e3511b254..fd45dadfe 100644 --- a/doc/controls/DrawerFlyoutPresenter.md +++ b/doc/controls/DrawerFlyoutPresenter.md @@ -8,6 +8,7 @@ uid: Toolkit.Controls.DrawerFlyoutPresenter ## Properties ### Remarks All of the properties below can be used both as a dependency property or as an attached property, much like the `ScrollViewer` properties: +# [**XAML**](#tab/xaml) ```xml xmlns:utu="using:Uno.Toolkit.UI" @@ -25,6 +26,22 @@ xmlns:utu="using:Uno.Toolkit.UI" LightDismissOverlayBackground="#80808080" IsGestureEnabled="True" /> ``` +# [**C#**](#tab/csharp) +```cs +new Style() + .BasedOn("DrawerFlyoutPresenterStyle") + .Setters(s => s.DrawerFlyoutPresenter(x => x.OpenDirection(DrawerOpenDirection.Up))) + .Setters(s => s.DrawerFlyoutPresenter(x => x.LightDismissOverlayBackground("#80808080"))) + .Setters(s => s.DrawerFlyoutPresenter(x => x.IsGestureEnabled(true))) +// and/or +new DrawerFlyoutPresenter() + .OpenDirection(DrawerOpenDirection.Up) + .LightDismissOverlayBackground("#80808080") + .IsGestureEnabled(true) +``` +> [!IMPORTANT] +> `DrawerLength` is currently not supported in C# Markup. +*** > [!IMPORTANT] > There is currently a bug on windows that prevents the usage of attached property style setters. The workaround is to add the following code in your application: @@ -88,6 +105,7 @@ To use this, simply use a `Flyout` with `Placement="Full"` and one of the follow - `BottomDrawerFlyoutPresenterStyle` (OpenDirection=Up) Example: +# [**XAML**](#tab/xaml) ```xml ``` +# [**C#**](#tab/csharp) +```cs +new Button() + .Flyout( + new Flyout() + .Placement(FlyoutPlacementMode.Full) + //TODO couldn't find BottomDrawer style + .FlyoutPresenterStyle(Theme.FlyoutPresenter.Styles.BottomDrawer) + .Content( + new StackPanel() + .VisibleBoundsPadding(PaddingMask.All) + .Background(Colors.SkyBlue) + .MinHeight(200) + .Children( + new TextBlock() + .Text("text"), + new Button() + .Content("button") + ) + ) + ) +``` +*** > [!NOTE] > Here `VisibleBoundsPadding.PaddingMask` is used to prevent the content from being placed outside of the user-interactable area on mobile devices. ### Extended Use Cases - Rounded Corner + # [**XAML**](#tab/xaml) ```xml @@ -120,8 +162,27 @@ Example: ``` + # [**C#**](#tab/csharp) + ```cs + new Flyout() + .Placement(FlyoutPlacementMode.Full) + .FlyoutPresenterStyle( + new Style() + .BasedOn("BottomDrawerFlyoutPresenterStyle") + .Setters(s => s.CornerRadius(new CornerRadius(16, 16, 0, 0))) + ) + .Content( + new Border() + .VisibleBoundsPadding(PaddingMask.All) + .Padding(new Thickness(16, 16, 0, 0)) + ) + ``` + *** + > remarks: `Padding` is used on the flyout content to avoid content being clipped. + - Custom background + # [**XAML**](#tab/xaml) ```xml @@ -134,8 +195,29 @@ Example: ``` + # [**C#**](#tab/csharp) + ```cs + new Flyout() + .Placement(FlyoutPlacementMode.Full) + .FlyoutPresenterStyle( + new Style() + .BasedOn("BottomDrawerFlyoutPresenterStyle") + .Setters(s => s.Background(Colors.SkyBlue)) + ) + .Content( + new Border() + .VisibleBoundsPadding(PaddingMask.All) + .Padding(new Thickness(16, 16, 0, 0)) + ) + ``` + *** > remarks: Avoid setting `Background` directly on the flyout content: > ```xml > > ``` + > ```cs + > new Border() + > .Placement(FlyoutPlacementMode.Full) + > .Background(Colors.SkyBlue) + > ``` > Instead, `Background` should be set from style setter to avoid edge bleeding on certain platforms, and to avoid default background being painted on the rounded corners. diff --git a/doc/controls/ExtendedSplashScreen.md b/doc/controls/ExtendedSplashScreen.md index cb5c9584a..a97ba34b0 100644 --- a/doc/controls/ExtendedSplashScreen.md +++ b/doc/controls/ExtendedSplashScreen.md @@ -15,17 +15,17 @@ SplashIsEnabled|bool|Gets a value that determines whether native splash is to be ## Usage +# [**XAML**](#tab/xaml) ```xml xmlns:utu="using:Uno.Toolkit.UI" ... - + HorizontalAlignment="Stretch" + VerticalAlignment="Stretch" + HorizontalContentAlignment="Stretch" + VerticalContentAlignment="Stretch" + Platforms="Android,iOS,Windows"> @@ -35,13 +35,36 @@ xmlns:utu="using:Uno.Toolkit.UI" + Grid.Row="1" + VerticalAlignment="Center" + HorizontalAlignment="Center" + Height="100" + Width="100" /> ``` +# [**C#**](#tab/csharp) +```cs +new ExtendedSplashScreen() + .HorizontalAlignment(HorizontalAlignment.Stretch) + .VerticalAlignment(VerticalAlignment.Stretch) + .HorizontalContentAlignment(HorizontalAlignment.Stretch) + .VerticalContentAlignment(VerticalAlignment.Stretch) + .Platforms(//TODO how to add multiple choices?) + .LoadingContentTemplate(() => + new Grid() + .RowDefinitions("2*, Auto") + .Children( + new ProgressRing() + .IsActive(true) + .Grid(row: 1) + .VerticalAlignment(VerticalAlignment.Center) + .HorizontalAlignment(HorizontalAlignment.Center) + .Height(100) + .Width(100) + ) + ) +``` +*** \ No newline at end of file diff --git a/doc/controls/LoadingView.md b/doc/controls/LoadingView.md index 6bb7e39eb..785f658c5 100644 --- a/doc/controls/LoadingView.md +++ b/doc/controls/LoadingView.md @@ -29,6 +29,7 @@ Represents an `ILoadable` that forwards the `ILoadable.IsExecuting` state of its Represents an `ILoadable` aggregate that is `ILoadable.IsExecuting` when any of its nested Sources is. ## Usage +# [**XAML**](#tab/xaml) ```xml xmlns:utu="using:Uno.Toolkit.UI" ... @@ -68,6 +69,60 @@ xmlns:utu="using:Uno.Toolkit.UI" ``` +# [**C#**](#tab/csharp) +```cs +// single source example +new LoadingView() + .Source(() => vm.FetchWeatherForecasts) + .Content( + new Grid() + .RowDefinitions("Auto,*") + .Children( + new Button() + .Grid(row:0) + .Content("Refresh") + .Command(() => vm.FetchWeatherForecasts), + new ListView() + .Grid(row:1) + .ItemsSource(() => vm.Forecasts) + ) + ) + .LoadingContent( + new StackPanel() + .Children( + new TextBlock() + .Text("Scrying..."), + new Image() + .Source("ms-appx:///Assets/CrystalBall.jpg") + ) + ) + +// multi-sources example +new LoadingView() + .Source( + new CompositeLoadableSource() + .Content( + new LoadableSource() + .Source(() => vm.LoadContent0Command), + new LoadableSource() + .Source(() => vm.LoadContent1Command) + ) + ) + .Content( + new StackPanel() + .Children( + new ListView() + .ItemsSource(() => vm.Content0), + new ListView() + .ItemsSource(() => vm.Content1) + ) + ) + .LoadingContent( + new ProgressRing() + .IsActive(true) + ) +``` +*** ```cs private class ViewModel : ViewModelBase diff --git a/doc/controls/NavigationBar.md b/doc/controls/NavigationBar.md index 113db8103..a55855c26 100644 --- a/doc/controls/NavigationBar.md +++ b/doc/controls/NavigationBar.md @@ -16,14 +16,19 @@ This document highlights some of the differences you might encounter when workin public partial class NavigationBar : ContentControl ``` -### XAML +### Usage +# [**XAML**](#tab/xaml) ```xml xmlns:utu="using:Uno.Toolkit.UI" ... ``` - +# [**C#**](#tab/csharp) +```cs +new NavigationBar() +``` +*** ### Inheritance Object → DependencyObject → UIElement → FrameworkElement → Control → ContentControl → NavigationBar @@ -50,11 +55,16 @@ Under the hood, this mode uses a custom-styled `CommandBar`. It is templatable a ![](../assets/navbar-windows-page2.png) #### Usage Example - +# [**XAML**](#tab/xaml) ```xml - + ``` - +# [**C#**](#tab/csharp) +```cs +new Style() + .Setters(s => s.MainCommandStyle( + new Style() + .Setters(s => s.Foreground(Colors.Red)) + )) +``` +*** Remarks: Only supports `SolidColorBrush`. @@ -379,6 +493,7 @@ Gets or sets the back button icon for the `MainCommand`. ![](../assets/navbar-ios-back-icon.png) +# [**XAML**](#tab/xaml) ```xml @@ -390,7 +505,19 @@ Gets or sets the back button icon for the `MainCommand`. ``` - +# [**C#**](#tab/csharp) +```cs +new NavigationBar() + .Content("Title") + .MainCommand( + new AppBarButton() + .Icon( + new BitmapIcon() + .UriSource(new Uri("ms-appx:///Assets/Close.png")) + ) + ) +``` +*** Remarks: @@ -582,7 +709,7 @@ Remarks: # FAQ: NavigationBar ## How can I remove the back button title from all pages on iOS? - + # [**XAML**](#tab/xaml) ```xml xmlns:utu="using:Uno.Toolkit.UI" ... @@ -599,9 +726,20 @@ Remarks: Value="{StaticResource MyCustomAppBarButtonStyle}" /> ``` - + # [**C#**](#tab/csharp) + ```cs + new Style() + .BasedOn("NavigationBarStyle") + .Setters(s => s.MainCommandStyle( + new Style() + .BasedOn("AppBarButtonStyle") + .Setters(s => s.Label("")) + )) + ``` + *** ## How can I change the back button icon/arrow/chevron in my app? - + + # [**XAML**](#tab/xaml) ```xml xmlns:utu="using:Uno.Toolkit.UI" ... @@ -615,9 +753,22 @@ Remarks: ``` + # [**C#**](#tab/csharp) + ```cs + new NavigationBar() + .Content("Page Title") + .MainCommand( + new AppBarButton() + .Icon( + new BitmapIcon() + .UriSource(new Uri("ms-appx:///Assets/Back.png")) + ) + ) + ``` + *** ## How can I change the color of the back button? - + # [**XAML**](#tab/xaml) ```xml xmlns:utu="using:Uno.Toolkit.UI" ... @@ -628,6 +779,17 @@ Remarks: ``` + # [**C#**](#tab/csharp) + ```cs + new NavigationBar() + .Content("Page Title") + .MainCommand( + new AppBarButton() + .Foreground(Colors.Red) + .ShowAsMonochrome(false) + ) + ``` + *** ## Why does my back button display "Back" on iOS? @@ -653,7 +815,8 @@ Remarks: ## How can I add a badge to an AppBarButton? You can implement your own badge by setting a custom content on `AppBarButton`: - + + # [**XAML**](#tab/xaml) ```xml @@ -682,20 +845,63 @@ Remarks: ``` + # [**C#**](#tab/csharp) + ```cs + new AppBarButton() + .Content( + new Grid() + .Height(48) + .Width(48) + .Children( + new Image() + .Source("ms-appx:///Assets/Icons/cart.png") + .VerticalAlignment(VerticalAlignment.Center) + .HorizontalAlignment(HorizontalAlignment.Center), + new Border() + .VerticalAlignment(VerticalAlignment.Top) + .HorizontalAlignment(HorizontalAlignment.Right) + .Background(Colors.Red) + .Margin(new Thickness(8, 4, 8, 4)) + .Padding(new Thickness(4, 0, 4, 0)) + .MinWidth(16) + .Height(16) + .CornerRadius(new CornerRadius(8)) + .Child( + new TextBlock() + .HorizontalAlignment(HorizontalAlignment.Center) + .VerticalAlignment(VerticalAlignment) + .Foreground(Colors.White) + .FontSize(8) + .Text("0") + ) + ) + ) + ``` + *** ## How can I set custom content to an AppBarButton? - You can set a custom content to an `AppBarButton` like this: - - ```xml - - - - - - - ``` - +You can set a custom content to an `AppBarButton` like this: +# [**XAML**](#tab/xaml) +```xml + + + + + + +``` +# [**C#**](#tab/csharp) +```cs +new AppBarButton() + .Content( + //Custom content goes here + new TextBlock() + .Text("asd") + ) +``` +*** + ## Why does my NavigationBar always appear at the top of the page on iOS? You can't place your `NavigationBar` anywhere other than at the top of the `Page` on **iOS**. See the **Placement** section for details. @@ -721,21 +927,35 @@ Remarks: `Page` only supports a single `NavigationBar` at a time. To display two `NavigationBar`s side by side (i.e., master-detail), you should place two `Frame`s side by side and put a `NavigationBar` in the `Page` of each `Frame`. ## How can I add a burger menu to the left of my NavigationBar? - - ```xml - xmlns:utu="using:Uno.Toolkit.UI" - ... - - - - - - - - - - ``` - + +# [**XAML**](#tab/xaml) +```xml +xmlns:utu="using:Uno.Toolkit.UI" +... + + + + + + + + + +``` +# [**C#**](#tab/csharp) +```cs +new NavigationBar() + .MainCommand( + new AppBarButton() + .Command(() => vm.ToggleMenu) + .Icon( + new BitmapIcon() + .UriSource(new Uri("ms-appx:///Assets/Icons/menu.png")) + ) + ) +``` +*** + ## Why doesn't Flyout work on my AppBarButton? `AppBarButton` doesn't currently support `Flyout` when using `NavigationBar` in native mode. You can use `MenuFlyout` instead. @@ -775,19 +995,29 @@ Remarks: ## How can I customize the font of the NavigationBar title/content? - To customize the font of the `NavigationBar`'s title, you must set a custom `FrameworkElement` as the `Content` of your `NavigationBar`: - - ```xml - xmlns:utu="using:Uno.Toolkit.UI" - ... - - - - - - ``` - +To customize the font of the `NavigationBar`'s title, you must set a custom `FrameworkElement` as the `Content` of your `NavigationBar`: +# [**XAML**](#tab/xaml) +```xml +xmlns:utu="using:Uno.Toolkit.UI" +... + + + + + +``` +# [**C#**](#tab/csharp) +```cs +new NavigationBar() + .Content( + new TextBlock() + .Text("Title") + .FontFamily(StaticResource.Get("CustomFontFamily")) + ) +``` +*** + ## Why doesn't my NavigationBar scroll when placed inside a ScrollViewer on iOS? `NavigationBar` can't be placed inside a `ScrollViewer`. It must be anchored to the top of your `Page` at all times. Please refer to the **Placement** section for details. @@ -810,37 +1040,64 @@ Remarks: ## Why doesn't my AppBarToggleButton work? - `AppBarToggleButton` is not currently supported. - - To implement a similar effect, you can bind your `AppBarButton`'s icon to a state using a converter: - - ```xml - xmlns:utu="using:Uno.Toolkit.UI" - ... - - - - - - - - ``` +`AppBarToggleButton` is not currently supported. + +To implement a similar effect, you can bind your `AppBarButton`'s icon to a state using a converter: +# [**XAML**](#tab/xaml) +```xml +xmlns:utu="using:Uno.Toolkit.UI" +... + + + + + + + +``` +# [**C#**](#tab/csharp) +```cs +new NavigationBar() + .Content( + new AppBarButton() + .Command(()=> vm.ToggleIsFavorite) + .Icon( + new BitmapIcon() + // TODO: is this correct? + .UriSource(() => vm.IsFavorite, isFavorite => isFavorite ? new Uri("ms-appx:///Assets/Icons/filled_star.png") : new Uri("ms-appx:///Assets/Icons/outlined_star.png")) + ) + ) +``` +*** ## How can I show an image under my NavigationBar? - You can show an image under a `NavigationBar` by making its background transparent and superposing it over an `Image`: - - ```xml - xmlns:utu="using:Uno.Toolkit.UI" - ... - - - - - ``` - - ![](assets/NavigationBar/ios/transparent.png) +You can show an image under a `NavigationBar` by making its background transparent and superposing it over an `Image`: + +# [**XAML**](#tab/xaml) +```xml +xmlns:utu="using:Uno.Toolkit.UI" +... + + + + +``` +# [**C#**](#tab/csharp) +```cs +new Grid() + .Children( + new Image() + .Source("http://www.example.com/image.png"), + new NavigationBar() + .Background(Colors.Transparent) + .VerticalAlignment(VerticalAlignment.Top) + ) +``` +*** + +![](assets/NavigationBar/ios/transparent.png) ## What size should my AppBarButton icons be? @@ -848,24 +1105,37 @@ Remarks: ## Why does my back button icon change when swiping back on iOS? - This can happen when navigating between two pages with `NavigationBar`s using different `MainCommand.Icon`s - - To avoid this issue, please make sure that all `NavigationBar`s use the same `BitmapIcon` for their `MainCommand.Icon` by using a style: - - ```xml - xmlns:utu="using:Uno.Toolkit.UI" - ... - +This can happen when navigating between two pages with `NavigationBar`s using different `MainCommand.Icon`s - - ``` +To avoid this issue, please make sure that all `NavigationBar`s use the same `BitmapIcon` for their `MainCommand.Icon` by using a style: + +# [**XAML**](#tab/xaml) +```xml +xmlns:utu="using:Uno.Toolkit.UI" +... + + + +``` +# [**C#**](#tab/csharp) +```cs +new Style() + .Setters(x => x.MainCommandStyle( + new Style() + .Setters(s => s.Icon( + new BitmapIcon() + .UriSource(new Uri("ms-appx:///Assets/Icons/back.png")) + )) + )) +``` +*** \ No newline at end of file diff --git a/doc/controls/SafeArea.md b/doc/controls/SafeArea.md index 24b612658..d73fad8d8 100644 --- a/doc/controls/SafeArea.md +++ b/doc/controls/SafeArea.md @@ -17,6 +17,7 @@ In some cases, it is acceptable for visible content to be partially obscured (a `SafeArea` can be used as a control or as a set of attached properties on another `FrameworkElement`, much like the `ScrollViewer`: +# [**XAML**](#tab/xaml) ```xml xmlns:utu="using:Uno.Toolkit.UI" @@ -30,6 +31,17 @@ xmlns:utu="using:Uno.Toolkit.UI" ``` +# [**C#**](#tab/csharp) +```cs +new Grid() + .SafeArea(SafeArea.InsetMask.VisibleBounds) + .Children( + // Content + ) +``` +> [!IMPORTANT] +> `SafeArea` as control is currently not supported in C# Markup. +*** > [!WARNING] > In most cases, the attached properties and the `SafeArea` control can be used interchangeably. However, be aware that using `SafeArea` as a control while `Insets` contains `InsetMask.SoftInput` will introduce a `ScrollViewer` into the visual tree as the content root of the `SafeArea`. Please refer to the [SoftInput usage section](#using-insetmasksoftinput-for-on-screen-keyboards). @@ -66,6 +78,7 @@ Here we are using the Toolkit's [`TabBar`](TabBarAndTabBarItem.md) with both the Given the following XAML, we can see what SafeArea is doing and what the differences are between an `InsetMode` of `Padding` versus `Margin`. +# [**XAML**](#tab/xaml) ```xml @@ -88,10 +101,10 @@ Given the following XAML, we can see what SafeArea is doing and what the differe + FontSize="30" + Grid.Row="1" + VerticalAlignment="Center" + HorizontalAlignment="Center" /> @@ -129,6 +142,80 @@ Given the following XAML, we can see what SafeArea is doing and what the differe ``` +# [**C#**](#tab/csharp) +```cs +public MainPage() +{ + this.DataContext((page, vm) => page + .Content( + new Grid() + .RowDefinitions("Auto,*,Auto") + .Children( + new TabBar() + .Background(Colors.Purple) + .Items( + new TabBarItem() + .Foreground(Colors.White) + .Content("Home"), + new TabBarItem() + .Foreground(Colors.White) + .Content("Search"), + new TabBarItem() + .Foreground(Colors.White) + .Content("Support"), + new TabBarItem() + .Foreground(Colors.White) + .Content("About") + ), + new TextBlock() + .Text("Page Content") + .FontSize(30) + .Grid(row: 1) + .VerticalAlignment(VerticalAlignment.Center) + .HorizontalAlignment(HorizontalAlignment.Center), + new TabBar() + .Grid(row: 2) + .Background(Colors.Purple) + .Items( + new TabBarItem() + .Foreground(Colors.White) + .Content("Home") + .Icon( + new FontIcon() + .Foreground(Colors.White) + .Glyph("") + ), + new TabBarItem() + .Foreground(Colors.White) + .Content("Search") + .Icon( + new FontIcon() + .Foreground(Colors.White) + .Glyph("") + ), + new TabBarItem() + .Foreground(Colors.White) + .Content("Support") + .Icon( + new FontIcon() + .Foreground(Colors.White) + .Glyph("") + ), + new TabBarItem() + .Foreground(Colors.White) + .Content("About") + .Icon( + new FontIcon() + .Foreground(Colors.White) + .Glyph("") + ) + ) + ) + ) + ); +} +``` +*** #### [**Without SafeArea**](#tab/none) @@ -138,18 +225,34 @@ Given the following XAML, we can see what SafeArea is doing and what the differe Top TabBar: +**XAML** ```diff ``` +**C#** +```diff +new TabBar() + .Background(Colors.Purple) ++ .SafeArea(SafeArea.InsetMask.Top) +``` Bottom TabBar: +**XAML** ```diff ``` +**C#** +```diff +new TabBar() + .Grid(row: 2) ++ .SafeArea(SafeArea.InsetMask.Bottom) + .Background(Colors.Purple) +``` + ![safearea_with_padding_alpha](../assets/safearea_with_padding.png) @@ -157,23 +260,37 @@ Bottom TabBar: Top TabBar: +**XAML** ```diff ``` +**C#** +```diff +new TabBar() + .Background(Colors.Purple) ++ .SafeArea(SafeArea.InsetMask.Top, SafeArea.InsetMode.Margin) +``` Bottom TabBar: +**XAML** ```diff ``` +**C#** +```diff +new TabBar() + .Grid(row: 2) ++ .SafeArea(SafeArea.InsetMask.Bottom, SafeArea.InsetMode.Margin) + .Background(Colors.Purple) +``` ![safearea_with_margin_alpha](../assets/safearea_with_margin.png) - *** ### Using `InsetMask.SoftInput` for on-screen keyboards @@ -204,6 +321,7 @@ Notice in this first example (without `SafeArea` in use) that the Username and P +**XAML** ```xml @@ -245,6 +363,51 @@ Notice in this first example (without `SafeArea` in use) that the Username and P ``` +**C#** +```cs +new Grid() + .Padding(new Thickness(50,0,50,0)) + // 0: Logo, 1: Spacing, 2: FormPanel + .RowDefinitions("Auto, 40, *") + .Children( + // Logo + new Image() + .Source("ms-appx:///Assets/uno-logo.png") + .VerticalAlignment(VerticalAlignment.Stretch) + .HorizontalAlignment(HorizontalAlignment.Stretch), + // FormPanel + new StackPanel() + .Grid(row: 2) + .Spacing(20) + .Children( + new TextBlock() + .Text("Welcome to Uno!") + .HorizontalAlignment(HorizontalAlignment.Center) + .FontSize(35), + new PersonPicture() + .ProfilePicture("ms-appx:///Assets/profile.png"), + new TextBox() + .PlaceholderText("Username"), + new StackPanel() + .Orientation(Orientation.Horizontal) + .Spacing(4) + .Children( + new CheckBox() + .Padding(0) + .MinWidth(0), + new TextBlock() + .Text("Remember me") + .VerticalAlignment(VerticalAlignment.Center) + ), + new Button() + .Content("Login") + .VerticalAlignment(VerticalAlignment.Top) + .HorizontalAlignment(HorizontalAlignment.Stretch) + .Margin(new Thickness(0, 30, 0, 30)) + ) + ) + +``` @@ -255,12 +418,13 @@ In this next example, we attempt to have the UI adapt to the keyboard by attachi - + @@ -328,37 +525,55 @@ There are alternative usages of `SafeArea` that may be considered in this situat 1. Have your own ScrollViewer defined within the XAML and then you can simply wrap that `ScrollViewer` with any container, such as `Grid`, and use the `SafeArea` attached properties on that wrapping container. -
PageXAMLCode
+**XAML** ```diff ``` +**C#** +```diff +new StackPanel() + .Grid(row: 2) ++ .SafeArea(SafeArea.InsetMask.SoftInput) + .Spacing(20) + .Children( + new TextBlock() + .Text("Welcome to Uno!") + .HorizontalAlignment(HorizontalAlignment.Center) + .FontSize(35), + new PersonPicture() + .ProfilePicture("ms-appx:///Assets/profile.png"), + new TextBox() + .PlaceholderText("Username"), + new StackPanel() + .Orientation(Orientation.Horizontal) + .Spacing(4) + .Children( + new CheckBox() + .Padding(0) + .MinWidth(0), + new TextBlock() + .Text("Remember me") + .VerticalAlignment(VerticalAlignment.Center) + ), + new Button() + .Content("Login") + .VerticalAlignment(VerticalAlignment.Top) + .HorizontalAlignment(HorizontalAlignment.Stretch) + .Margin(new Thickness(0, 30, 0, 30)) + ) +```
- - - - - +
PageXAML
+ + + + + - - -
PageCode
+ - ```diff - - + - + - - - - - - - - ... - + - + - - - ``` +**XAML** +```diff + ++ ++ + + + + + + + + ... ++ ++ + + +``` +**C#** +```diff ++ new Grid() ++ .SafeArea(SafeArea.InsetMask.SoftInput) ++ .Children( ++ new ScrollViewer() ++ .Content( + new Grid() + .Padding(new Thickness(50,0,50,0)) + // 0: Logo, 1: Spacing, 2: FormPanel + .RowDefinitions("Auto, 40, *") + .Children( + ... + ) ++ ) ++ ) +``` -
+ + + 2. If you do not want to have the whole page scrollable, you could wrap only the FormPanel `StackPanel` within a `SafeArea` instead of the root `Grid`. This may not always have the best visual effect as can be seen in the demonstration below diff --git a/doc/getting-started.md b/doc/getting-started.md index a0fa984fb..fb9a3d198 100644 --- a/doc/getting-started.md +++ b/doc/getting-started.md @@ -7,6 +7,9 @@ uid: Toolkit.GettingStarted The Uno.Toolkit library is available as NuGet packages that can be added to any new or existing Uno solution. +> [!NOTE] +> The Toolkit library also has support for C# Markup through a [Uno.Toolkit.WinUI.Markup](https://www.nuget.org/packages/Uno.Toolkit.WinUI.Markup) NuGet Package. To get started with Toolkit in your C# Markup application, add the `Uno.Toolkit.WinUI.Markup` NuGet package to your **App Code Library** project and your platform heads. + > [!NOTE] > As of [Uno 4.7](https://platform.uno/blog/uno-platform-4-7-new-project-template-performance-improvements-and-more/), the solution template of an Uno app has changed. There is no longer a Shared project (.shproj), it has been replaced with a regular cross-platform library containing all user code files, referred to as the **App Code Library** project. This also implies that package references can be included in a single location without the previous need to include those in all project heads. @@ -19,23 +22,39 @@ This article is a guide for installing the base Uno.Toolkit library, additional 1. Open an existing Uno project, or create a new Uno project using the `Multi-Platform App (Uno Platform)` template. 2. In the Solution Explorer panel, right-click on your app's **App Code Library** project (`PROJECT_NAME.csproj`) and select `Manage NuGet Packages...` -3. Install the [**`Uno.Toolkit.WinUI`**](https://www.nuget.org/packages/Uno.Toolkit.WinUI.Material) package -4. Add the resources to `AppResources.xaml`: - - ```xml - - +3. Install the [**`Uno.Toolkit.WinUI`**](https://www.nuget.org/packages/Uno.Toolkit.WinUI.Material) package for XAML or [**`Uno.Toolkit.WinUI.Markup`**](https://www.nuget.org/packages/Uno.Toolkit.WinUI.Markup) for C# Markup. +4. Add the resources to the `AppResources` file: +# [**XAML**](#tab/xaml) +```xml + + - - + + - - - - - - ``` + + + + +``` +# [**C#**](#tab/csharp) +```cs +public sealed class AppResources : ResourceDictionary +{ + public AppResources() + { + + // Load Uno.UI.Toolkit Resources + this.Build(r => r.Merged( + new ToolkitResources())); + + // Load custom application resources + // ... + } +} +``` +*** #### Previous Installation Method If your application is based on the older solution template that includes a shared project (.shproj), follow these steps: @@ -74,17 +93,4 @@ If your application is based on the older solution template that includes a shar ``` -## Using C# Markup - -The Toolkit library also has support for C# Markup through a [Uno.Toolkit.WinUI.Markup](https://www.nuget.org/packages/Uno.Toolkit.WinUI.Markup) NuGet Package. - -To get started with Toolkit in your C# Markup application, add the `Uno.Toolkit.WinUI.Markup` NuGet package to your **App Code Library** project and your platform heads. -Then, add the following code to your `AppResources.cs`: - -```csharp -using Uno.Toolkit.UI.Markup; - -this.Build(r => r.UseToolkit()); -``` - > [!NOTE]: If you are using the [Uno.Toolkit.WinUI.Material.Markup](https://www.nuget.org/packages/Uno.Toolkit.WinUI.Material.Markup) NuGet package, follow the steps in the [Using C# Markup for the Material Toolkit](./material-getting-started.md#using-c-markup) guide instead as it includes the Toolkit library. diff --git a/doc/material-getting-started.md b/doc/material-getting-started.md index c124c6944..3510d2384 100644 --- a/doc/material-getting-started.md +++ b/doc/material-getting-started.md @@ -16,7 +16,7 @@ Initialization of the Material Toolkit resources is handled by the specialized ` ### `MaterialToolkitTheme` > [!NOTE] -> The `MaterialToolkitTheme` class also handles the required initialization of the Uno.Material resources. Therefore, there is no need to initialize `MaterialTheme` within the `AppResources.xaml` +> The `MaterialToolkitTheme` class also handles the required initialization of the Uno.Material resources. Therefore, there is no need to initialize `MaterialTheme` within the `AppResources` file. #### Constructors @@ -34,27 +34,48 @@ Initialization of the Material Toolkit resources is handled by the specialized ` ## Installation +> [!NOTE] +> The Material Toolkit library also has support for C# Markup through a [Uno.Toolkit.WinUI.Material.Markup](https://www.nuget.org/packages/Uno.Toolkit.WinUI.Material.Markup) NuGet Package. To get started with Material Toolkit in your C# Markup application, add the `Uno.Toolkit.WinUI.Material.Markup` NuGet package to your **App Code Library** project and your platform heads. + > [!NOTE] > As of [Uno Platform 4.7](https://platform.uno/blog/uno-platform-4-7-new-project-template-performance-improvements-and-more/), the solution template of the Uno app has changed. There is no longer a Shared project (.shproj), it has been replaced with a regular cross-platform library containing all user code files, referred to as the **App Code Library** project. This also implies that package references can be included in a single location without the previous need to include those in all project heads. 1. Open an existing Uno project, or create a new Uno project using the `Multi-Platform App (Uno Platform)` template. 2. In the Solution Explorer panel, right-click on your app's **App Code Library** project (`PROJECT_NAME.csproj`) and select `Manage NuGet Packages...` -3. Install the [**`Uno.Toolkit.WinUI.Material`**](https://www.nuget.org/packages/Uno.Toolkit.WinUI.Material) package -4. Add the resources to `AppResources.xaml`: +3. Install the [**`Uno.Toolkit.WinUI.Material`**](https://www.nuget.org/packages/Uno.Toolkit.WinUI.Material) package for XAML or [**`Uno.Toolkit.WinUI.Material.Markup`**](https://www.nuget.org/packages/Uno.Toolkit.WinUI.Material.Markup) for C# Markup. +4. Add the resources to the `AppResources` file: +# [**XAML**](#tab/xaml) +```xml + + - ```xml - - + + - - + + - - + + +``` +# [**C#**](#tab/csharp) +```cs +using Uno.Toolkit.UI.Material.Markup; - - - ``` +public sealed class AppResources : ResourceDictionary +{ + public AppResources() + { + // Load Material Toolkit resources (also loads the base Uno.Material resources) + this.Build(r => r.Merged( + new MaterialToolkitTheme())); + + // Load custom application resources + // ... + } +} +``` +*** ### Installing the Material Toolkit on previous versions of Uno Platform @@ -96,49 +117,52 @@ If your application is based on the older solution template that includes a shar ## Customization -With `MaterialToolkitTheme`, you do not need to explicitly initialize `MaterialTheme`, `MaterialColors`, or `MaterialFonts`. This means that all resource overrides should go through `MaterialToolkitTheme` itself. There are two properties on `MaterialToolkitTheme` that you can set within your `AppResources.xaml`. +With `MaterialToolkitTheme`, you do not need to explicitly initialize `MaterialTheme`, `MaterialColors`, or `MaterialFonts`. This means that all resource overrides should go through `MaterialToolkitTheme` itself. There are two properties on `MaterialToolkitTheme` that you can set within your `AppResources`. ### Customize Colors -Follow the steps [here](https://platform.uno/docs/articles/external/uno.themes/doc/material-getting-started.html#customize-color-palette) to create a `ColorPaletteOverride.xaml` file and add it to your **App Code Library** project (`PROJECT_NAME.csproj`) +Follow the steps [here](https://platform.uno/docs/articles/external/uno.themes/doc/material-getting-started.html#customize-color-palette) to create a `ColorPaletteOverride` file and add it to your **App Code Library** project (`PROJECT_NAME.csproj`) -In `AppResources.xaml`, instead of initializing `MaterialColors`, you would use the `ColorOverrideSource` property on `MaterialToolkitTheme`: +In `AppResources`, instead of initializing `MaterialColors`, you would use the `ColorOverrideSource` property on `MaterialToolkitTheme`: +# [**XAML**](#tab/xaml) ```xml - + ``` +# [**C#**](#tab/csharp) +```cs +this.Build(r => r.Merged( + new MaterialToolkitTheme( + colorOverride: new Styles.ColorPaletteOverride() + ) +)); +``` +*** ### Customize Fonts -Follow the steps [here](https://platform.uno/docs/articles/external/uno.themes/doc/material-getting-started.html#change-default-font) to create a `FontOverride.xaml` file and add it to your **App Code Library** project (`PROJECT_NAME.csproj`) +Follow the steps [here](https://platform.uno/docs/articles/external/uno.themes/doc/material-getting-started.html#change-default-font) to create a `FontOverride` file and add it to your **App Code Library** project (`PROJECT_NAME.csproj`) -In `AppResources.xaml`, instead of initializing `MaterialFonts`, you would use the `FontOverrideSource` property on `MaterialToolkitTheme`: +In the `AppResources` file, instead of initializing `MaterialFonts`, you would use the `FontOverrideSource` property on `MaterialToolkitTheme`: +# [**XAML**](#tab/xaml) ```xml ``` - -## Using C# Markup - -The Material Toolkit library also has support for C# Markup through a [Uno.Toolkit.WinUI.Material.Markup](https://www.nuget.org/packages/Uno.Toolkit.WinUI.Material.Markup) NuGet Package. - -To get started with Material Toolkit in your C# Markup application, add the `Uno.Toolkit.WinUI.Material.Markup` NuGet package to your **App Code Library** project and your platform heads. -Then, add the following code to your `AppResources.cs`: - -```csharp -using Uno.Toolkit.UI.Material.Markup; - -this.Build(r => r.UseMaterialToolkit( - //optional - new Styles.ColorPaletteOverride(), - //optional - new Styles.MaterialFontsOverride() +# [**C#**](#tab/csharp) +```cs +this.Build(r => r.Merged( + new MaterialToolkitTheme( + fontOverride: new Styles.MaterialFontsOverride() + ) )); ``` +*** -> [!NOTE]: The [Uno.Toolkit.WinUI.Material.Markup](https://www.nuget.org/packages/Uno.Toolkit.WinUI.Material.Markup) NuGet package includes the base [Toolkit Markup package](https://www.nuget.org/packages/Uno.Toolkit.WinUI.Markup) as a dependency. Therefore, there is no need to add the `Uno.Toolkit.WinUI.Markup` package separately. Furthermore, the `UseMaterialToolkit` extension method also initializes the Toolkit library, so there is no need to call the `UseToolkit` extension method in your `AppResources.cs`. +> [!NOTE] +> The [Uno.Toolkit.WinUI.Material.Markup](https://www.nuget.org/packages/Uno.Toolkit.WinUI.Material.Markup) NuGet package includes the base [Toolkit Markup package](https://www.nuget.org/packages/Uno.Toolkit.WinUI.Markup) as a dependency. Therefore, there is no need to add the `Uno.Toolkit.WinUI.Markup` package separately. Furthermore, the `MaterialToolkitTheme` extension method also initializes the Toolkit library, so there is no need to call the `ToolkitResources` extension method in your `AppResources.cs`. ## Additional Resources