From a605d6c032c3b21226cc851d58f37158d6e16be8 Mon Sep 17 00:00:00 2001 From: Rashmi Thakur Date: Wed, 11 Mar 2026 12:09:18 +0530 Subject: [PATCH 1/6] specs/XamlBindingHelper_Spec.md --- specs/XamlBindingHelper_Spec.md | 306 ++++++++++++++++++++++++++++++++ 1 file changed, 306 insertions(+) create mode 100644 specs/XamlBindingHelper_Spec.md diff --git a/specs/XamlBindingHelper_Spec.md b/specs/XamlBindingHelper_Spec.md new file mode 100644 index 0000000000..72dc0dc7b6 --- /dev/null +++ b/specs/XamlBindingHelper_Spec.md @@ -0,0 +1,306 @@ +XamlBindingHelper and Setter.ValueProperty +=== + +# Background + +[`XamlBindingHelper`](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.markup.xamlbindinghelper) +is a utility class in WinUI 3 that provides static helper methods for setting dependency property +values without boxing them to `IInspectable`. It already has overloads for primitive types such as +`Int32`, `Double`, `Boolean`, `String`, and several `Windows.Foundation` structs (`Point`, `Rect`, +`Size`, `TimeSpan`). + +In WinUI 2, developers could use the +[`XamlDirect`](https://learn.microsoft.com/uwp/api/windows.ui.xaml.core.direct.xamldirect) API to +set struct-typed property values directly without boxing. For example `SetThicknessProperty`, +`SetCornerRadiusProperty`, and `SetColorProperty`. `XamlDirect` was intentionally not carried +forward to WinUI 3 because it is a narrow, low-level API with a limited number of consumers and +significant maintenance costs. + +However, there is a real performance gap: developers who need to configure `Setter.Value` with +struct types - `Thickness`, `CornerRadius`, and `Windows.UI.Color` — currently have no option +other than boxing the value to `Object` first: + +```cpp +// WinUI 3 — current approach (boxing required) +auto widthSetter = Setter(); +widthSetter.Value(box_value(300)); +``` + +This spec extends `XamlBindingHelper` with three new struct-typed overloads to close that gap: + +- `SetPropertyFromThickness` +- `SetPropertyFromCornerRadius` +- `SetPropertyFromColor` + +In addition, `Setter` is extended with a new static dependency property accessor, +`Setter.ValueProperty`, which exposes the `DependencyProperty` identifier for `Setter.Value`. +This accessor is necessary because all `XamlBindingHelper.SetPropertyFrom*` methods require a +`DependencyProperty` as their second argument, and there was previously no public way to obtain +this token for `Setter.Value`. + +With these two additions, developers can set struct-typed values on a `Setter` without any boxing: + +```cpp +// WinUI 3 — new approach (no boxing) +XamlBindingHelper::SetPropertyFromThickness( + widthSetter, + Setter::ValueProperty(), + thickness); +``` + +## Goals + +* Provide boxing-free helpers for the three most commonly needed struct types when configuring `Setter.Value`. +* Follow the established `SetPropertyFrom*` naming pattern already present on `XamlBindingHelper`. +* Expose `Setter.ValueProperty` so callers have a `DependencyProperty` handle to pass as `propertyToSet`. + +## Non-goals + +* Re-introducing `XamlDirect` or any part of its API surface into WinUI 3. +* Adding `SetPropertyFrom*` overloads for every possible WinUI or Windows struct type. + +# Conceptual pages (How To) + +## Setting Setter.Value without boxing + +Before these APIs, setting a struct-typed value on `Setter.Value` required boxing the value to +`Object` first. For example, setting a `Thickness` on a `Setter` looked like this: + +```cpp +auto setter = Setter(); +setter.Value(box_value(Thickness{ 2, 4, 2, 4 })); +``` + +With the new APIs, the struct can be passed directly and no boxing is needed in application code: + +```cpp +auto setter = Setter(); +Thickness thickness{ 2, 4, 2, 4 }; +XamlBindingHelper::SetPropertyFromThickness(setter, Setter::ValueProperty(), thickness); +``` + +# API Pages + +_(Each level-two section below maps to a docs.microsoft.com API page.)_ + +## Setter.ValueProperty property + +Gets the `DependencyProperty` identifier for the [`Setter.Value`](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.setter.value) property. + +```idl +static Microsoft.UI.Xaml.DependencyProperty ValueProperty{ get; }; +``` + +### Remarks + +* `ValueProperty` is a read-only static property that returns a singleton `DependencyProperty` instance. +* Its primary purpose is to serve as the `propertyToSet` argument when calling + `XamlBindingHelper.SetPropertyFrom*` methods targeting `Setter.Value`. + +## XamlBindingHelper.SetPropertyFromThickness method + +Sets a `Microsoft.UI.Xaml.Thickness` value on the specified dependency property of an object, +without requiring the caller to box the struct to `IInspectable`. + +```idl +static void SetPropertyFromThickness( + Object dependencyObject, + Microsoft.UI.Xaml.DependencyProperty propertyToSet, + Microsoft.UI.Xaml.Thickness value); +``` + +### Parameters + +| Parameter | Type | Description | +|---|---|---| +| `dependencyObject` | `object` | The target object that owns `propertyToSet`. | +| `propertyToSet` | `DependencyProperty` | The dependency property to assign the value to. | +| `value` | `Microsoft.UI.Xaml.Thickness` | The `Thickness` value to set. | + +### Examples + +* C#: +```csharp +var thicknessSetter = new Setter(); +var thickness = new Thickness(); +thickness.Left = 2; +thickness.Top = 4; +thickness.Right = 2; +thickness.Bottom = 4; +XamlBindingHelper.SetPropertyFromThickness(thicknessSetter, Setter.ValueProperty, thickness); +DemoBorder.SetValue(Border.BorderThicknessProperty, thicknessSetter.Value); +``` + +* C++: +```cpp +auto thicknessSetter = Setter(); +Thickness thickness{}; +thickness.Left = 2; +thickness.Top = 4; +thickness.Right = 2; +thickness.Bottom = 4; +XamlBindingHelper::SetPropertyFromThickness(thicknessSetter, Setter::ValueProperty(), thickness); +DemoBorder().SetValue(Border::BorderThicknessProperty(), thicknessSetter.Value()); +``` + +### Remarks + +* `dependencyObject` must not be `null`; an `E_POINTER` error is returned if it is `null`. +* `propertyToSet` must not be `null`; an `E_POINTER` error is returned if it is `null`. + +## XamlBindingHelper.SetPropertyFromCornerRadius method + +Sets a `Microsoft.UI.Xaml.CornerRadius` value on the specified dependency property of an object, +without requiring the caller to box the struct to `IInspectable`. + +```idl +static void SetPropertyFromCornerRadius( + Object dependencyObject, + Microsoft.UI.Xaml.DependencyProperty propertyToSet, + Microsoft.UI.Xaml.CornerRadius value); +``` + +### Parameters + +| Parameter | Type | Description | +|---|---|---| +| `dependencyObject` | `object` | The target object that owns `propertyToSet`. | +| `propertyToSet` | `DependencyProperty` | The dependency property to assign the value to. | +| `value` | `Microsoft.UI.Xaml.CornerRadius` | The `CornerRadius` value to set. | + +### Examples + +* C#: +```csharp +var cornerRadiusSetter = new Setter(); +var cornerRadius = new CornerRadius(); +cornerRadius.TopLeft = 5; +cornerRadius.TopRight = 10; +cornerRadius.BottomRight = 15; +cornerRadius.BottomLeft = 20; +XamlBindingHelper.SetPropertyFromCornerRadius(cornerRadiusSetter, Setter.ValueProperty, cornerRadius); +DemoBorder.SetValue(Border.CornerRadiusProperty, cornerRadiusSetter.Value); +``` + +* C++: +```cpp +auto cornerRadiusSetter = Setter(); +CornerRadius cornerRadius{}; +cornerRadius.TopLeft = 5; +cornerRadius.TopRight = 10; +cornerRadius.BottomRight = 15; +cornerRadius.BottomLeft = 20; +XamlBindingHelper::SetPropertyFromCornerRadius(cornerRadiusSetter, Setter::ValueProperty(), cornerRadius); +DemoBorder().SetValue(Border::CornerRadiusProperty(), cornerRadiusSetter.Value()); +``` + +### Remarks + +* `dependencyObject` must not be `null`; an `E_POINTER` error is returned if it is `null`. +* `propertyToSet` must not be `null`; an `E_POINTER` error is returned if it is `null`. + +## XamlBindingHelper.SetPropertyFromColor method + +Sets a `Windows.UI.Color` value on the specified dependency property of an object, without +requiring the caller to box the struct to `IInspectable`. + +```idl +static void SetPropertyFromColor( + Object dependencyObject, + Microsoft.UI.Xaml.DependencyProperty propertyToSet, + Windows.UI.Color value); +``` + +### Parameters + +| Parameter | Type | Description | +|---|---|---| +| `dependencyObject` | `object` | The target object that owns `propertyToSet`. | +| `propertyToSet` | `DependencyProperty` | The dependency property to assign the value to. | +| `value` | `Windows.UI.Color` | The `Color` value to set. | + +### Examples + +Setting `Setter.Value` to a color: + +* C#: +```csharp +var colorSetter = new Setter(); +XamlBindingHelper.SetPropertyFromColor(colorSetter, Setter.ValueProperty, Colors.BlueViolet); +DemoBorder.SetValue( + Border.BorderBrushProperty, + new SolidColorBrush((Windows.UI.Color)colorSetter.Value)); +``` + +Setting `SolidColorBrush.ColorProperty` directly on a brush: + +* C#: +```csharp +var brush = new SolidColorBrush(); +XamlBindingHelper.SetPropertyFromColor(brush, SolidColorBrush.ColorProperty, Colors.BlueViolet); +DemoBorder.SetValue(Border.BorderBrushProperty, brush); +``` + +* C++: +```cpp +auto brush = SolidColorBrush(); +XamlBindingHelper::SetPropertyFromColor( + brush, + SolidColorBrush::ColorProperty(), + Colors::BlueViolet()); +DemoBorder().SetValue(Border::BorderBrushProperty(), brush); +``` + +### Remarks + +* `dependencyObject` must not be `null`; an `E_POINTER` error is returned if it is `null`. +* `propertyToSet` must not be `null`; an `E_POINTER` error is returned if it is `null`. + +# API Details + +```idl +namespace Microsoft.UI.Xaml +{ + [contract(Microsoft.UI.Xaml.WinUIContract, 1)] + [webhosthidden] + runtimeclass Setter : Microsoft.UI.Xaml.SetterBase + { + // Existing members omitted for brevity + + [contract(Microsoft.UI.Xaml.WinUIContract, 10)] + [static_name("Microsoft.UI.Xaml.ISetterStatics2")] + { + static Microsoft.UI.Xaml.DependencyProperty ValueProperty{ get; }; + } + }; +} + +namespace Microsoft.UI.Xaml.Markup +{ + [contract(Microsoft.UI.Xaml.WinUIContract, 1)] + [webhosthidden] + [default_interface] + runtimeclass XamlBindingHelper + { + // Existing members omitted for brevity + + [contract(Microsoft.UI.Xaml.WinUIContract, 10)] + { + static void SetPropertyFromThickness( + Object dependencyObject, + Microsoft.UI.Xaml.DependencyProperty propertyToSet, + Microsoft.UI.Xaml.Thickness value); + + static void SetPropertyFromCornerRadius( + Object dependencyObject, + Microsoft.UI.Xaml.DependencyProperty propertyToSet, + Microsoft.UI.Xaml.CornerRadius value); + + static void SetPropertyFromColor( + Object dependencyObject, + Microsoft.UI.Xaml.DependencyProperty propertyToSet, + Windows.UI.Color value); + } + }; +} +``` From 903f207506c45485a3288c9d42c1bd35c201bd6e Mon Sep 17 00:00:00 2001 From: Rashmi Thakur Date: Wed, 11 Mar 2026 16:15:21 +0530 Subject: [PATCH 2/6] update remarks for the APIs --- specs/XamlBindingHelper_Spec.md | 11 +++-------- 1 file changed, 3 insertions(+), 8 deletions(-) diff --git a/specs/XamlBindingHelper_Spec.md b/specs/XamlBindingHelper_Spec.md index 72dc0dc7b6..ee3a4b17fb 100644 --- a/specs/XamlBindingHelper_Spec.md +++ b/specs/XamlBindingHelper_Spec.md @@ -145,10 +145,7 @@ DemoBorder().SetValue(Border::BorderThicknessProperty(), thicknessSetter.Value() ### Remarks -* `dependencyObject` must not be `null`; an `E_POINTER` error is returned if it is `null`. -* `propertyToSet` must not be `null`; an `E_POINTER` error is returned if it is `null`. - -## XamlBindingHelper.SetPropertyFromCornerRadius method +* If `dependencyObject` or `propertyToSet` is `null`, an exception is thrown by the WinRT layer from the underlying `E_POINTER` failure. Sets a `Microsoft.UI.Xaml.CornerRadius` value on the specified dependency property of an object, without requiring the caller to box the struct to `IInspectable`. @@ -196,8 +193,7 @@ DemoBorder().SetValue(Border::CornerRadiusProperty(), cornerRadiusSetter.Value() ### Remarks -* `dependencyObject` must not be `null`; an `E_POINTER` error is returned if it is `null`. -* `propertyToSet` must not be `null`; an `E_POINTER` error is returned if it is `null`. +* If `dependencyObject` or `propertyToSet` is `null`, an exception is thrown by the WinRT layer from the underlying `E_POINTER` failure. ## XamlBindingHelper.SetPropertyFromColor method @@ -253,8 +249,7 @@ DemoBorder().SetValue(Border::BorderBrushProperty(), brush); ### Remarks -* `dependencyObject` must not be `null`; an `E_POINTER` error is returned if it is `null`. -* `propertyToSet` must not be `null`; an `E_POINTER` error is returned if it is `null`. +* If `dependencyObject` or `propertyToSet` is `null`, an exception is thrown by the WinRT layer from the underlying `E_POINTER` failure. # API Details From 54524f3bbe95a413edd966c20c02f77640dec6a4 Mon Sep 17 00:00:00 2001 From: rashmithakur Date: Fri, 10 Apr 2026 12:23:26 +0530 Subject: [PATCH 3/6] Split XamlBindingHelper spec: move Setter.ValueProperty to its own spec --- specs/Setter_ValueProperty_Spec.md | 113 +++++++++++++++++++++++++++++ specs/XamlBindingHelper_Spec.md | 47 ++---------- 2 files changed, 118 insertions(+), 42 deletions(-) create mode 100644 specs/Setter_ValueProperty_Spec.md diff --git a/specs/Setter_ValueProperty_Spec.md b/specs/Setter_ValueProperty_Spec.md new file mode 100644 index 0000000000..056a899306 --- /dev/null +++ b/specs/Setter_ValueProperty_Spec.md @@ -0,0 +1,113 @@ +Setter.ValueProperty +=== + +# Background + +[`Setter`](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.setter) +is a WinUI 3 class that associates a dependency property with a value inside a `Style`. The +`Setter.Value` property holds the value that will be applied, but until now there has been no +public `DependencyProperty` identifier exposed for it. + +All `XamlBindingHelper.SetPropertyFrom*` methods require a `DependencyProperty` as their second +argument (`propertyToSet`). Without a public `DependencyProperty` handle for `Setter.Value`, +callers cannot use `XamlBindingHelper` to set `Setter.Value` directly — they are forced to box the +value to `Object` first: + +```cpp +// WinUI 3 — current approach (boxing required) +auto widthSetter = Setter(); +widthSetter.Value(box_value(300)); +``` + +This spec adds a new static property, `Setter.ValueProperty`, that returns the +`DependencyProperty` identifier for `Setter.Value`. This unlocks `XamlBindingHelper` usage for +`Setter.Value`, allowing developers to set values without boxing: + +```cpp +// WinUI 3 — new approach (no boxing) +XamlBindingHelper::SetPropertyFromInt32( + widthSetter, + Setter::ValueProperty(), + 300); +``` + +## Goals + +* Expose `Setter.ValueProperty` so callers have a `DependencyProperty` handle to pass as + `propertyToSet` in `XamlBindingHelper.SetPropertyFrom*` methods. +* Follow the established pattern of other WinUI 3 classes that expose `DependencyProperty` + identifiers for their properties. + +## Non-goals + +* Changing the behavior or storage of `Setter.Value` itself. +* Adding new overloads to `XamlBindingHelper` (covered in a separate spec). + +# Conceptual pages (How To) + +## Using Setter.ValueProperty with XamlBindingHelper + +Previously there was no public way to obtain a `DependencyProperty` token for `Setter.Value`. With +`Setter.ValueProperty`, you can now pass it to any existing `XamlBindingHelper.SetPropertyFrom*` +overload: + +```cpp +auto setter = Setter(); +// Set an Int32 value without boxing +XamlBindingHelper::SetPropertyFromInt32(setter, Setter::ValueProperty(), 300); +``` + +# API Pages + +## Setter.ValueProperty property + +Gets the `DependencyProperty` identifier for the +[`Setter.Value`](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.setter.value) +property. + +```idl +static Microsoft.UI.Xaml.DependencyProperty ValueProperty{ get; }; +``` + +### Remarks + +* `ValueProperty` is a read-only static property that returns a singleton `DependencyProperty` + instance. +* Its primary purpose is to serve as the `propertyToSet` argument when calling + `XamlBindingHelper.SetPropertyFrom*` methods targeting `Setter.Value`. + +### Examples + +* C#: +```csharp +var setter = new Setter(); +// Use any existing SetPropertyFrom* overload with Setter.ValueProperty +XamlBindingHelper.SetPropertyFromDouble(setter, Setter.ValueProperty, 16.0); +``` + +* C++: +```cpp +auto setter = Setter(); +// Use any existing SetPropertyFrom* overload with Setter::ValueProperty() +XamlBindingHelper::SetPropertyFromDouble(setter, Setter::ValueProperty(), 16.0); +``` + +# API Details + +```idl +namespace Microsoft.UI.Xaml +{ + [contract(Microsoft.UI.Xaml.WinUIContract, 1)] + [webhosthidden] + runtimeclass Setter : Microsoft.UI.Xaml.SetterBase + { + // Existing members omitted for brevity + + [contract(Microsoft.UI.Xaml.WinUIContract, 10)] + [static_name("Microsoft.UI.Xaml.ISetterStatics2")] + { + static Microsoft.UI.Xaml.DependencyProperty ValueProperty{ get; }; + } + }; +} +``` diff --git a/specs/XamlBindingHelper_Spec.md b/specs/XamlBindingHelper_Spec.md index ee3a4b17fb..1fcb1305a2 100644 --- a/specs/XamlBindingHelper_Spec.md +++ b/specs/XamlBindingHelper_Spec.md @@ -1,4 +1,4 @@ -XamlBindingHelper and Setter.ValueProperty +XamlBindingHelper === # Background @@ -17,11 +17,11 @@ forward to WinUI 3 because it is a narrow, low-level API with a limited number o significant maintenance costs. However, there is a real performance gap: developers who need to configure `Setter.Value` with -struct types - `Thickness`, `CornerRadius`, and `Windows.UI.Color` — currently have no option +struct types - `Thickness`, `CornerRadius`, and `Windows.UI.Color` � currently have no option other than boxing the value to `Object` first: ```cpp -// WinUI 3 — current approach (boxing required) +// WinUI 3 � current approach (boxing required) auto widthSetter = Setter(); widthSetter.Value(box_value(300)); ``` @@ -32,16 +32,10 @@ This spec extends `XamlBindingHelper` with three new struct-typed overloads to c - `SetPropertyFromCornerRadius` - `SetPropertyFromColor` -In addition, `Setter` is extended with a new static dependency property accessor, -`Setter.ValueProperty`, which exposes the `DependencyProperty` identifier for `Setter.Value`. -This accessor is necessary because all `XamlBindingHelper.SetPropertyFrom*` methods require a -`DependencyProperty` as their second argument, and there was previously no public way to obtain -this token for `Setter.Value`. - -With these two additions, developers can set struct-typed values on a `Setter` without any boxing: +With these additions, developers can set struct-typed values on a `Setter` without any boxing: ```cpp -// WinUI 3 — new approach (no boxing) +// WinUI 3 � new approach (no boxing) XamlBindingHelper::SetPropertyFromThickness( widthSetter, Setter::ValueProperty(), @@ -52,7 +46,6 @@ XamlBindingHelper::SetPropertyFromThickness( * Provide boxing-free helpers for the three most commonly needed struct types when configuring `Setter.Value`. * Follow the established `SetPropertyFrom*` naming pattern already present on `XamlBindingHelper`. -* Expose `Setter.ValueProperty` so callers have a `DependencyProperty` handle to pass as `propertyToSet`. ## Non-goals @@ -83,20 +76,6 @@ XamlBindingHelper::SetPropertyFromThickness(setter, Setter::ValueProperty(), thi _(Each level-two section below maps to a docs.microsoft.com API page.)_ -## Setter.ValueProperty property - -Gets the `DependencyProperty` identifier for the [`Setter.Value`](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.setter.value) property. - -```idl -static Microsoft.UI.Xaml.DependencyProperty ValueProperty{ get; }; -``` - -### Remarks - -* `ValueProperty` is a read-only static property that returns a singleton `DependencyProperty` instance. -* Its primary purpose is to serve as the `propertyToSet` argument when calling - `XamlBindingHelper.SetPropertyFrom*` methods targeting `Setter.Value`. - ## XamlBindingHelper.SetPropertyFromThickness method Sets a `Microsoft.UI.Xaml.Thickness` value on the specified dependency property of an object, @@ -254,22 +233,6 @@ DemoBorder().SetValue(Border::BorderBrushProperty(), brush); # API Details ```idl -namespace Microsoft.UI.Xaml -{ - [contract(Microsoft.UI.Xaml.WinUIContract, 1)] - [webhosthidden] - runtimeclass Setter : Microsoft.UI.Xaml.SetterBase - { - // Existing members omitted for brevity - - [contract(Microsoft.UI.Xaml.WinUIContract, 10)] - [static_name("Microsoft.UI.Xaml.ISetterStatics2")] - { - static Microsoft.UI.Xaml.DependencyProperty ValueProperty{ get; }; - } - }; -} - namespace Microsoft.UI.Xaml.Markup { [contract(Microsoft.UI.Xaml.WinUIContract, 1)] From d3288da8699ac1115cbb2e4f5a16f53cb203c78c Mon Sep 17 00:00:00 2001 From: rashmithakur Date: Mon, 13 Apr 2026 11:41:44 +0530 Subject: [PATCH 4/6] Address review feedback on XamlBindingHelper and Setter specs --- specs/Setter_ValueProperty_Spec.md | 3 +-- specs/XamlBindingHelper_Spec.md | 2 ++ 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/specs/Setter_ValueProperty_Spec.md b/specs/Setter_ValueProperty_Spec.md index 056a899306..b73afd8430 100644 --- a/specs/Setter_ValueProperty_Spec.md +++ b/specs/Setter_ValueProperty_Spec.md @@ -10,8 +10,7 @@ public `DependencyProperty` identifier exposed for it. All `XamlBindingHelper.SetPropertyFrom*` methods require a `DependencyProperty` as their second argument (`propertyToSet`). Without a public `DependencyProperty` handle for `Setter.Value`, -callers cannot use `XamlBindingHelper` to set `Setter.Value` directly — they are forced to box the -value to `Object` first: +setting values on a `Setter` requires boxing the value to `Object` first: ```cpp // WinUI 3 — current approach (boxing required) diff --git a/specs/XamlBindingHelper_Spec.md b/specs/XamlBindingHelper_Spec.md index 1fcb1305a2..0234aff79b 100644 --- a/specs/XamlBindingHelper_Spec.md +++ b/specs/XamlBindingHelper_Spec.md @@ -126,6 +126,8 @@ DemoBorder().SetValue(Border::BorderThicknessProperty(), thicknessSetter.Value() * If `dependencyObject` or `propertyToSet` is `null`, an exception is thrown by the WinRT layer from the underlying `E_POINTER` failure. +## XamlBindingHelper.SetPropertyFromCornerRadius method + Sets a `Microsoft.UI.Xaml.CornerRadius` value on the specified dependency property of an object, without requiring the caller to box the struct to `IInspectable`. From 87e09b94666523fb4cd4fc1acd2cd1d77da976ff Mon Sep 17 00:00:00 2001 From: rashmithakur Date: Thu, 16 Apr 2026 14:53:30 +0530 Subject: [PATCH 5/6] [UPDATE] specs/Setter_ValueProperty_Spec.md --- specs/Setter_ValueProperty_Spec.md | 22 ++++++++-------------- 1 file changed, 8 insertions(+), 14 deletions(-) diff --git a/specs/Setter_ValueProperty_Spec.md b/specs/Setter_ValueProperty_Spec.md index b73afd8430..5e00224419 100644 --- a/specs/Setter_ValueProperty_Spec.md +++ b/specs/Setter_ValueProperty_Spec.md @@ -6,11 +6,8 @@ Setter.ValueProperty [`Setter`](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.setter) is a WinUI 3 class that associates a dependency property with a value inside a `Style`. The `Setter.Value` property holds the value that will be applied, but until now there has been no -public `DependencyProperty` identifier exposed for it. - -All `XamlBindingHelper.SetPropertyFrom*` methods require a `DependencyProperty` as their second -argument (`propertyToSet`). Without a public `DependencyProperty` handle for `Setter.Value`, -setting values on a `Setter` requires boxing the value to `Object` first: +public `DependencyProperty` identifier exposed for it. This means setting values on a `Setter` +requires boxing the value to `Object` first: ```cpp // WinUI 3 — current approach (boxing required) @@ -18,9 +15,10 @@ auto widthSetter = Setter(); widthSetter.Value(box_value(300)); ``` -This spec adds a new static property, `Setter.ValueProperty`, that returns the -`DependencyProperty` identifier for `Setter.Value`. This unlocks `XamlBindingHelper` usage for -`Setter.Value`, allowing developers to set values without boxing: +This spec exposes the `DependencyProperty` identifier for `Setter.Value` through a new static +property, `Setter.ValueProperty`. This unblocks the usage of the `Setter` class with +`XamlBindingHelper.SetPropertyFrom*` APIs, which require a `DependencyProperty` as their second +argument, allowing developers to set values without boxing: ```cpp // WinUI 3 — new approach (no boxing) @@ -32,8 +30,7 @@ XamlBindingHelper::SetPropertyFromInt32( ## Goals -* Expose `Setter.ValueProperty` so callers have a `DependencyProperty` handle to pass as - `propertyToSet` in `XamlBindingHelper.SetPropertyFrom*` methods. +* Expose the `DependencyProperty` identifier for `Setter.Value`. * Follow the established pattern of other WinUI 3 classes that expose `DependencyProperty` identifiers for their properties. @@ -47,8 +44,7 @@ XamlBindingHelper::SetPropertyFromInt32( ## Using Setter.ValueProperty with XamlBindingHelper Previously there was no public way to obtain a `DependencyProperty` token for `Setter.Value`. With -`Setter.ValueProperty`, you can now pass it to any existing `XamlBindingHelper.SetPropertyFrom*` -overload: +`Setter.ValueProperty` exposed, this is now possible: ```cpp auto setter = Setter(); @@ -72,8 +68,6 @@ static Microsoft.UI.Xaml.DependencyProperty ValueProperty{ get; }; * `ValueProperty` is a read-only static property that returns a singleton `DependencyProperty` instance. -* Its primary purpose is to serve as the `propertyToSet` argument when calling - `XamlBindingHelper.SetPropertyFrom*` methods targeting `Setter.Value`. ### Examples From 8697534f8114baa6007ca817e648249f117f799c Mon Sep 17 00:00:00 2001 From: rashmithakur Date: Thu, 16 Apr 2026 15:16:21 +0530 Subject: [PATCH 6/6] [UPDATE] specs/XamlBindingHelper_Spec.md --- specs/XamlBindingHelper_Spec.md | 75 +++++++++++++-------------------- 1 file changed, 30 insertions(+), 45 deletions(-) diff --git a/specs/XamlBindingHelper_Spec.md b/specs/XamlBindingHelper_Spec.md index 0234aff79b..4cf131aa93 100644 --- a/specs/XamlBindingHelper_Spec.md +++ b/specs/XamlBindingHelper_Spec.md @@ -16,14 +16,14 @@ set struct-typed property values directly without boxing. For example `SetThickn forward to WinUI 3 because it is a narrow, low-level API with a limited number of consumers and significant maintenance costs. -However, there is a real performance gap: developers who need to configure `Setter.Value` with -struct types - `Thickness`, `CornerRadius`, and `Windows.UI.Color` � currently have no option -other than boxing the value to `Object` first: +However, there is a real performance gap: when setting struct-typed dependency properties — +`Thickness`, `CornerRadius`, and `Windows.UI.Color` — developers currently have no option other +than boxing the value to `Object` first: ```cpp -// WinUI 3 � current approach (boxing required) -auto widthSetter = Setter(); -widthSetter.Value(box_value(300)); +// WinUI 3 — current approach (boxing required) +auto border = Border(); +border.SetValue(Border::BorderThicknessProperty(), box_value(Thickness{ 2, 4, 2, 4 })); ``` This spec extends `XamlBindingHelper` with three new struct-typed overloads to close that gap: @@ -32,19 +32,21 @@ This spec extends `XamlBindingHelper` with three new struct-typed overloads to c - `SetPropertyFromCornerRadius` - `SetPropertyFromColor` -With these additions, developers can set struct-typed values on a `Setter` without any boxing: +With these additions, developers can set struct-typed values on dependency properties without any +boxing: ```cpp -// WinUI 3 � new approach (no boxing) +// WinUI 3 — new approach (no boxing) XamlBindingHelper::SetPropertyFromThickness( - widthSetter, - Setter::ValueProperty(), - thickness); + border, + Border::BorderThicknessProperty(), + Thickness{ 2, 4, 2, 4 }); ``` ## Goals -* Provide boxing-free helpers for the three most commonly needed struct types when configuring `Setter.Value`. +* Provide boxing-free helpers for the three most commonly needed struct types: `Thickness`, + `CornerRadius`, and `Color`. * Follow the established `SetPropertyFrom*` naming pattern already present on `XamlBindingHelper`. ## Non-goals @@ -54,22 +56,22 @@ XamlBindingHelper::SetPropertyFromThickness( # Conceptual pages (How To) -## Setting Setter.Value without boxing +## Setting struct-typed dependency properties without boxing -Before these APIs, setting a struct-typed value on `Setter.Value` required boxing the value to -`Object` first. For example, setting a `Thickness` on a `Setter` looked like this: +Before these APIs, setting a struct-typed value on a dependency property required boxing the value +to `Object` first: ```cpp -auto setter = Setter(); -setter.Value(box_value(Thickness{ 2, 4, 2, 4 })); +auto border = Border(); +border.SetValue(Border::BorderThicknessProperty(), box_value(Thickness{ 2, 4, 2, 4 })); ``` With the new APIs, the struct can be passed directly and no boxing is needed in application code: ```cpp -auto setter = Setter(); +auto border = Border(); Thickness thickness{ 2, 4, 2, 4 }; -XamlBindingHelper::SetPropertyFromThickness(setter, Setter::ValueProperty(), thickness); +XamlBindingHelper::SetPropertyFromThickness(border, Border::BorderThicknessProperty(), thickness); ``` # API Pages @@ -100,26 +102,24 @@ static void SetPropertyFromThickness( * C#: ```csharp -var thicknessSetter = new Setter(); +var border = new Border(); var thickness = new Thickness(); thickness.Left = 2; thickness.Top = 4; thickness.Right = 2; thickness.Bottom = 4; -XamlBindingHelper.SetPropertyFromThickness(thicknessSetter, Setter.ValueProperty, thickness); -DemoBorder.SetValue(Border.BorderThicknessProperty, thicknessSetter.Value); +XamlBindingHelper.SetPropertyFromThickness(border, Border.BorderThicknessProperty, thickness); ``` * C++: ```cpp -auto thicknessSetter = Setter(); +auto border = Border(); Thickness thickness{}; thickness.Left = 2; thickness.Top = 4; thickness.Right = 2; thickness.Bottom = 4; -XamlBindingHelper::SetPropertyFromThickness(thicknessSetter, Setter::ValueProperty(), thickness); -DemoBorder().SetValue(Border::BorderThicknessProperty(), thicknessSetter.Value()); +XamlBindingHelper::SetPropertyFromThickness(border, Border::BorderThicknessProperty(), thickness); ``` ### Remarks @@ -150,26 +150,24 @@ static void SetPropertyFromCornerRadius( * C#: ```csharp -var cornerRadiusSetter = new Setter(); +var border = new Border(); var cornerRadius = new CornerRadius(); cornerRadius.TopLeft = 5; cornerRadius.TopRight = 10; cornerRadius.BottomRight = 15; cornerRadius.BottomLeft = 20; -XamlBindingHelper.SetPropertyFromCornerRadius(cornerRadiusSetter, Setter.ValueProperty, cornerRadius); -DemoBorder.SetValue(Border.CornerRadiusProperty, cornerRadiusSetter.Value); +XamlBindingHelper.SetPropertyFromCornerRadius(border, Border.CornerRadiusProperty, cornerRadius); ``` * C++: ```cpp -auto cornerRadiusSetter = Setter(); +auto border = Border(); CornerRadius cornerRadius{}; cornerRadius.TopLeft = 5; cornerRadius.TopRight = 10; cornerRadius.BottomRight = 15; cornerRadius.BottomLeft = 20; -XamlBindingHelper::SetPropertyFromCornerRadius(cornerRadiusSetter, Setter::ValueProperty(), cornerRadius); -DemoBorder().SetValue(Border::CornerRadiusProperty(), cornerRadiusSetter.Value()); +XamlBindingHelper::SetPropertyFromCornerRadius(border, Border::CornerRadiusProperty(), cornerRadius); ``` ### Remarks @@ -198,19 +196,6 @@ static void SetPropertyFromColor( ### Examples -Setting `Setter.Value` to a color: - -* C#: -```csharp -var colorSetter = new Setter(); -XamlBindingHelper.SetPropertyFromColor(colorSetter, Setter.ValueProperty, Colors.BlueViolet); -DemoBorder.SetValue( - Border.BorderBrushProperty, - new SolidColorBrush((Windows.UI.Color)colorSetter.Value)); -``` - -Setting `SolidColorBrush.ColorProperty` directly on a brush: - * C#: ```csharp var brush = new SolidColorBrush(); @@ -263,4 +248,4 @@ namespace Microsoft.UI.Xaml.Markup } }; } -``` +``` \ No newline at end of file