diff --git a/specs/AnimatedVisualPlayer Spec.md b/specs/AnimatedVisualPlayer Spec.md index fa140a84da..5e8c61e8e7 100644 --- a/specs/AnimatedVisualPlayer Spec.md +++ b/specs/AnimatedVisualPlayer Spec.md @@ -4,37 +4,37 @@ AnimatedVisualPlayer Spec # Background Today, developers can create animated visuals to use in their UI by using the -[AnimatedVisualPlayer](https://docs.microsoft.com/uwp/api/Microsoft.UI.Xaml.Controls.AnimatedVisualPlayer) -control. -`AnimatedVisualPlayer` can play any -[IAnimatedVisual](https://docs.microsoft.com/uwp/api/Microsoft.UI.Xaml.Controls.IAnimatedVisual) -implementation, -but the typical way to get an `IAnimatedVisual` implementation is to use +[AnimatedVisualPlayer](https://learn.microsoft.com/uwp/api/Microsoft.UI.Xaml.Controls.AnimatedVisualPlayer) +control. `AnimatedVisualPlayer` can play any +[IAnimatedVisual](https://learn.microsoft.com/uwp/api/Microsoft.UI.Xaml.Controls.IAnimatedVisual) +implementation, but the typical way to get an `IAnimatedVisual` implementation is to use the LottieGen tool to generate code from a JSON file that was created from Adobe AfterEffects. -[More information on Lottie and AnimatedVisualPlayer](https://docs.microsoft.com/en-us/windows/communitytoolkit/animations/lottie) +[More information on Lottie and AnimatedVisualPlayer](https://learn.microsoft.com/windows/communitytoolkit/animations/lottie) -There are some performance issues with the current implementation of LottieGen and AnimatedVisualPlayer: -1) Complex Lottie animations can instantiate a lot of composition animations -which may impact performance and overall battery life. -2) Lottie files that have a lot of complex animations -have some cost to performance even when they are paused. +There are some performance issues with the current implementation of LottieGen and AnimatedVisualPlayer: + +1) Complex Lottie animations can instantiate a lot of composition animations +which may impact performance and overall battery life. +2) Lottie files that have a lot of complex animations +have some cost to performance even when they are paused. The Idle (paused) Lottie animations use the same amount of CPU resources as when they are playing the actual animation. The new APIs here allow `AnimatedVisualPlayer`, -[AnimatedIcon](https://docs.microsoft.com/uwp/api/Microsoft.UI.Xaml.Controls.AnimatedIcon), +[AnimatedIcon](https://learn.microsoft.com/uwp/api/Microsoft.UI.Xaml.Controls.AnimatedIcon), and the interface generated by LottieGen to be updated to help reduce the number of composition animations created when the animation is idle or paused to help improve performance when a developer uses Lottie Animations with `AnimatedVisualPlayer`. -This spec will focus on changes for LottieGen and `AnimatedVisualPlayer`. +This spec will focus on changes for LottieGen and `AnimatedVisualPlayer`. + +This will require 3 changes: -This will require 3 changes: -1. Create a new interface for which an implementation is generated by LottieGen called `IAnimatedVisual2`, +1. Create a new interface for which an implementation is generated by LottieGen called `IAnimatedVisual2`, that can destroy and instantiate animations. -2. Create a new interface `IAnimatedVisualSource3` from which to get the new `IAnimatedvisual2` -3. Add a `AnimationOptimization` property to AnimatedVisualPlayer that will control +2. Create a new interface `IAnimatedVisualSource3` from which to get the new `IAnimatedvisual2` +3. Add a `AnimationOptimization` property to AnimatedVisualPlayer that will control when animations should be destroyed and when they should be instantiated. This will be implemented using the previous new interfaces. @@ -47,29 +47,28 @@ Gets or sets a value that determines how animations are cached. Defaults to 'Lat The two modes for the property will specify the behavior the AnimatedVisualPlayer will have when the player is idle (when `PlayAsync` is not active). -|Mode| Behavior| -|---- | -------| -|Latency| AnimatedVisualPlayer will pre-create animations even before `PlayAsync()` is called, -and not destroy any when player is idle. -|Resources | AnimatedVisualPlayer will not create animations until `PlayAsync()` is called, -and will destroy them when it completes. If you call pause, this does not free up all -resources of the player. To truly stop the animation, call Stop. +| Mode | Behavior | +| ---- | -------- | +|Latency| AnimatedVisualPlayer will pre-create animations even before `PlayAsync()` is called, and not destroy any when player is idle. | +|Resources | AnimatedVisualPlayer will not create animations until `PlayAsync()` is called, and will destroy them when it completes. +If you call pause, this does not free up all resources of the player. To truly stop the animation, call Stop. | -Note: If you set the `Source` or `AnimationOptimization` of your player, the player will defer -processing of the source file until the layout is being formed. +> [!NOTE] +> If you set the `Source` or `AnimationOptimization` of your player, +> the player will defer processing of the source file until the layout is being formed. -If you have an animation that will start on click, you may want to initialize +If you have an animation that will start on click, you may want to initialize the property to `None` and set `AnimationOptimization` to 'Always' -when the mouse enters this control, +when the mouse enters this control, and back to `None` when mouse leaves to ensure that the animation starts immediately on click, but don't use up resources otherwise. Setting the `AnimationOptimization` to `Latency` when the mouse enters the control will ensure that -the animation objects are preloaded so that the animation may start immediately when it needs to play. +the animation objects are preloaded so that the animation may start immediately when it needs to play. If you call PlayAsync before animations are loaded, then the player won't start until all animations are loaded completely. -```c# +```csharp private void Player_PointerEntered(object sender, PointerRoutedEventArgs e) { myanimatedvisualplayer.AnimationOptimization = AnimationOptimization.Latency; @@ -83,15 +82,14 @@ async private void Player_OnClick(object sender, PointerRoutedEventArgs e) { myanimatedvisualplayer.PlayAsync(0.0, 1.0); } - ``` If `PlayAsync` is called and the animations have not been instantiated due to `AnimationOptimization` being set to `None`, -`PlayAsync` will instantiate the animations so it can play the visual. +`PlayAsync` will instantiate the animations so it can play the visual. # API Details -```c# +```csharp namespace Microsoft.UI.Xaml.Controls { unsealed runtimeclass AnimatedVisualPlayer @@ -113,15 +111,15 @@ namespace Microsoft.UI.Xaml.Controls ## IAnimatedVisual2 Interface An extension to -[IAnimatedVisual](https://docs.microsoft.com/uwp/api/Microsoft.UI.Xaml.Controls.IAnimatedVisual) +[IAnimatedVisual](https://learn.microsoft.com/uwp/api/Microsoft.UI.Xaml.Controls.IAnimatedVisual) that adds the ability to control when animation objects are created and destroyed. | Method | Meaning | -|-------------|---------| +|--------|---------| | CreateAnimations | Instantiates the animation visuals for the provided progress value of the animation. | | DestroyAnimations | Destroys all animation visuals for a given animation.| -```c# +```csharp interface IAnimatedVisual2 requires IAnimatedVisual { void InstantiateAnimations(Double progressHint); @@ -131,26 +129,27 @@ interface IAnimatedVisual2 requires IAnimatedVisual ## IAnimatedVisual2.InstantiateAnimations Method -Instantiates the animation visuals for the provided progress value of the animation. +Instantiates the animation visuals for the provided progress value of the animation. -```c# +```csharp void CreateAnimations(); ``` ## IAnimatedVisual2.DestroyAnimations Method -Destroys all animation visuals for a given animation. +Destroys all animation visuals for a given animation. -```c# +```csharp void DestroyAnimations(); ``` + ## IAnimatedVisualSource3 Interface An extension to -[IAnimatedVisualSource](https://docs.microsoft.com/uwp/api/Microsoft.UI.Xaml.Controls.IAnimatedVisualSource) +[IAnimatedVisualSource](https://learn.microsoft.com/uwp/api/Microsoft.UI.Xaml.Controls.IAnimatedVisualSource) that products an `IAnimatedVisualSource3`. -```c# +```csharp interface IAnimatedVisualSource3 { IAnimatedVisual2 TryCreateAnimatedVisual( @@ -158,5 +157,4 @@ interface IAnimatedVisualSource3 out Object diagnostics, Boolean instantiateAnimations,); }; - ``` diff --git a/specs/DateTimePicker-Visual-Updates-Spec.md b/specs/DateTimePicker-Visual-Updates-Spec.md index c8d72770ec..ce76a11683 100644 --- a/specs/DateTimePicker-Visual-Updates-Spec.md +++ b/specs/DateTimePicker-Visual-Updates-Spec.md @@ -3,29 +3,30 @@ MonochromaticOverlayPresenter # Background -The `MonochromaticOverlayPresenter` API is a Xaml Framework Element that renders the portion of +The `MonochromaticOverlayPresenter` API is a XAML Framework Element that renders the portion of another element at the same position (the portion of that element that it overlays), while also applying a monochromatic colorization effect. This allows the element to appear to be an overlay on top of the other element. `MonochromaticOverlayPresenter` element is similar to several precedents: -* [CompositionMaskBrush](https://docs.microsoft.com/uwp/api/Windows.UI.Composition.CompositionMaskBrush), + +- [CompositionMaskBrush](https://learn.microsoft.com/uwp/api/Windows.UI.Composition.CompositionMaskBrush), which is a brush that gets its content from another (source) brush. -* WPF's [VisualBrush](https://docs.microsoft.com/dotnet/api/System.Windows.Media.VisualBrush), +- WPF's [VisualBrush](https://learn.microsoft.com/dotnet/api/System.Windows.Media.VisualBrush), which uses an element's rendering to draw a brush. A key difference in this new type is that it only renders the portion of the source element which it intersects with in location. -This new `MonochromaticOverlayPresenter` will be used in the rendering of the -[DatePicker](https://docs.microsoft.com/uwp/api/Windows.UI.Xaml.Controls.DatePicker) +This new `MonochromaticOverlayPresenter` will be used in the rendering of the +[DatePicker](https://learn.microsoft.com/uwp/api/Windows.UI.Xaml.Controls.DatePicker) control (see more info in the Appendix). # API Pages ## MonochromaticOverlayPresenter class -A [Framework Element](https://docs.microsoft.com/windows/winui/api/microsoft.ui.xaml.frameworkelement?view=winui-3.0-preview) +A [Framework Element](https://learn.microsoft.com/windows/winui/api/microsoft.ui.xaml.frameworkelement?view=winui-3.0-preview) which renders another element at the same position (beneath it in the Z-order), while also optionally applying a monochromatic colorization effect. @@ -46,34 +47,35 @@ of the two elements will be rendered by the overlay. Only the source element's rendering applies to the `MonochromaticOverlayPresenter`; the user cannot interact with it using the mouse, or move keyboard focus to it. However, `MonochromaticOverlayPresenter` will render system focus visuals, regardless of what the -[UseSystemFocusVisuals](https://docs.microsoft.com/uwp/api/Windows.UI.Xaml.Controls.Control.UseSystemFocusVisuals) -property is set to. +[UseSystemFocusVisuals](https://learn.microsoft.com/uwp/api/Windows.UI.Xaml.Controls.Control.UseSystemFocusVisuals) +property is set to. To allow pointer events to get to the source element, set the overlay's -[UIElement.IsHitTestVisible](https://docs.microsoft.com/uwp/api/Windows.UI.Xaml.UIElement.IsHitTestVisible) +[UIElement.IsHitTestVisible](https://learn.microsoft.com/uwp/api/Windows.UI.Xaml.UIElement.IsHitTestVisible) property to false. -> Note: the element set as the `SourceElement` cannot be an ancestor or in the descendancy of -the `MonochromaticOverlayPresenter`. However the `SourceElement` must be in the same XAML tree as -the `MonochromaticOverlayPresenter`. +> [!NOTE] +> The element set as the `SourceElement` cannot be an ancestor or in the descendancy of the `MonochromaticOverlayPresenter`. +> However the `SourceElement` must be in the same XAML tree as the `MonochromaticOverlayPresenter`. -If the `ReplacementColor` property is set and has a nonzero Alpha value, then the `SourceElement` -is treated as a mask: every non-transparent pixel will be replaced by this color. The RGB value -of the `ReplacementColor` (not the Alpha value) will override the RGB of the source. +If the `ReplacementColor` property is set and has a nonzero Alpha value, then the `SourceElement` +is treated as a mask: every non-transparent pixel will be replaced by this color. The RGB value +of the `ReplacementColor` (not the Alpha value) will override the RGB of the source. The default value for `ReplacementColor` is -[Colors.Transparent](https://docs.microsoft.com/uwp/api/Windows.UI.Colors.Transparent). +[Colors.Transparent](https://learn.microsoft.com/uwp/api/Windows.UI.Colors.Transparent). ### MonochromaticOverlayPresenter examples The following example puts a `MonochromaticOverlayPresenter` on top of (z-ordered above) some scrolling text, causing the center of the text to be highlighted, even as it's scrolling. Things to note: -* The `MonochromaticOverlayPresenter` is sourcing from the `TextBlock`, it's also z-ordered above + +- The `MonochromaticOverlayPresenter` is sourcing from the `TextBlock`, it's also z-ordered above the same `TextBlock`. If the `Background` and `SourceElement` properties weren't set, it would have no effect; it would render the `TextBlock` exactly on top of itself. -* The `MonochromaticOverlayPresenter` is positioned and given a height such that it's a black band +- The `MonochromaticOverlayPresenter` is positioned and given a height such that it's a black band across the center of the scrolling text. -* The `MonochromaticOverlayPresenter.IsHitTestVisible` property is set to False, so that input +- The `MonochromaticOverlayPresenter.IsHitTestVisible` property is set to False, so that input still goes to the ScrollViewer that is z-ordered behind it. ```xml @@ -122,11 +124,11 @@ The example below shows how the new `MonochromaticOverlayPresenter` API can be u ### MonochromaticOverlayPresenter theme resources -You can modify the default Style and ControlTemplate to give the control a unique appearance. -For more info, see the -[Light-weight styling section](https://docs.microsoft.com/en-us/windows/uwp/design/controls-and-patterns/xaml-styles#lightweight-styling) -of the -[Styling controls](https://docs.microsoft.com/en-us/windows/uwp/design/controls-and-patterns/xaml-styles) +You can modify the default Style and ControlTemplate to give the control a unique appearance. +For more info, see the +[Light-weight styling section](https://learn.microsoft.com/windows/uwp/design/controls-and-patterns/xaml-styles#lightweight-styling) +of the +[Styling controls](https://learn.microsoft.com/windows/uwp/design/controls-and-patterns/xaml-styles) article. `MonochromaticOverlayPresenter` defines the following new resource: @@ -138,7 +140,7 @@ article. ## Other MonochromaticOverlayPresenter members | Name | Description | -| - | - | +| --- | --- | | SourceElement | Gets or sets the UIElement to render inside the `MonochromaticOverlayPresenter`. | | ReplacementColor | Gets or sets the Color to use instead of the non-transparent pixels of the SourceElement. @@ -165,32 +167,34 @@ unsealed runtimeclass MonochromaticOverlayPresenter : Windows.UI.Xaml.Controls.F ``` # Appendix + ## DatePicker -In WinUI 2.2, controls began to be re-designed to have rounded corners, marking a shift in our overall design language. -There's more information on rounded corners in WinUI [here](https://docs.microsoft.com/en-us/windows/uwp/design/style/rounded-corner), -but the general purpose of the rounded corners design shift is to evoke warmth and trust, -and make the UI easier for users to visually process. -Since this shift, certain controls have adopted the new styling and recieved rounded corners, but some have not. -This creates a strong visual inconsistency in WinUI apps, where certain pieces of an app may look modern and others may look dated. -Examples of this include the DatePicker and TimePicker controls. While the corners of the controls themselves are rounded, the selection rectangle within the control is still squared off. Buttons and other areas inside these controls are also still squared off, making them look dated when placed alongside other controls that are more modernly designed, such as -[NavigationView](https://docs.microsoft.com/en-us/windows/uwp/design/controls-and-patterns/navigationview). +In WinUI 2.2, controls began to be re-designed to have rounded corners, marking a shift in our overall design language. +There's more information on rounded corners in [WinUI docs](https://learn.microsoft.com/windows/uwp/design/style/rounded-corner), +but the general purpose of the rounded corners design shift is to evoke warmth and trust, +and make the UI easier for users to visually process. +Since this shift, certain controls have adopted the new styling and received rounded corners, but some have not. +This creates a strong visual inconsistency in WinUI apps, where certain pieces of an app may look modern and others may look dated. +Examples of this include the DatePicker and TimePicker controls. While the corners of the controls themselves are rounded, the selection rectangle within the control is still squared off. Buttons and other areas inside these controls are also still squared off, making them look dated when placed alongside other controls that are more modernly designed, such as +[NavigationView](https://learn.microsoft.com/windows/uwp/design/controls-and-patterns/navigationview). -Recently, [ListView was given design updates](https://github.com/microsoft/microsoft-ui-xaml-specs/blob/user/anawish/ListViewGridViewDesignUpdates/active/ListViewGridView/listviewgridview-designupdates.md) to round the corners of its items. DatePicker and TimePicker should follow in these footsteps, and make sure that they adopt any of the ListView design elements that are relevant. This includes general rounding of selection visuals, as well as rounded grey backplates for items that get hovered. +Recently, [ListView was given design updates](https://github.com/microsoft/microsoft-ui-xaml-specs/blob/user/anawish/ListViewGridViewDesignUpdates/active/ListViewGridView/listviewgridview-designupdates.md) to round the corners of its items. DatePicker and TimePicker should follow in these footsteps, and make sure that they adopt any of the ListView design elements that are relevant. This includes general rounding of selection visuals, as well as rounded grey backplates for items that get hovered. -This spec will detail a number of changes to update the designs of DatePicker and TimePicker so that they are more -visually aligned with modern WinUI controls. At a high level, some key parts of these updated styles are: a rounded selection rectangle; rounded backplates on items, buttons, and scroll buttons on hover; and new animations that are aligned with other controls. +This spec will detail a number of changes to update the designs of DatePicker and TimePicker so that they are more +visually aligned with modern WinUI controls. At a high level, some key parts of these updated styles are: a rounded selection rectangle; rounded backplates on items, buttons, and scroll buttons on hover; and new animations that are aligned with other controls. These visual changes to DatePicker and TimePicker will in part be made possible by the new `MonochromaticOverlayPresenter` API which is described above. This class provides the logic behind displaying the 'inverted' selection rectangle that spans across all three columns in DatePicker and TimePicker, and giving it the correct foreground color to have appropriate contrast over the accent colored background. ### Visual Examples + +(http://learn.microsoft.com/windows/uwp/design/controls-and-patterns/password-box). --> **DatePicker:** @@ -210,28 +214,18 @@ As you can see in the mockup below, all buttons and items (individual cells) wit ![Shows a DatePicker with scroll and check buttons being hovered, as well as the last column being focused upon](images/DPTP-other-states.PNG) - ## Detailed Task Breakdown for styling implementation + The following steps apply to both DatePicker and TimePicker, unless otherwise noted. 1. The background color of the overall flyout should change, as shown in mockups above. - -2. Selected items (entire rows) should have a rounded (4px corner radius) accent-color backplate. This backplate should have a 32px height, and have 4px margin on the left/right and 2px margin on the top/bottom from its overall footprint. - -3. When items (individual cells, i.e. "November") are in a hover or pressed state, they will have a rounded (4px corner radius) grey backplate, with the same margins from its overall footprint as the selection row has described above. This backplate should also be 32px in height. - -4. The scroll up/down button visuals should use caret icons (rather than the current chevron icons). - +2. Selected items (entire rows) should have a rounded (4px corner radius) accent-color backplate. This backplate should have a 32px height, and have 4px margin on the left/right and 2px margin on the top/bottom from its overall footprint. +3. When items (individual cells, i.e. "November") are in a hover or pressed state, they will have a rounded (4px corner radius) grey backplate, with the same margins from its overall footprint as the selection row has described above. This backplate should also be 32px in height. +4. The scroll up/down button visuals should use caret icons (rather than the current chevron icons). 5. When the scroller buttons are hovered, they should have a rounded grey backplate that have a height of 12px, and a 4px margin on all sides from their overall button footprints. - 6. The check and X buttons at the bottom of the Date/TimePicker should also be updated to use new icons as shown in mockups above. - 7. On hover, the check and X buttons should also receive a rounded gray backplate with 4px margins on all sides from its overall button footprint. - -8. Focus visuals for all buttons need to be rounded. - -9. **DatePicker only**: Items in columns should now be left-aligned, rather than center-aligned as they were previously.  - +8. Focus visuals for all buttons need to be rounded. +9. **DatePicker only**: Items in columns should now be left-aligned, rather than center-aligned as they were previously. 10. Columns within an expanded Date/TimePicker can be focused upon. For the column focus, the black focus rectangle will need to be rounded. - 11. Animations: Date/TimePicker should have an opening/closing animation and use the same easing/timing as other controls. diff --git a/specs/FooterMenuItemTemplate-spec.md b/specs/FooterMenuItemTemplate-spec.md index d9f7af1d49..9b3234c344 100644 --- a/specs/FooterMenuItemTemplate-spec.md +++ b/specs/FooterMenuItemTemplate-spec.md @@ -1,25 +1,24 @@ # Background -The [`NavigationView.FooterMenuItems`](https://docs.microsoft.com/windows/winui/api/microsoft.ui.xaml.controls.navigationview.footermenuitems?view=winui-2.5) property provides a way to place NavigationView items into a bottom-aligned (or right-aligned, if your NavigationView is in top mode) section of a NavigationView. This is distinct from the [`NavigationView.PaneFooter`](https://docs.microsoft.com/windows/winui/api/microsoft.ui.xaml.controls.navigationview.panefooter?view=winui-2.5) property, as only Navigation items should be placed in the Footer menu, while any kind of content can be placed in the PaneFooter. +The [`NavigationView.FooterMenuItems`](https://learn.microsoft.com/windows/winui/api/microsoft.ui.xaml.controls.navigationview.footermenuitems?view=winui-2.5) property provides a way to place NavigationView items into a bottom-aligned (or right-aligned, if your NavigationView is in top mode) section of a NavigationView. This is distinct from the [`NavigationView.PaneFooter`](https://learn.microsoft.com/windows/winui/api/microsoft.ui.xaml.controls.navigationview.panefooter?view=winui-2.5) property, as only Navigation items should be placed in the Footer menu, while any kind of content can be placed in the PaneFooter. Image of a NavigationView with labels pointing to main menu items and footer menu items -Currently, the DataTemplate that's assigned to the [`NavigationView.MenuItemTemplate`](https://docs.microsoft.com/windows/winui/api/microsoft.ui.xaml.controls.navigationview.menuitemtemplate?view=winui-2.5) property is applied to all Navigation items in the NavigationView. This means that if you add both regular NavigationView menu items and NavigationView footer menu items, they will automatically have the same data template applied. This is an issue as there's no current way to provide a standardized data template for all footer menu items that's separate/different from the data template used for all main menu items. +Currently, the DataTemplate that's assigned to the [`NavigationView.MenuItemTemplate`](https://learn.microsoft.com/windows/winui/api/microsoft.ui.xaml.controls.navigationview.menuitemtemplate?view=winui-2.5) property is applied to all Navigation items in the NavigationView. This means that if you add both regular NavigationView menu items and NavigationView footer menu items, they will automatically have the same data template applied. This is an issue as there's no current way to provide a standardized data template for all footer menu items that's separate/different from the data template used for all main menu items. # Description -In order to apply a data template to all items in the footer menu of your NavigationView, use the `NavigationView.FooterMenuItemTemplate` property. This property is similar to [NavigationView.MenuItemTemplate](https://docs.microsoft.com/windows/winui/api/microsoft.ui.xaml.controls.navigationview.menuitemtemplate?view=winui-2.5), but only applies to items placed in NavigationView's footer menu. It takes in a `DataTemplate` and applies that template to any Navigation item placed in the footer menu. +In order to apply a data template to all items in the footer menu of your NavigationView, use the `NavigationView.FooterMenuItemTemplate` property. This property is similar to [NavigationView.MenuItemTemplate](https://learn.microsoft.com/windows/winui/api/microsoft.ui.xaml.controls.navigationview.menuitemtemplate?view=winui-2.5), but only applies to items placed in NavigationView's footer menu. It takes in a `DataTemplate` and applies that template to any Navigation item placed in the footer menu. -To apply different data templates to individual Navigation items within your footer menu based on certain criteria, use the `NavigationView.FooterMenuItemTemplateSelector`. This property is similar to the [NavigationView.MenuItemTemplateSelector](https://docs.microsoft.com/windows/winui/api/microsoft.ui.xaml.controls.navigationview.menuitemtemplateselector?view=winui-2.5), but only applies to items placed in NavigationView's footer menu. +To apply different data templates to individual Navigation items within your footer menu based on certain criteria, use the `NavigationView.FooterMenuItemTemplateSelector`. This property is similar to the [NavigationView.MenuItemTemplateSelector](https://learn.microsoft.com/windows/winui/api/microsoft.ui.xaml.controls.navigationview.menuitemtemplateselector?view=winui-2.5), but only applies to items placed in NavigationView's footer menu. The Settings item will not be affected by FooterMenuItemTemplate as it is not technically a part of the FooterMenuItems collection. -The [NavigationView.MenuItemTemplate](https://docs.microsoft.com/windows/winui/api/microsoft.ui.xaml.controls.navigationview.menuitemtemplate?view=winui-2.5) will only apply to Navigation items that are placed in the main menu of a NavigationView. - +The [NavigationView.MenuItemTemplate](https://learn.microsoft.com/windows/winui/api/microsoft.ui.xaml.controls.navigationview.menuitemtemplate?view=winui-2.5) will only apply to Navigation items that are placed in the main menu of a NavigationView. # Examples -Example showing how a NavigationView can have different object types for main and footer menu items, and apply a different DataTemplate to each. +Example showing how a NavigationView can have different object types for main and footer menu items, and apply a different DataTemplate to each. ```xml - ``` - # API Notes - The following APIs are members of `NavigationView`. | Name | Description | -| - | - | -| FooterMenuItemTemplate | Gets or sets the [DataTemplate](https://docs.microsoft.com/en-us/uwp/api/windows.ui.xaml.datatemplate) used to display each footer menu item. | -| FooterMenuItemTemplateSelector | Gets or sets a reference to a custom [DataTemplateSelector](https://docs.microsoft.com/uwp/api/windows.ui.xaml.controls.datatemplateselector) logic class. The DataTemplateSelector referenced by this property returns a template to apply to Navigation items placed in the footer menu. - +| --- | --- | +| FooterMenuItemTemplate | Gets or sets the [DataTemplate](https://learn.microsoft.com/uwp/api/windows.ui.xaml.datatemplate) used to display each footer menu item. | +| FooterMenuItemTemplateSelector | Gets or sets a reference to a custom [DataTemplateSelector](https://learn.microsoft.com/uwp/api/windows.ui.xaml.controls.datatemplateselector) logic class. The DataTemplateSelector referenced by this property returns a template to apply to Navigation items placed in the footer menu. | # API Details - + + ```csharp [MUX_PREVIEW] @@ -69,5 +65,4 @@ The following APIs are members of `NavigationView`. static Windows.UI.Xaml.DependencyProperty FooterMenuItemTemplateProperty { get; }; static Windows.UI.Xaml.DependencyProperty FooterMenuItemTemplateSelectorProperty { get; }; } - ``` diff --git a/specs/NavigationViewTemplateSettings-OpenPaneLength.md b/specs/NavigationViewTemplateSettings-OpenPaneLength.md index 9041acd74f..db6bb4b47d 100644 --- a/specs/NavigationViewTemplateSettings-OpenPaneLength.md +++ b/specs/NavigationViewTemplateSettings-OpenPaneLength.md @@ -3,14 +3,14 @@ NavigationViewTemplateSettings.OpenPaneLength # Background -_This spec adds an `OpenPaneLength` property to the Xaml -[NavigationViewTemplateSettings](https://docs.microsoft.com//windows/winui/api/microsoft.ui.xaml.controls.navigationviewtemplatesettings) class_ +_This spec adds an `OpenPaneLength` property to the XAML +[NavigationViewTemplateSettings](https://learn.microsoft.com/windows/winui/api/microsoft.ui.xaml.controls.navigationviewtemplatesettings) class_ -The (existing) WinUI [NavigationView](https://docs.microsoft.com/uwp/api/Windows.UI.Xaml.Controls.NavigationView) control has +The (existing) WinUI [NavigationView](https://learn.microsoft.com/uwp/api/Windows.UI.Xaml.Controls.NavigationView) control has a list of items you can view, and a content area that shows the selected item. The list is shown in a pane that can be open, closed or partially open (compact). The exact width of the open pane can be specified using the -[NavigationView.OpenPaneLength](https://docs.microsoft.com/uwp/api/Windows.UI.Xaml.Controls.NavigationView.OpenPaneLength) +[NavigationView.OpenPaneLength](https://learn.microsoft.com/uwp/api/Windows.UI.Xaml.Controls.NavigationView.OpenPaneLength) property. Example of compact pane: @@ -33,9 +33,9 @@ it was previously a simple template binding to `NavigationView.OpenPaneLength` p in the original design it was envisioned that there woould be a vertical mode in the future, where this could represent a height too.) -TemplateSettings properties are not commonly used by app developers, +TemplateSettings properties are not commonly used by app developers, however, in situations when they copy a WinUI control's template into their own project, -there is a Xaml error when the TemplateSettings property is not public. +there is a XAML error when the TemplateSettings property is not public. See [issue #6682](https://github.com/microsoft/microsoft-ui-xaml/issues/6682) for more information on the error caused by non-public TemplateSettings. @@ -44,13 +44,13 @@ for more information on the error caused by non-public TemplateSettings. ## NavigationViewTemplateSettings.OpenPaneLength Gets the `min` between `OpenPaneLength` and the window's width. -This is the calculated value of the width of the pane when opened and fully expanded. Defaults to 320.0 in [view pixels](https://docs.microsoft.com/uwp/api/Windows.Graphics.Display.DisplayInformation.RawPixelsPerViewPixel) +This is the calculated value of the width of the pane when opened and fully expanded. Defaults to 320.0 in [view pixels](https://learn.microsoft.com/uwp/api/Windows.Graphics.Display.DisplayInformation.RawPixelsPerViewPixel) (Type: Double) This example shows the `OpenPaneLength` property being used in the `ControlTemplate` for `NavigationView` to pass through to the -[SplitView.OpenPaneLength](https://docs.microsoft.com/uwp/api/Windows.UI.Xaml.Controls.SplitView.OpenPaneLength). +[SplitView.OpenPaneLength](https://learn.microsoft.com/uwp/api/Windows.UI.Xaml.Controls.SplitView.OpenPaneLength). ```xml @@ -72,7 +72,8 @@ _Spec note: Usage available to view in this PR: [#7341](https://github.com/micro # API Details -```c# (but really MIDL3) +```csharp +// (but really MIDL3) [webhosthidden] unsealed runtimeclass NavigationViewTemplateSettings : Windows.UI.Xaml.DependencyObject { @@ -89,6 +90,6 @@ unsealed runtimeclass NavigationViewTemplateSettings : Windows.UI.Xaml.Dependenc The NavigationView pane is open when it is expanded to its full width. It is visible when the pane is shown - even in compact mode. -See [NavigationView.IsPaneOpen](https://docs.microsoft.com/windows/winui/api/microsoft.ui.xaml.controls.navigationview.ispaneopen) -and [NavigationView.IsPaneVisible](https://docs.microsoft.com/windows/winui/api/microsoft.ui.xaml.controls.navigationview.ispanevisible) +See [NavigationView.IsPaneOpen](https://learn.microsoft.com/windows/winui/api/microsoft.ui.xaml.controls.navigationview.ispaneopen) +and [NavigationView.IsPaneVisible](https://learn.microsoft.com/windows/winui/api/microsoft.ui.xaml.controls.navigationview.ispanevisible) for additional information on the distinction. diff --git a/specs/Popup-AdditionalLayoutProperties-Spec.md b/specs/Popup-AdditionalLayoutProperties-Spec.md index 660ac095c1..ca6031a769 100644 --- a/specs/Popup-AdditionalLayoutProperties-Spec.md +++ b/specs/Popup-AdditionalLayoutProperties-Spec.md @@ -3,26 +3,27 @@ Popup additional layout properties # Background -[Popups](https://docs.microsoft.com/uwp/api/Windows.UI.Xaml.Controls.Primitives.Popup) +[Popups](https://learn.microsoft.com/uwp/api/Windows.UI.Xaml.Controls.Primitives.Popup) and -[flyouts](https://docs.microsoft.com/uwp/api/Windows.UI.Xaml.Controls.Primitives.FlyoutBase) +[flyouts](https://learn.microsoft.com/uwp/api/Windows.UI.Xaml.Controls.Primitives.FlyoutBase) in XAML are given two modes of display: -* They can either appear as part of the rest of XAML, -in which case they're confined to the bounds of the XAML root, -* Or they can appear in their own HWND, which -allows them to escape the bounds of the XAML root. This is common for elements such as context menus. -[CommandBarFlyout](https://docs.microsoft.com/uwp/api/Windows.UI.Xaml.Controls.CommandBarFlyout) +- They can either appear as part of the rest of XAML, +in which case they're confined to the bounds of the XAML root, +- Or they can appear in their own HWND, which +allows them to escape the bounds of the XAML root. This is common for elements such as context menus. + +[CommandBarFlyout](https://learn.microsoft.com/uwp/api/Windows.UI.Xaml.Controls.CommandBarFlyout) is one such element, but since it's defined in the WinUI 2 controls library rather than in the OS, it does not -have access to the HWND used to allow it to escape the XAML root's bounds. As such, it has no way to +have access to the HWND used to allow it to escape the XAML root's bounds. As such, it has no way to determine which monitor it's being displayed in, which makes it unable to know whether it has enough visual space to open the popup for its secondary commands _below_ its primary commands or whether it should open them above instead. This new API adds three properties and an event to `Popup` which will allow apps to specify where it logically desires a popup to be displayed relative to another element, and then respond to where system XAML was able to actually place -the popup. This will allow elements such as `CommandBarFlyout` to be able to rely on system XAML for the placement of their +the popup. This will allow elements such as `CommandBarFlyout` to be able to rely on system XAML for the placement of their child popups in a way that will take monitor or app bounds into account without needing to do that accounting manually. ## Visual Examples @@ -41,7 +42,7 @@ Secondary commands flyout open: **Opening up** -When CommandBarFlyout does *not* have enough space below its primary commands, we want it to be able to open up. +When CommandBarFlyout does _not_ have enough space below its primary commands, we want it to be able to open up. Secondary commands flyout closed: @@ -70,10 +71,10 @@ class Popup } ``` -The example below shows how the `Placement` APIs are used by the -[CommandBarFlyout](https://docs.microsoft.com/uwp/api/Windows.UI.Xaml.Controls.CommandBarFlyout) +The example below shows how the `Placement` APIs are used by the +[CommandBarFlyout](https://learn.microsoft.com/uwp/api/Windows.UI.Xaml.Controls.CommandBarFlyout) to position its -[CommandBarFlyoutCommandBar](https://docs.microsoft.com/uwp/api/Windows.UI.Xaml.Controls.Primitives.CommandBarFlyoutCommandBar)'s +[CommandBarFlyoutCommandBar](https://learn.microsoft.com/uwp/api/Windows.UI.Xaml.Controls.Primitives.CommandBarFlyoutCommandBar)'s secondary commands Popup, and how to respond to the event raised when XAML places the Popup. ```xml @@ -116,23 +117,23 @@ Use this property to describe which element the `Popup` should be positioned rel Defaults to `null`. If this is `null`, then `DesiredPlacement` is ignored, `ActualPlacement` is always `Auto`, and -`ActualPlacementChanged` is never raised. If the `Popup` is in the visual tree, `PlacementTarget` will override what its -position would otherwise be set to by layout. Setting `PlacementTarget` to an element under a different XAML root than +`ActualPlacementChanged` is never raised. If the `Popup` is in the visual tree, `PlacementTarget` will override what its +position would otherwise be set to by layout. Setting `PlacementTarget` to an element under a different XAML root than `Popup.XamlRoot` is invalid and will throw an `ArgumentException`. Ignored if `DesiredPlacement` is `Auto`. _Spec note: this property is analogous to the -[FlyoutBase.Target](https://docs.microsoft.com/uwp/api/Windows.UI.Xaml.Controls.Primitives.FlyoutBase.Target) +[FlyoutBase.Target](https://learn.microsoft.com/uwp/api/Windows.UI.Xaml.Controls.Primitives.FlyoutBase.Target) property, but `Popup.Target` looked confusing, so we added the `Placement` prefix._ ## Popup.DesiredPlacement property Use this property to describe how you would ideally like the `Popup` -positioned relative to `PlacementTarget`. Defaults to `Auto`. +positioned relative to `PlacementTarget`. Defaults to `Auto`. If this is `Auto`, then `PlacementTarget` is ignored, -`ActualPlacement` is always `Auto` and `ActualPlacementChanged` is never raised. +`ActualPlacement` is always `Auto` and `ActualPlacementChanged` is never raised. If both `DesiredPlacement` and `PlacementTarget` are set and `HorizontalOffset` and/or `VerticalOffset` are also set, then the latter two properties will offset the `Popup` from where it would have been placed by `DesiredPlacement` and `PlacementTarget` alone. @@ -149,7 +150,7 @@ Will always be `Auto` if either `PlacementTarget` and `DesiredPlacement` are not Raised whenever XAML changes the value of `ActualPlacement`, which allows apps to respond to where a `Popup` was placed. -For example, use this to determine the visual state to go into, +For example, use this to determine the visual state to go into, based on whether a `Popup` is appearing above or below `PlacementTarget`. This event is raised before the screen is refreshed, meaning that any visual changes made @@ -159,8 +160,8 @@ Will never be raised if either `PlacementTarget` and `DesiredPlacement` are not ## PopupPlacementMode enum _Spec note: This is designed to align with the existing -[FlyoutPlacementMode](https://docs.microsoft.com/uwp/api/Windows.UI.Xaml.Controls.Primitives.FlyoutPlacementMode) -enum, with the exception of the absence of "Full". "Full" is absent since developers should use a Flyout +[FlyoutPlacementMode](https://learn.microsoft.com/uwp/api/Windows.UI.Xaml.Controls.Primitives.FlyoutPlacementMode) +enum, with the exception of the absence of "Full". "Full" is absent since developers should use a Flyout if they want something full-screen._ ```csharp @@ -183,7 +184,7 @@ enum PopupPlacementMode ``` _Spec note: The meaning of "Left" and "Right" are swapped if -[FlowDirection](https://docs.microsoft.com/en-us/uwp/api/windows.ui.xaml.frameworkelement.flowdirection) +[FlowDirection](https://learn.microsoft.com/uwp/api/windows.ui.xaml.frameworkelement.flowdirection) is `RightToLeft`._ # API Details diff --git a/specs/SystemBackdropElement_Spec.md b/specs/SystemBackdropElement_Spec.md index d21390b572..054f847ae8 100644 --- a/specs/SystemBackdropElement_Spec.md +++ b/specs/SystemBackdropElement_Spec.md @@ -3,26 +3,26 @@ SystemBackdropElement # Background -There are backdrop materials provided in WinUI such as Mica, Acrylic that are subclass of -[Microsoft.UI.Xaml.Media.SystemBackdrop](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.media.systembackdrop). Currently, it is possible to add a system backdrop only at the window level or on flyouts, but not in a specific area in the visual tree. This has been a major limitation on WinUI3 compared to WinUI2 in achieving the acrylic / mica effects, especially for achieving various animations. +There are backdrop materials provided in WinUI such as Mica, Acrylic that are subclass of +[Microsoft.UI.Xaml.Media.SystemBackdrop](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.media.systembackdrop). Currently, it is possible to add a system backdrop only at the window level or on flyouts, but not in a specific area in the visual tree. This has been a major limitation on WinUI 3 compared to WinUI 2 in achieving the acrylic / mica effects, especially for achieving various animations. `SystemBackdropElement` is a lightweight `FrameworkElement` that bridges between the XAML tree and the composition -infrastructure required by `SystemBackdrop`. It creates the required composition components to add the systembackdrop on a specific area, resizes the systembackdrop to fill the given area, and applies the clip on the backdrop visual based on `CornerRadius` values applied on `SystemBackdropElement` which helps for rounded corners +infrastructure required by `SystemBackdrop`. It creates the required composition components to add the systembackdrop on a specific area, resizes the systembackdrop to fill the given area, and applies the clip on the backdrop visual based on `CornerRadius` values applied on `SystemBackdropElement` which helps for rounded corners to appear as expected. This control abstracts lot of details for the composition layer and hence make it easy -for WinUI3 developers to implement the acrylic effect in the applications. +for WinUI 3 developers to implement the acrylic effect in the applications. -In WinUI2, it was possible to achieve the backdrop using `BackgroundSource` property of [AcrylicBrush](https://learn.microsoft.com/uwp/api/windows.ui.xaml.media.acrylicbrush?view=winrt-26100), However in WinUI3, [AcrylicBrush](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.media.acrylicbrush) doesn't provide `BackgroundSource` property leaving it capable of achieving only in-app acrylic. This is due to the limitation of WinUI3 compositor which is running in-proc, and so can't fetch buffers outside the application window. In this design, the solution is to leverage the [ContentExternalBackdropLink](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/microsoft.ui.content.contentexternalbackdroplink) API, It provides `PlacementVisual` that would be used for rendering the backdrop in the WinUI3 visual tree. `SystemBackdropElement` control takes care of resizing and positioning this `PlacementVisual` as per the position, size and Z-order of the control. +In WinUI 2, it was possible to achieve the backdrop using `BackgroundSource` property of [AcrylicBrush](https://learn.microsoft.com/uwp/api/windows.ui.xaml.media.acrylicbrush?view=winrt-26100), However in WinUI 3, [AcrylicBrush](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.media.acrylicbrush) doesn't provide `BackgroundSource` property leaving it capable of achieving only in-app acrylic. This is due to the limitation of WinUI 3 compositor which is running in-proc, and so can't fetch buffers outside the application window. In this design, the solution is to leverage the [ContentExternalBackdropLink](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/microsoft.ui.content.contentexternalbackdroplink) API. It provides `PlacementVisual` that would be used for rendering the backdrop in the WinUI 3 visual tree. `SystemBackdropElement` control takes care of resizing and positioning this `PlacementVisual` as per the position, size and Z-order of the control. ## Goals -* Provide an intuitive, XAML-friendly way to place a system backdrop anywhere inside application's visual tree. -* Handle connection, disconnection, and sizing so application only have to set a backdrop and position the element. -* Allow to put rounded corners on the backdrop without writing custom composition code. +- Provide an intuitive, XAML-friendly way to place a system backdrop anywhere inside application's visual tree. +- Handle connection, disconnection, and sizing so application only have to set a backdrop and position the element. +- Allow to put rounded corners on the backdrop without writing custom composition code. ## Non-goals -* Adding a SystemBackdrop property independently on all controls. -* Provide a content container; `SystemBackdropElement` is purely a visual effect surface and is not a container. +- Adding a SystemBackdrop property independently on all controls. +- Provide a content container; `SystemBackdropElement` is purely a visual effect surface and is not a container. # Conceptual pages (How To) @@ -31,7 +31,7 @@ The guidance in the below examples can be followed by developers for adopting # API Pages -_(Each level-two section below maps to a docs.microsoft.com API page.)_ +_Each of the following level-two sections correspond to a page that will be on learn.microsoft.com_ ## SystemBackdropElement class @@ -76,7 +76,8 @@ Keep the `SystemBackdropElement` in the bottom of the stack below other contents The same pattern works from code: -* C#: +- C#: + ```csharp var backdropElement = new SystemBackdropElement { @@ -86,7 +87,8 @@ var backdropElement = new SystemBackdropElement rootGrid.Children.Add(backdropElement); ``` -* C++: +- C++: + ```cpp winrt::Microsoft::UI::Xaml::Controls::SystemBackdropElement backdropElement; backdropElement.SystemBackdrop(winrt::Microsoft::UI::Xaml::Media::MicaBackdrop()); @@ -99,27 +101,27 @@ If a `CornerRadius` is applied on the parent `rootGrid`, that would clip the `Sy ### Remarks -* _Spec note: This API is currently `experimental`; the API surface may still change before it is finalized._ -* It is recommended to be used as first element for background effect to work appropriately, for example as the first child inside a +- _Spec note: This API is currently `experimental`; the API surface may still change before it is finalized._ +- It is recommended to be used as first element for background effect to work appropriately, for example as the first child inside a panel. (First element added to tree gets rendered first and goes in the bottom of stack) -* The `SystemBackdropElement` only connects to a backdrop while it has a `XamlRoot`. If the element is not in the live tree, the backdrop +- The `SystemBackdropElement` only connects to a backdrop while it has a `XamlRoot`. If the element is not in the live tree, the backdrop remains disconnected until it is loaded. -* As `SystemBackdropElement` control punch hole in the layout to show the SystemBackdrop, properties like Shadow, Lights, Clip & Transform may not behave as intended. +- As `SystemBackdropElement` control punches a hole in the layout to show the SystemBackdrop, properties like Shadow, Lights, Clip & Transform may not behave as intended. ## SystemBackdropElement.SystemBackdrop property Gets or sets the `SystemBackdrop` instance that renders in the `SystemBackdropElement` area. The default value is `null`. -* You can data bind this property. Typical values include `MicaBackdrop`, `DesktopAcrylicBackdrop`, or a +- You can data bind this property. Typical values include `MicaBackdrop`, `DesktopAcrylicBackdrop`, or a custom subclass of `SystemBackdrop`. -* If the `SystemBackdropElement` does not yet have a `XamlRoot`, the connection is postponed until one becomes available. +- If the `SystemBackdropElement` does not yet have a `XamlRoot`, the connection is postponed until one becomes available. ## SystemBackdropElement.CornerRadius property Gets or sets the `CornerRadius` applied to the backdrop surface. The default value of `CornerRadius` is 0. -* The `SystemBackdropElement` applies a `RectangleClip` on the composition visual of SystemBackdrop to achieve the rounded corners. -* Default `CornerRadius` value will be 0 aligning with [control templates](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.control.cornerradius#remarks) behavior. +- The `SystemBackdropElement` applies a `RectangleClip` on the composition visual of SystemBackdrop to achieve the rounded corners. +- Default `CornerRadius` value will be 0 aligning with [control templates](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.control.cornerradius#remarks) behavior. # API Details diff --git a/specs/api_spec_template.md b/specs/api_spec_template.md index 7c04a75c59..4b062874f9 100644 --- a/specs/api_spec_template.md +++ b/specs/api_spec_template.md @@ -1,2 +1,2 @@ Please use this template for new/modified APIs: -https://github.com/microsoft/WindowsAppSDK/blob/main/specs/spec_template.md + diff --git a/specs/appwindow-spec.md b/specs/appwindow-spec.md index b5be2b3110..68b6de86d2 100644 --- a/specs/appwindow-spec.md +++ b/specs/appwindow-spec.md @@ -1,83 +1,91 @@ -Window.AppWindow api +Window.AppWindow API === -New api to simplify accessing [appwindow](https://docs.microsoft.com/en-us/windows/apps/windows-app-sdk/windowing/windowing-overview) -functionality through WinUI 3 code + +New API to simplify accessing [AppWindow](https://learn.microsoft.com/windows/apps/windows-app-sdk/windowing/windowing-overview) +functionality through WinUI 3 code. # Background -Xaml has a [Window](https://docs.microsoft.com/uwp/api/Windows.UI.Xaml.Window) API that -internally wraps an hwnd. Windows has an [AppWindow](https://docs.microsoft.com/uwp/api/Windows.UI.WindowManagement.AppWindow) class -that similarly wraps an hwnd in UWP. WinAppSDK has a new [AppWindow](https://docs.microsoft.com/windows/windows-app-sdk/api/winrt/Microsoft.UI.Windowing.AppWindow) which wraps an hwnd and works on Desktop. -You can get an AppWindow from a Xaml Window by calling a COM API to get Xaml and then -a DLL export API to convert the hwnd to an AppWindow. This spec adds a simple `Window.AppWindow` +XAML has a [Window](https://learn.microsoft.com/uwp/api/Windows.UI.Xaml.Window) API that +internally wraps an HWND. Windows has an [AppWindow](https://learn.microsoft.com/uwp/api/Windows.UI.WindowManagement.AppWindow) class +that similarly wraps an HWND in UWP. WinAppSDK has a new [AppWindow](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/Microsoft.UI.Windowing.AppWindow) which wraps an HWND and works on Desktop. + +You can get an AppWindow from a XAML Window by calling a COM API to get XAML and then +a DLL export API to convert the HWND to an AppWindow. This spec adds a simple `Window.AppWindow` property to make this much easier and more discoverable. -[Xaml Window](https://docs.microsoft.com/en-us/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.window) will -expose AppWindow object directly to app developer through an api. Instead of writing a lot of boiler plate -code everywhere, app developer can use this api, reducing code bloat, and making appwindow apis easily +[XAML Window](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.window) will +expose AppWindow object directly to app developer through an API. Instead of writing a lot of boilerplate +code everywhere, app developer can use this API, reducing code bloat, and making AppWindow APIs easily accessible from WinUI 3 code. -These *before* and *after* C# code examples illustrate how this api simplifies integrating appwindow apis in WinUI 3 codebase. +These _before_ and _after_ C# code examples illustrate how this API simplifies integrating AppWindow APIs in WinUI 3 codebase. -### Before -```c# -// This is needed to get any Window from inside a Xaml control -var xamlWindow = WindowHelper.GetWindowForElement(this); // api to get window object from UIElement (not a real api) +- Before -// unnecessary boiler plate code +```csharp +// This is needed to get any Window from inside a XAML control +var xamlWindow = WindowHelper.GetWindowForElement(this); // API to get window object from UIElement (not a real API) + +// unnecessary boilerplate code var windowId = Win32Interop.GetWindowIdFromWindow(WindowNative.GetWindowHandle(xamlWindow)); var appWindow = AppWindow.GetFromWindowId(windowId); -//calling function foo (not a real appwindow function) +//calling function foo (not a real AppWindow function) appWindow.foo(); ``` -### After -```c# -// This is needed to get any Window from inside a Xaml control -var xamlWindow = WindowHelper.GetWindowForElement(this); // api to get window object from UIElement (not a real api) +- After + +```csharp +// This is needed to get any Window from inside a XAML control +var xamlWindow = WindowHelper.GetWindowForElement(this); // API to get window object from UIElement (not a real API)   //calling function foo directly xamlWindow.AppWindow.foo(); ``` -Notice how `xamlWindow.AppWindow.foo()` doesn't require additional steps to call the function `foo`. +Notice how `xamlWindow.AppWindow.foo()` doesn't require additional steps to call the function `foo`. # API Pages ## Window.AppWindow property Gets the `AppWindow` associated with this `Window`. -```c# + +```csharp public Microsoft.UI.Windowing.AppWindow Window.AppWindow { get; } ``` -### Sample example -```c# + +### Example + +```csharp var xamlWindow = WindowHelper.GetWindowForElement(this);  auto windowSize = xamlWindow.AppWindow.Size; ``` -Mapping an hwnd to an AppWindow causes the hwnd to be subclassed, meaning that the timing of -when [AppWindow.GetFromWindowId](https://docs.microsoft.com/windows/windows-app-sdk/api/winrt/Microsoft.UI.Windowing.AppWindow.GetFromWindowId) +Mapping an HWND to an AppWindow causes the HWND to be subclassed, meaning that the timing of +when [AppWindow.GetFromWindowId](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/Microsoft.UI.Windowing.AppWindow.GetFromWindowId) is first called can potentially have a behavioral side effect. To ensure this is predictable, the AppWindow -for Xaml's hwnd will be created during the Xaml Window's construction. Note that this could potentially be +for XAML's HWND will be created during the XAML Window's construction. Note that this could potentially be an observable behavior change from the behavior before the introduction of this API. New subclassing order with this new feature change: -* ContentAppWindowBridge - ↓ -* AppWindow - ↓ -* Xaml Window +- ContentAppWindowBridge
↓ -* DefaultWndProc - +- AppWindow +↓ +- XAML Window +↓ +- DefaultWndProc # API Details -```c# (but really MIDL3) +- MIDL3 + +```csharp namespace Microsoft.UI.Xaml { unsealed runtimeclass Window @@ -89,16 +97,13 @@ namespace Microsoft.UI.Xaml ``` # Appendix -- Window.AppWindow api returns reference to the same appwindow object every time. It gets created - during xaml window object's creation. There is minimal performance impact observed for this change. +- Window.AppWindow API returns reference to the same AppWindow object every time. It gets created + during XAML window object's creation. There is minimal performance impact observed for this change. - Since AppWindow is an abstraction for HWND, its lifetime will be same as that of HWND. The - api cannot return null as AppWindow will always be present if Window object is there. If called after - window has been closed, it will fail similarly to other WinUI 3 apis and return a failure HRESULT. - -- There will be only one appwindow object per top level HWND, created during Window object creation. - No new appwindow objects are created for child windows. - -- Future scope : Since this api is limited to top level HWND, there should be a way to get app window object - for top level HWND from one of its nested children HWND which doesn’t require app developer writing a lot of code. - + API cannot return null as AppWindow will always be present if Window object is there. If called after + window has been closed, it will fail similarly to other WinUI 3 APIs and return a failure HRESULT. +- There will be only one AppWindow object per top level HWND, created during Window object creation. + No new AppWindow objects are created for child windows. +- Future scope: Since this API is limited to top level HWND, there should be a way to get app window object + for top level HWND from one of its nested children HWND which doesn’t require app developer writing a lot of code. diff --git a/specs/custom-iresourcemanager-spec.md b/specs/custom-iresourcemanager-spec.md index 9d579de208..424a7fa3b5 100644 --- a/specs/custom-iresourcemanager-spec.md +++ b/specs/custom-iresourcemanager-spec.md @@ -4,40 +4,39 @@ Providing a custom MRT Core `IResourceManager` for WinUI 3 to use # Background The WinUI 3 framework instantiates an MRT Core -[`ResourceManager`](https://learn.microsoft.com/en-us/windows/windows-app-sdk/api/winrt/microsoft.windows.applicationmodel.resources.resourcemanager?view=windows-app-sdk-1.2) -in order to resolve resource URIs. While this default `ResourceManager` is generally sufficient, +[`ResourceManager`](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/microsoft.windows.applicationmodel.resources.resourcemanager?view=windows-app-sdk-1.2) +in order to resolve resource URIs. While this default `ResourceManager` is generally sufficient, there are some scenarios in which an app needs non-standard behavior in order to resolve a particular resource URI. In order to address this requirement, this document describes a new API that would allow an app to provide its own custom implementation of the -[`IResourceManager`](https://learn.microsoft.com/en-us/windows/windows-app-sdk/api/winrt/microsoft.windows.applicationmodel.resources.iresourcemanager?view=windows-app-sdk-1.2) +[`IResourceManager`](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/microsoft.windows.applicationmodel.resources.iresourcemanager?view=windows-app-sdk-1.2) interface for WinUI to use in lieu of its default `ResourceManager`. # API Pages -_(Each of the following L2 sections correspond to a page that will be on docs.microsoft.com)_ +_Each of the following level-two sections correspond to a page that will be on learn.microsoft.com_ ## Application.ResourceManagerRequested Event Raised during startup of a new WinUI thread to give the app a chance to provide its own -[`IResourceManager`](https://learn.microsoft.com/en-us/windows/windows-app-sdk/api/winrt/microsoft.windows.applicationmodel.resources.iresourcemanager?view=windows-app-sdk-1.2) +[`IResourceManager`](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/microsoft.windows.applicationmodel.resources.iresourcemanager?view=windows-app-sdk-1.2) implementation to be used by the framework for resolving resource URIs. -_Spec note: is there a version of the 'ResourceDictionary and XAML resource references' article that +_Spec note: is there a version of the 'ResourceDictionary and XAML resource references' article that links to the Windows App SDK documentation for relevant APIs?_ -```c# +```csharp public event TypedEventHandler ResourceManagerRequested - ``` ### Remarks -It is strongly recommended that apps which need to listen for this event register their handler in -their `App` class's constructor so that it is available during initial app launch as in the +It is strongly recommended that apps which need to listen for this event register their handler in +their `App` class's constructor so that it is available during initial app launch as in the following example. -```c# +```csharp public App() { this.InitializeComponent(); @@ -52,44 +51,41 @@ public App() } ``` -This event is raised once per WinUI thread during initialization. If you use the same +This event is raised once per WinUI thread during initialization. If you use the same `IResourceManager` for multiple threads, then the `IResourceManager` must be thread-safe. - - ## ResourceManagerRequestedEventArgs Class Provides event data for the `Application.ResourceManagerRequested` event. -```c# +```csharp public sealed class ResourceManagerRequestedEventArgs ``` ### Remarks -`ResourceManagerRequestedEventArgs` is used to provide the WinUI 3 framework with a custom -implementation of the -[`IResourceManager`](https://learn.microsoft.com/en-us/windows/windows-app-sdk/api/winrt/microsoft.windows.applicationmodel.resources.iresourcemanager?view=windows-app-sdk-1.2) -interface to be used for resolving resource URIs rather than the default `ResourceManager` that the -framework creates. In the event handler, you should instantiate your custom `IResourceManager` and -assign it to the `ResourceManagerRequestedEventArgs.CustomResourceManager` property. The value of this -property is initially `null`, and it is only checked by the framework once per event raise after -all registered event handlers have been invoked. If the property value is still `null` then the +`ResourceManagerRequestedEventArgs` is used to provide the WinUI 3 framework with a custom +implementation of the +[`IResourceManager`](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/microsoft.windows.applicationmodel.resources.iresourcemanager?view=windows-app-sdk-1.2) +interface to be used for resolving resource URIs rather than the default `ResourceManager` that the +framework creates. In the event handler, you should instantiate your custom `IResourceManager` and +assign it to the `ResourceManagerRequestedEventArgs.CustomResourceManager` property. The value of this +property is initially `null`, and it is only checked by the framework once per event raise after +all registered event handlers have been invoked. If the property value is still `null` then the framework will use the default `ResourceManager`. - ## ResourceManagerRequestedEventArgs.CustomResourceManager Property -Sets the custom `IResourceManager` that should be used by WinUI to resolve MRT resources for the +Sets the custom `IResourceManager` that should be used by WinUI to resolve MRT resources for the current thread. If you leave the value `null` then the default `ResourceManager` will be used. -```c# +```csharp public IResourceManager ResourceManager { get; set; } ``` - # API Details -```c# + +```csharp namespace Microsoft.UI.Xaml { runtimeclass Application @@ -105,6 +101,4 @@ namespace Microsoft.UI.Xaml IResourceManager CustomResourceManager; }; } - ``` - diff --git a/specs/public-api-review-process.md b/specs/public-api-review-process.md index db35888b63..134e0c5fed 100644 --- a/specs/public-api-review-process.md +++ b/specs/public-api-review-process.md @@ -1,106 +1,105 @@ -WinUI Platform Public Spec Review Process +WinUI Platform Public Spec Review Process === ## Introduction + We are excited to formally re-introduce a community feedback process to our API authoring workflow! This will leverage the collective wisdom and insights of the community, allowing us to develop more robust and comprehensive APIs that meet the needs of our diverse user base. We assure our community that their input is invaluable to us, and we are dedicated to fostering a transparent and collaborative environment. By adopting this structured feedback process outlined below, we aim to set clear expectations and handle all contributions with the utmost professionalism and consideration. - ## Public Post on Github -- The drafted spec from is posted as a PR under the `./specs/` directory. - - Example PR: [Popup placement properties API spec](https://github.com/microsoft/microsoft-ui-xaml/pull/4905) - - Every spec will link to this public spec markdown file. -- A dedicated discussion thread will be created to announce that we are actively gathering feedback for the API. -- A Github issue with `spec-review` tag will be created to represent the new API proposal. It will be tracked in the Github API Spec Review Board: - - > [API Specs Review](https://github.com/orgs/microsoft/projects/1328/views/1) +- The drafted spec from is posted as a PR under the `./specs/` directory. + + - Example PR: [Popup placement properties API spec](https://github.com/microsoft/microsoft-ui-xaml/pull/4905) + - Every spec will link to this public spec markdown file. +- A dedicated discussion thread will be created to announce that we are actively gathering feedback for the API. +- A Github issue with `spec-review` tag will be created to represent the new API proposal. It will be tracked in the Github API Spec Review Board: - - If the proposed API addresses any existing Github issues, the existing issue will be linked to the `spec-review` issue representing the API proposal. +> [API Specs Review](https://github.com/orgs/microsoft/projects/1328/views/1) + +- If the proposed API addresses any existing Github issues, the existing issue will be linked to the `spec-review` issue representing the API proposal. ## Gather Feedback -The issue is open for a predefined period of **1 month** to gather feedback from the community. + +The issue is open for a predefined period of **1 month** to gather feedback from the community. The start and end dates will be outlined in the spec and in the [API Specs Review](https://github.com/orgs/microsoft/projects/1328/views/1) Board. - Community members can provide feedback by **commenting directly on the PR**, or through a **code suggestion** with Github tools. -- Feedback should be constructive and specific, addressing potential use cases, design concerns, and functionality. +- Feedback should be constructive and specific, addressing potential use cases, design concerns, and functionality. > **Examples of constructive feedback:** > -> - Developer use cases and edge cases – sample code and screenshots of such scenarios are very much welcomed. +> - Developer use cases and edge cases – sample code and screenshots of such scenarios are very much welcomed. > -> - ~~Don't: "You should use a ToggleButton and have it to the left"~~ -> - Do: "Can I customize the content here? Here is some code and screenshots showcasing my needed scenario.” +> - ~~Don't: "You should use a ToggleButton and have it to the left"~~ +> - Do: "Can I customize the content here? Here is some code and screenshots showcasing my needed scenario.” > -> - Consistent API naming conventions – and comparisons of said APIs across WinUI and industry standards. +> - Consistent API naming conventions – and comparisons of said APIs across WinUI and industry standards. > > - ~~Don't: "This is a bad name, it should be called something different."~~ -> - Do: "Normally, these types of properties are named IsFoo, like IsFoo on X's BarControl. < link to learn.microsoft.com API property page or other framework's documentation />" +> - Do: "Normally, these types of properties are named IsFoo, like IsFoo on X's BarControl. < link to learn.microsoft.com API property page or other framework's documentation />" +> +> - Raised accessibility concerns and use cases > -> - Raised accessibility concerns and use cases -> > - ~~Don't: "This control is not accessible."~~ > - Do: "How does this control support screen readers? Here is an example of how it should announce state changes to ensure accessibility." -> - Raised usability concerns with different languages -> -> - ~~Don't: "This won't work support other languages."~~ -> - Do: “How will the control layout handle RTL languages? Here is an example of what could appear on the control.” +> - Raised usability concerns with different languages > -> - Inquiries and suggestions regarding scenarios and usages +> - ~~Don't: "This won't work support other languages."~~ +> - Do: “How will the control layout handle RTL languages? Here is an example of what could appear on the control.” > -> - ~~Don't: "This control is missing features."~~ -> - Do: “Does it have an orientation property to toggle horizontal and vertical? Here is an example of how this property can be used in different scenarios.” - -## Handle Feedback +> - Inquiries and suggestions regarding scenarios and usages +> +> - ~~Don't: "This control is missing features."~~ +> - Do: “Does it have an orientation property to toggle horizontal and vertical? Here is an example of how this property can be used in different scenarios.” -We are commited to respond to all feedback in different manners depending on the feedback category. +## Handle Feedback -**Feedback categorization:** In general, feedback will be prioritized into the categories below based on relevance, impact, and feasibility. +We are committed to respond to all feedback in different manners depending on the feedback category. -- **Immediate Action:** Feedback that will be addressed in the current specification iteration due to its high relevance and feasibility. -- **Deferred Action:** Feedback that is valuable but not feasible for immediate implementation. This will be considered for future updates. -- **Not Planned:** Feedback that is not aligned with current goals or is not feasible to implement. Reasons for this will be clearly communicated. -- **Discussion:** Feedback is an open-ended discussion, and no immediate action is necessary. +**Feedback categorization:** In general, feedback will be prioritized into the categories below based on relevance, impact, and feasibility. -
+- **Immediate Action:** Feedback that will be addressed in the current specification iteration due to its high relevance and feasibility. +- **Deferred Action:** Feedback that is valuable but not feasible for immediate implementation. This will be considered for future updates. +- **Not Planned:** Feedback that is not aligned with current goals or is not feasible to implement. Reasons for this will be clearly communicated. +- **Discussion:** Feedback is an open-ended discussion, and no immediate action is necessary. -**Acknowledgment:** All feedback will be acknowledged by at least one of the following means: +**Acknowledgment:** All feedback will be acknowledged by at least one of the following means: - **Immediate & Deferred Action:** - - Final post calling out specific points that influenced decisions + - Final post calling out specific points that influenced decisions *and / or* - - In-line response to comments + - In-line response to comments *and / or* - - “Resolve comment” to signify that the feedback has been incorporated into the spec draft + - “Resolve comment” to signify that the feedback has been incorporated into the spec draft *and / or* - - Directly commit the suggestion if it is done via code suggestion with Github tools, and it is appropriate + - Directly commit the suggestion if it is done via code suggestion with Github tools, and it is appropriate -- **Not Planned:** +- **Not Planned:** - - In-line response to comments explaining reasoning + - In-line response to comments explaining reasoning *and* - - “Resolve comment” to signify that it is not planned + - “Resolve comment” to signify that it is not planned - **Discussion:** - - A “eye” emoji by the author / poster to signify that it is read. + - An “eye” emoji by the author / poster to signify that it is read. ## Consolidate Feedback We will carefully consider each contribution and update the spec to reflect the accepted feedback. A summary of changes will be shared, highlighting each significant feedback point. Finally, the PR containing the final spec is merged in. +### Passive Monitoring of Relevant Feedback and Issues -### Passive Monitoring of Relevant Feedback and Issues - -- Continuous monitoring for any late feedback or issues is passively maintained. -- Future enhancements or changes based on post-implementation feedback are considered in subsequent spec reviews. \ No newline at end of file +- Continuous monitoring for any late feedback or issues is passively maintained. +- Future enhancements or changes based on post-implementation feedback are considered in subsequent spec reviews. diff --git a/specs/xaml-backdrop-api.md b/specs/xaml-backdrop-api.md index a78323d9f2..9600d24e8a 100644 --- a/specs/xaml-backdrop-api.md +++ b/specs/xaml-backdrop-api.md @@ -1,39 +1,36 @@ - - -Xaml Backdrop APIs +XAML Backdrop APIs === # Background Composition in WinAppSDK has a general -[ISystemBackdropController](https://docs.microsoft.com/windows/windows-app-sdk/api/winrt/Microsoft.UI.Composition.SystemBackdrops.ISystemBackdropController) +[ISystemBackdropController](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/Microsoft.UI.Composition.SystemBackdrops.ISystemBackdropController) interface that's concretely implemented by -[MicaController](https://docs.microsoft.com/windows/windows-app-sdk/api/winrt/Microsoft.UI.Composition.SystemBackdrops.MicaController) -and [DesktopAcrylicController](https://docs.microsoft.com/windows/windows-app-sdk/api/winrt/Microsoft.UI.Composition.SystemBackdrops.DesktopAcrylicController). +[MicaController](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/Microsoft.UI.Composition.SystemBackdrops.MicaController) +and [DesktopAcrylicController](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/Microsoft.UI.Composition.SystemBackdrops.DesktopAcrylicController). A backdrop is a visual effect you can use as the background for your window (or island). For example the Desktop Acrylic backdrop lets you set as the background of your window the desktop wallpaper behind it, but visually modified. -[More info](https://learn.microsoft.com/en-us/windows/apps/design/style/acrylic). +[More info](https://learn.microsoft.com/windows/apps/design/style/acrylic). These existing Mica and Desktop Acrylic controllers allow you to set the backdrops onto a -[WindowId](https://docs.microsoft.com/windows/windows-app-sdk/api/winrt/Microsoft.UI.WindowId), -and there's currently only an awkward way to get a `WindowId` from a Xaml object such as -[Window](https://docs.microsoft.com/windows/windows-app-sdk/api/winrt/Microsoft.UI.Xaml.Window). +[WindowId](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/Microsoft.UI.WindowId), +and there's currently only an awkward way to get a `WindowId` from a XAML object such as +[Window](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/Microsoft.UI.Xaml.Window). The awkwardness only begins there; you also need to work with a _system_ -[DispatcherQueue](https://docs.microsoft.com/uwp/api/Windows.System.DispatcherQueue), +[DispatcherQueue](https://learn.microsoft.com/uwp/api/Windows.System.DispatcherQueue), coordinate with the -[Loaded](https://docs.microsoft.com/windows/windows-app-sdk/api/winrt/Microsoft.UI.Xaml.FrameworkElement.Loaded) +[Loaded](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/Microsoft.UI.Xaml.FrameworkElement.Loaded) event, and check -[IsSupported](https://docs.microsoft.com/windows/windows-app-sdk/api/winrt/Microsoft.UI.Composition.SystemBackdrops.MicaController.IsSupported) +[IsSupported](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/Microsoft.UI.Composition.SystemBackdrops.MicaController.IsSupported) to see if you need to provide a fallback (Mica isn't supported on Windows 10). So it's a great feature and works, but it's difficult to use. -[Here's a full code example of the current solution](https://learn.microsoft.com/en-us/windows/apps/windows-app-sdk/system-backdrop-controller#example-use-mica-in-a-windows-appsdkwinui-3-app). +Here's a [full code example of the current solution](https://learn.microsoft.com/windows/apps/windows-app-sdk/system-backdrop-controller#example-use-mica-in-a-windows-appsdkwinui-3-app). -The purpose of the new APIs here are to make backdrops much easier to use in a Xaml app, +The purpose of the new APIs here are to make backdrops much easier to use in a XAML app, allowing you to simply set a backdrop as a property on a `Window`. - # API Pages ## Window.SystemBackdrop property @@ -72,7 +69,6 @@ The following example creates a Window with a Mica backdrop. ``` - ## MicaBackdrop class _Same description applies to `DesktopAcrylicBackdrop` class_ @@ -80,10 +76,11 @@ _Same description applies to `DesktopAcrylicBackdrop` class_ _See also the base class: `SystemBackdrop`_ Use this class to set a backdrop on a -[Window](https://docs.microsoft.com/windows/windows-app-sdk/api/winrt/Microsoft.UI.Xaml.Window), -[Popup](https://docs.microsoft.com/windows/windows-app-sdk/api/winrt/Microsoft.UI.Xaml.Controls.Primitives.Popup)\*, -or [FlyoutBase](https://docs.microsoft.com/windows/windows-app-sdk/api/winrt/Microsoft.UI.Xaml.Controls.Primitives.FlyoutBase)\* (such as a `Flyout` or `MenuFlyout`). -* `Popup`/`MenuFlyout` `SystemBackdrop` support is not available in WinAppSDK 1.3.0, but is expected to light up in a subsequent release. Note also `SystemBackdrop` will only work in "windowed" popups, i.e. those with *ShouldConstrainToRootBounds=False*. +[Window](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/Microsoft.UI.Xaml.Window), +[Popup](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/Microsoft.UI.Xaml.Controls.Primitives.Popup)\*, +or [FlyoutBase](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/Microsoft.UI.Xaml.Controls.Primitives.FlyoutBase)\* (such as a `Flyout` or `MenuFlyout`). + +- `Popup`/`MenuFlyout` `SystemBackdrop` support is not available in WinAppSDK 1.3.0, but is expected to light up in a subsequent release. Note also `SystemBackdrop` will only work in "windowed" popups, i.e. those with _ShouldConstrainToRootBounds=False_. For example: @@ -97,25 +94,23 @@ For example: ``` -Note that `MicaBackdrop` isn't supported on all systems. -In such cases a solid color will be used instead of the Mica effect. - +> [!NOTE] +> Note that `MicaBackdrop` isn't supported on all systems. In such cases a solid color will be used instead of the Mica effect. ## SystemBackdrop class Use this class to create a custom system backdrop. You don't create this class directly, but subclass it to add your custom support (note the protected constructor). This class is the base of built-in backdrop materials `MicaBackdrop` and `DesktopAcrylicBackdrop`. -Generally, the custom material overrides `OnTargetConnected` to create and configure a backing [ISystemBackdropController](https://learn.microsoft.com/en-us/windows/windows-app-sdk/api/winrt/microsoft.ui.composition.systembackdrops.isystembackdropcontroller?view=windows-app-sdk-1.3), which will manage the [CompositionBrush](https://learn.microsoft.com/en-us/windows/windows-app-sdk/api/winrt/microsoft.ui.composition.compositionbrush?view=windows-app-sdk-1.3) used to fill the backdrop region. The brush's ultimate pixel rendering is affected by the environment/policy (set via [SystemBackdropConfiguration](https://learn.microsoft.com/en-us/windows/windows-app-sdk/api/winrt/microsoft.ui.composition.systembackdrops.systembackdropconfiguration?view=windows-app-sdk-1.3)) and material's appearence parameters, exposed via general (eg `ICompositionControllerWithTargets.SystemBackdropState` ∈ { _`Active` / `Fallback` / `HighContast`_ }) and material-specfic (eg `MicaController.Kind` ∈ { _`Base` / `BaseAlt`_} _SystemBackdropController_ properties. +Generally, the custom material overrides `OnTargetConnected` to create and configure a backing [ISystemBackdropController](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/microsoft.ui.composition.systembackdrops.isystembackdropcontroller?view=windows-app-sdk-1.3), which will manage the [CompositionBrush](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/microsoft.ui.composition.compositionbrush?view=windows-app-sdk-1.3) used to fill the backdrop region. The brush's ultimate pixel rendering is affected by the environment/policy (set via [SystemBackdropConfiguration](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/microsoft.ui.composition.systembackdrops.systembackdropconfiguration?view=windows-app-sdk-1.3)) and material's appearance parameters, exposed via general (eg `ICompositionControllerWithTargets.SystemBackdropState` ∈ { _`Active` / `Fallback` / `HighContast`_ }) and material-specfic (eg `MicaController.Kind` ∈ { _`Base` / `BaseAlt`_} _SystemBackdropController_ properties. -* The controllers available today (`MicaController` and `DesktopAcrylicContoller`) support the following parameters for customizing their appearence: [FallbackColor](https://learn.microsoft.com/en-us/windows/windows-app-sdk/api/winrt/microsoft.ui.composition.systembackdrops.desktopacryliccontroller.fallbackcolor?view=windows-app-sdk-1.3), [LuminosityOpacity](https://learn.microsoft.com/en-us/windows/windows-app-sdk/api/winrt/microsoft.ui.composition.systembackdrops.desktopacryliccontroller.luminosityopacity?view=windows-app-sdk-1.3), [TintColor](https://learn.microsoft.com/en-us/windows/windows-app-sdk/api/winrt/microsoft.ui.composition.systembackdrops.micacontroller.tintcolor?view=windows-app-sdk-1.3), and [TintOpacity](https://learn.microsoft.com/en-us/windows/windows-app-sdk/api/winrt/microsoft.ui.composition.systembackdrops.micacontroller.tintopacity?view=windows-app-sdk-1.3). -* The provided Xaml backdrop materials `MicaBackdrop` and `DesktopAcrylicBackdrop` currently do not expose `FallbackColor` or the material customization properties (`TintOpacity`, etc), instead relying on the default Light/Dark configurations of the underlying `MicaController` and `DesktopAcrylicController`. To customize these properties, createa a custom material class deriving from SystemBackdrop that exposes the desired properties. +- The controllers available today (`MicaController` and `DesktopAcrylicController`) support the following parameters for customizing their appearance: [FallbackColor](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/microsoft.ui.composition.systembackdrops.desktopacryliccontroller.fallbackcolor?view=windows-app-sdk-1.3), [LuminosityOpacity](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/microsoft.ui.composition.systembackdrops.desktopacryliccontroller.luminosityopacity?view=windows-app-sdk-1.3), [TintColor](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/microsoft.ui.composition.systembackdrops.micacontroller.tintcolor?view=windows-app-sdk-1.3), and [TintOpacity](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/microsoft.ui.composition.systembackdrops.micacontroller.tintopacity?view=windows-app-sdk-1.3). +- The provided XAML backdrop materials `MicaBackdrop` and `DesktopAcrylicBackdrop` currently do not expose `FallbackColor` or the material customization properties (`TintOpacity`, etc), instead relying on the default Light/Dark configurations of the underlying `MicaController` and `DesktopAcrylicController`. To customize these properties, createa a custom material class deriving from SystemBackdrop that exposes the desired properties. The following example shows a simple custom system backdrop class that's implemented using -[MicaController](https://docs.microsoft.com/windows/windows-app-sdk/api/winrt/Microsoft.UI.Composition.SystemBackdrops.MicaController). +[MicaController](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/Microsoft.UI.Composition.SystemBackdrops.MicaController). - -```cs +```csharp public class MicaSystemBackdrop : SystemBackdrop { MicaController _micaController; @@ -165,39 +160,38 @@ public class MicaSystemBackdrop : SystemBackdrop ## SystemBackdrop.GetDefaultSystemBackdropConfiguration method -Returns a default -[SystemBackdropConfiguration](https://docs.microsoft.com/windows/windows-app-sdk/api/winrt/Microsoft.UI.Composition.SystemBackdrops.SystemBackdropConfiguration) +Returns a default +[SystemBackdropConfiguration](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/Microsoft.UI.Composition.SystemBackdrops.SystemBackdropConfiguration) object that is set and maintained automatically for each `SystemBackdrop` usage context (i.e `connectedTarget`), and can be passed to -[ISystemBackdropControllerWithTargets.SetSystemBackdropConfiguration](https://docs.microsoft.com/windows/windows-app-sdk/api/winrt/Microsoft.UI.Composition.SystemBackdrops.ISystemBackdropControllerWithTargets.SetSystemBackdropConfiguration) to apply the default policy. +[ISystemBackdropControllerWithTargets.SetSystemBackdropConfiguration](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/Microsoft.UI.Composition.SystemBackdrops.ISystemBackdropControllerWithTargets.SetSystemBackdropConfiguration) to apply the default policy. The properties on `SystemBackdropConfiguration` you receive may change over time: -* `Theme`: set based on [ElementTheme](https://docs.microsoft.com/uwp/api/Windows.UI.Xaml.ElementTheme) of the target element (obtained from xamlRoot.Content) - * If `FallbackColor`, `LuminosityOpacity`, `TintColor`, or `TintOpacity` are modified by the material's implementation, changes to associated [SystemBackdropConfiguration.Theme](https://learn.microsoft.com/en-us/windows/windows-app-sdk/api/winrt/microsoft.ui.composition.systembackdrops.systembackdropconfiguration.theme?view=windows-app-sdk-1.3) will no longer automatically toggle the controller's theme (since default Dark and Light configurations are no longer apopropriate). In this case, the material's appearence properties need to be manually updated to match the new Theme in `SystemBackdrop.OnDefaultSystemBackdropConfigurationChanged`. - -* `IsInputActive`: true if the target of the `SystemBackdrop` is in the active window. +- `Theme`: set based on [ElementTheme](https://learn.microsoft.com/uwp/api/Windows.UI.Xaml.ElementTheme) of the target element (obtained from xamlRoot.Content) + - If `FallbackColor`, `LuminosityOpacity`, `TintColor`, or `TintOpacity` are modified by the material's implementation, changes to associated [SystemBackdropConfiguration.Theme](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/microsoft.ui.composition.systembackdrops.systembackdropconfiguration.theme?view=windows-app-sdk-1.3) will no longer automatically toggle the controller's theme (since default Dark and Light configurations are no longer appropriate). In this case, the material's appearance properties need to be manually updated to match the new Theme in `SystemBackdrop.OnDefaultSystemBackdropConfigurationChanged`. -* `IsHighContrast`: true if the target of the `SystemBackdrop` is in high contrast mode. +- `IsInputActive`: true if the target of the `SystemBackdrop` is in the active window. +- `IsHighContrast`: true if the target of the `SystemBackdrop` is in high contrast mode. ## SystemBackdrop.OnDefaultSystemBackdropConfigurationChanged virtual protected method -Override this method to be called when one of the properrties (described above) on the object returned by `GetDefaultSystemBackdropConfiguration` has changed. +Override this method to be called when one of the properties (described above) on the object returned by `GetDefaultSystemBackdropConfiguration` has changed. -* This is useful when implementing a custom `SystemBackdropConfiguration` that incorporates some of the tracked property states but is different in some way from the default policy. First, obtain a `SystemBackdropConfiguration` object from `GetDefaultSystemBackdropConfiguration` as usual, but do not apply it via `CompositionContoller.SetSystemBackdropConfiguration`. Instead create an additional `SystemBackdropConfiguration` object that is updated on `OnDefaultSystemBackdropConfigurationChanged` by applying custom logic to the tracked property (eg ignoring Theme change). The second `SystemBackdropConfiguration` object is hooked up to `CompositionContoller.SetSystemBackdropConfiguration`, applying the custom policy. +- This is useful when implementing a custom `SystemBackdropConfiguration` that incorporates some of the tracked property states but is different in some way from the default policy. First, obtain a `SystemBackdropConfiguration` object from `GetDefaultSystemBackdropConfiguration` as usual, but do not apply it via `CompositionController.SetSystemBackdropConfiguration`. Instead create an additional `SystemBackdropConfiguration` object that is updated on `OnDefaultSystemBackdropConfigurationChanged` by applying custom logic to the tracked property (eg ignoring Theme change). The second `SystemBackdropConfiguration` object is hooked up to `CompositionController.SetSystemBackdropConfiguration`, applying the custom policy. ## Other `SystemBackdrop` members | Member | Description | -| - | - | +| --- | --- | | `OnTargetConnected` virtual method | Called when this object is attached to a valid container, for example when set on `Window.SystemBackdrop`. Override to create and configure the underlying `CompositionController` and its `SystemBackdropConfiguration`. | | `OnTargetDisconnected` virtual method | Called when this object is cleared from its container | - - # API Details -```c# (but really MIDL3) +- MIDL3 + +```csharp namespace Microsoft.UI.Xaml.Media { [contract(Microsoft.UI.Xaml.WinUIContract, 4)] @@ -293,4 +287,3 @@ namespace Microsoft.UI.Xaml.Controls.Primitives } ``` - diff --git a/specs/xaml-resource-references-tracing-spec.md b/specs/xaml-resource-references-tracing-spec.md index 49c3a1232c..d540557563 100644 --- a/specs/xaml-resource-references-tracing-spec.md +++ b/specs/xaml-resource-references-tracing-spec.md @@ -3,13 +3,13 @@ Tracing XAML resource reference lookup failures # Background -A XAML resource is an item in a -[ResourceDictionary](https://docs.microsoft.com/windows/windows-app-sdk/api/winrt/Microsoft.UI.Xaml.ResourceDictionary) +A XAML resource is an item in a +[ResourceDictionary](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/Microsoft.UI.Xaml.ResourceDictionary) that can be referenced in markup with a `{StaticResource}` or `{ThemeResource}` reference. For example: ```xml - + @@ -17,36 +17,33 @@ For example: ``` -`ResourceDictionary`s can be defined in multiple places, so the resource reference is resolved -as a search. +`ResourceDictionary`s can be defined in multiple places, so the resource reference is resolved as a search. -Failure to resolve a XAML resource reference is one of -the most common causes of app crashes. Such failures manifest in the _native code_ debug output with the -message "Cannot find a Resource with the Name/Key *foo*", and generally fall into one of two +Failure to resolve a XAML resource reference is one of +the most common causes of app crashes. Such failures manifest in the _native code_ debug output with the +message "Cannot find a Resource with the Name/Key _foo_", and generally fall into one of two buckets: -1. The referenced resource legitimately does not exist, e.g. the referenced key is misspelled or +1. The referenced resource legitimately does not exist, e.g. the referenced key is misspelled or the intended matching resource has not been added to the app. -2. The referenced resource *does* exist in the app, but it is not reachable from the reference +2. The referenced resource _does_ exist in the app, but it is not reachable from the reference at run-time. -Unfortunately, the stowed exception message is the *only* information provided about the error, +Unfortunately, the stowed exception message is the _only_ information provided about the error, which makes it difficult or, more often, outright impossible to debug. -This spec describes a new -API on the `DebugSettings` class that developers can use to access more detailed information about +This spec describes a new API on the `DebugSettings` class that developers can use to access more detailed information about the resource reference lookup failure. The new APIs here are patterned after the existing -[DebugSettings.BindingFailed](https://docs.microsoft.com/windows/windows-app-sdk/api/winrt/Microsoft.UI.Xaml.DebugSettings.BindingFailed) +[DebugSettings.BindingFailed](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/Microsoft.UI.Xaml.DebugSettings.BindingFailed) and -[DebugSettings.IsBindingTracingEnabled](https://docs.microsoft.com/windows/windows-app-sdk/api/winrt/Microsoft.UI.Xaml.DebugSettings.IsBindingTracingEnabled) +[DebugSettings.IsBindingTracingEnabled](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/Microsoft.UI.Xaml.DebugSettings.IsBindingTracingEnabled) APIs. - # API Pages -_(Updates to the -[DebugSettings](https://docs.microsoft.com/windows/windows-app-sdk/api/winrt/Microsoft.UI.Xaml.DebugSettings) +_(Updates to the +[DebugSettings](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/Microsoft.UI.Xaml.DebugSettings) class)_ ## DebugSettings.XamlResourceReferenceFailed Event @@ -55,18 +52,17 @@ Occurs when a [XAML resource reference](https://learn.microsoft.com/en-us/windows/apps/design/style/xaml-resource-dictionary) cannot be resolved. -_Spec note: This API is similar to the `DebugSettings.BindingFailed` event. Like XAML resource references, -Bindings cannot be modeled solely through static evaluation, e.g. at compile-time, and so a run-time -event when a failure occurs is the best approach for providing developers with a means of determining the +_Spec note: This API is similar to the `DebugSettings.BindingFailed` event. Like XAML resource references, +Bindings cannot be modeled solely through static evaluation, e.g. at compile-time, and so a run-time +event when a failure occurs is the best approach for providing developers with a means of determining the root cause._ -_Spec note: is there a version of the 'ResourceDictionary and XAML resource references' article that +_Spec note: is there a version of the 'ResourceDictionary and XAML resource references' article that links to the Windows App SDK documentation for relevant APIs?_ -```c# +```csharp public event TypedEventHandler XamlResourceReferenceFailed - ``` ### Remarks @@ -74,7 +70,7 @@ XamlResourceReferenceFailed `IsXamlResourceReferenceTracingEnabled` must be `true` in order for this event to be raised. Error information is also logged to the native debug output when the event is raised, -so attaching a `XamlResourceReferenceFailed` handler yourself is an advanced scenario for +so attaching a `XamlResourceReferenceFailed` handler yourself is an advanced scenario for getting the raw message programmatically. ## DebugSettings.IsXamlResourceReferenceTracingEnabled Property @@ -83,40 +79,39 @@ Gets or sets a value indicating that when a XAML resource reference error occurs the `XamlResourceReferenceFailed` event should be raised, and error information should be logged in the native debug output. -```c# +```csharp public bool IsXamlResourceReferenceTracingEnabled { get; set; } ``` ### Remarks -This property is `true` by default. When XAML resource reference tracing is enabled and you -run your app with the native debugger attached, any XAML resource reference errors appear +This property is `true` by default. When XAML resource reference tracing is enabled and you +run your app with the native debugger attached, any XAML resource reference errors appear in the **Output** window in Microsoft Visual Studio. - ## XamlResourceReferenceFailedEventArgs Class Provides event data for the `DebugSettings.XamlResourceReferenceFailed` event. -```c# +```csharp public sealed class XamlResourceReferenceFailedEventArgs ``` ### Remarks -`XamlResourceReferenceFailedEventArgs` is used for debugging XAML resource references. Register the event -handler using `DebugSettings`. It will receive a reference to this class. You'll mainly be +`XamlResourceReferenceFailedEventArgs` is used for debugging XAML resource references. Register the event +handler using `DebugSettings`. It will receive a reference to this class. You'll mainly be interested in the `Message` value, which you could log or send to **Debug** output. -The message in the event data contains the following information about the failed XAML resource +The message in the event data contains the following information about the failed XAML resource reference: -* The URI of the XAML page containing each `ResourceDictionary` that was searched -* The order in which the `ResourceDictionary`s were searched +- The URI of the XAML page containing each `ResourceDictionary` that was searched +- The order in which the `ResourceDictionary`s were searched -You can use this information to investigate why the XAML resource reference could not be resolved; -perhaps the `ResourceDictionary` it is contained in was not in the list of searched -`ResourceDictionary`s, or perhaps that `ResourceDictionary` was searched which could indicate that +You can use this information to investigate why the XAML resource reference could not be resolved; +perhaps the `ResourceDictionary` it is contained in was not in the list of searched +`ResourceDictionary`s, or perhaps that `ResourceDictionary` was searched which could indicate that an incorrect resource key was specified. Below is an example message from the WinUI Gallery sample app after an incorrect resource reference @@ -124,10 +119,12 @@ Below is an example message from the WinUI Gallery sample app after an incorrect that the desired resource is defined in `App.xaml`, then the failure to locate it in there is a strong indicator of an erroneous reference. -Note: The below example output is for illustrative purposes only. The precise format of the message is -implementation-defined and may change in the future. Applications should not attempt to parse the message. +> [!NOTE] +> The below example output is for illustrative purposes only. +> The precise format of the message is implementation-defined and may change in the future. +> Applications should not attempt to parse the message. -``` +```text Beginning search for resource with key 'OutputTextBlockStyl'. Searching dictionary 'ms-appx:///Controls/ControlExample.xaml' for resource with key 'OutputTextBlockStyl'. Finished searching dictionary 'ms-appx:///Controls/ControlExample.xaml'. @@ -160,18 +157,17 @@ Beginning search for resource with key 'OutputTextBlockStyl'. Finished search for resource with key 'OutputTextBlockStyl'. ``` - ## XamlResourceReferenceFailedEventArgs.Message Property A human-readable explanation (in English) of the XAML resource reference failure. -```c# +```csharp public string Message { get; } ``` - # API Details -```c# + +```csharp namespace Microsoft.UI.Xaml { runtimeclass DebugSettings @@ -187,5 +183,4 @@ namespace Microsoft.UI.Xaml String Message{ get; }; }; } - ```