Skip to content

Commit abb3591

Browse files
rashmi-thakurrRashmi Thakur
rashmi-thakurr
and
Rashmi Thakur
authored
specs/XamlBindingHelper_Spec.md (#11022)
* [ADD] specs/XamlBindingHelper_Spec.md, specs/Setter_ValueProperty_Spec.md Co-authored-by: Rashmi Thakur <rashmithakur@microsoft.com>
1 parent 5f9e851 commit abb3591

2 files changed

Lines changed: 369 additions & 0 deletions

File tree

‎specs/Setter_ValueProperty_Spec.md‎

Lines changed: 115 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,115 @@
1+
Setter.ValueProperty
2+
===
3+
4+
# Background
5+
6+
[`Setter`](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.setter)
7+
is a WinUI 3 class that associates a dependency property with a value inside a `Style`. The
8+
`Setter.Value` property holds the value that will be applied, but until now there has been no
9+
public `DependencyProperty` identifier exposed for it. This means setting values on a `Setter`
10+
requires boxing the value to `Object` first:
11+
12+
* C#:
13+
```csharp
14+
// WinUI 3 — current approach (boxing required)
15+
var widthSetter = new Setter();
16+
widthSetter.Value = 300;
17+
```
18+
19+
* C++:
20+
```cpp
21+
// WinUI 3 — current approach (boxing required)
22+
auto widthSetter = Setter();
23+
widthSetter.Value(box_value(300));
24+
```
25+
26+
This spec exposes the `DependencyProperty` identifier for `Setter.Value` through a new static
27+
property, `Setter.ValueProperty`. This unblocks the usage of the `Setter` class with
28+
`XamlBindingHelper.SetPropertyFrom*` APIs, which require a `DependencyProperty` as their second
29+
argument, allowing developers to set values without boxing:
30+
31+
* C#:
32+
```csharp
33+
// WinUI 3 — new approach (no boxing)
34+
XamlBindingHelper.SetPropertyFromInt32(widthSetter, Setter.ValueProperty, 300);
35+
```
36+
37+
* C++:
38+
```cpp
39+
// WinUI 3 — new approach (no boxing)
40+
XamlBindingHelper::SetPropertyFromInt32(
41+
widthSetter,
42+
Setter::ValueProperty(),
43+
300);
44+
```
45+
46+
# Conceptual pages (How To)
47+
48+
## Using Setter.ValueProperty with XamlBindingHelper
49+
50+
Previously there was no public way to obtain a `DependencyProperty` token for `Setter.Value`. With
51+
`Setter.ValueProperty` exposed, this is now possible:
52+
53+
* C#:
54+
```csharp
55+
var setter = new Setter();
56+
// Set an Int32 value without boxing
57+
XamlBindingHelper.SetPropertyFromInt32(setter, Setter.ValueProperty, 300);
58+
```
59+
60+
* C++:
61+
```cpp
62+
auto setter = Setter();
63+
// Set an Int32 value without boxing
64+
XamlBindingHelper::SetPropertyFromInt32(setter, Setter::ValueProperty(), 300);
65+
```
66+
67+
# API Pages
68+
69+
## Setter.ValueProperty property
70+
71+
Gets the `DependencyProperty` identifier for the
72+
[`Setter.Value`](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.setter.value)
73+
property.
74+
75+
```idl
76+
static Microsoft.UI.Xaml.DependencyProperty ValueProperty{ get; };
77+
```
78+
79+
### Remarks
80+
81+
* `ValueProperty` is a read-only static property that returns a singleton `DependencyProperty`
82+
instance.
83+
84+
### Examples
85+
86+
* C#:
87+
```csharp
88+
var setter = new Setter();
89+
// Use any existing SetPropertyFrom* overload with Setter.ValueProperty
90+
XamlBindingHelper.SetPropertyFromDouble(setter, Setter.ValueProperty, 16.0);
91+
```
92+
93+
* C++:
94+
```cpp
95+
auto setter = Setter();
96+
// Use any existing SetPropertyFrom* overload with Setter::ValueProperty()
97+
XamlBindingHelper::SetPropertyFromDouble(setter, Setter::ValueProperty(), 16.0);
98+
```
99+
100+
# API Details
101+
102+
```idl
103+
namespace Microsoft.UI.Xaml
104+
{
105+
[webhosthidden]
106+
runtimeclass Setter : Microsoft.UI.Xaml.SetterBase
107+
{
108+
// Existing members omitted for brevity
109+
110+
{
111+
static Microsoft.UI.Xaml.DependencyProperty ValueProperty{ get; };
112+
}
113+
};
114+
}
115+
```

‎specs/XamlBindingHelper_Spec.md‎

Lines changed: 254 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,254 @@
1+
XamlBindingHelper
2+
===
3+
4+
# Background
5+
6+
[`XamlBindingHelper`](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.markup.xamlbindinghelper)
7+
is a utility class in WinUI 3 that provides static helper methods for setting dependency property
8+
values without boxing them to `IInspectable`. It already has overloads for primitive types such as
9+
`Int32`, `Double`, `Boolean`, `String`, and several `Windows.Foundation` structs (`Point`, `Rect`,
10+
`Size`, `TimeSpan`).
11+
12+
In WinUI 2, developers could use the
13+
[`XamlDirect`](https://learn.microsoft.com/uwp/api/windows.ui.xaml.core.direct.xamldirect) API to
14+
set struct-typed property values directly without boxing. For example `SetThicknessProperty`,
15+
`SetCornerRadiusProperty`, and `SetColorProperty`. `XamlDirect` was intentionally not carried
16+
forward to WinUI 3 because it is a narrow, low-level API with a limited number of consumers and
17+
significant maintenance costs.
18+
19+
However, there is a gap: when setting struct-typed dependency properties —
20+
`Microsoft.UI.Xaml.Thickness`, `Microsoft.UI.Xaml.CornerRadius`, and `Windows.UI.Color` — developers currently have no option other
21+
than boxing the value to `Object` first:
22+
23+
* C#:
24+
```csharp
25+
// WinUI 3 — current approach (boxing required)
26+
var border = new Border();
27+
border.SetValue(Border.BorderThicknessProperty, new Thickness(2, 4, 2, 4));
28+
```
29+
30+
* C++:
31+
```cpp
32+
// WinUI 3 — current approach (boxing required)
33+
auto border = Border();
34+
border.SetValue(Border::BorderThicknessProperty(), box_value(Thickness{ 2, 4, 2, 4 }));
35+
```
36+
37+
This spec extends `XamlBindingHelper` with three new struct-typed overloads to close that gap:
38+
39+
- `SetPropertyFromThickness`
40+
- `SetPropertyFromCornerRadius`
41+
- `SetPropertyFromColor`
42+
43+
With these additions, developers can set struct-typed values on dependency properties without any
44+
boxing:
45+
46+
* C#:
47+
```csharp
48+
// WinUI 3 — new approach (no boxing)
49+
var border = new Border();
50+
var thickness = new Thickness(2, 4, 2, 4);
51+
XamlBindingHelper.SetPropertyFromThickness(border, Border.BorderThicknessProperty, thickness);
52+
```
53+
54+
* C++:
55+
```cpp
56+
// WinUI 3 — new approach (no boxing)
57+
XamlBindingHelper::SetPropertyFromThickness(
58+
border,
59+
Border::BorderThicknessProperty(),
60+
Thickness{ 2, 4, 2, 4 });
61+
```
62+
63+
# Conceptual pages (How To)
64+
65+
## Setting struct-typed dependency properties without boxing
66+
67+
Before these APIs, setting a struct-typed value on a dependency property required boxing the value
68+
to `Object` first:
69+
70+
* C#:
71+
```csharp
72+
var border = new Border();
73+
border.SetValue(Border.BorderThicknessProperty, new Thickness(2, 4, 2, 4));
74+
```
75+
76+
* C++:
77+
```cpp
78+
auto border = Border();
79+
border.SetValue(Border::BorderThicknessProperty(), box_value(Thickness{ 2, 4, 2, 4 }));
80+
```
81+
82+
With the new APIs, the struct can be passed directly and no boxing is needed in application code:
83+
84+
* C#:
85+
```csharp
86+
var border = new Border();
87+
var thickness = new Thickness(2, 4, 2, 4);
88+
XamlBindingHelper.SetPropertyFromThickness(border, Border.BorderThicknessProperty, thickness);
89+
```
90+
91+
* C++:
92+
```cpp
93+
auto border = Border();
94+
Thickness thickness{ 2, 4, 2, 4 };
95+
XamlBindingHelper::SetPropertyFromThickness(border, Border::BorderThicknessProperty(), thickness);
96+
```
97+
98+
# API Pages
99+
100+
_(Each level-two section below maps to a docs.microsoft.com API page.)_
101+
102+
## XamlBindingHelper.SetPropertyFromThickness method
103+
104+
Sets a `Microsoft.UI.Xaml.Thickness` value on the specified dependency property of an object,
105+
without requiring the caller to box the struct to `IInspectable`.
106+
107+
```idl
108+
static void SetPropertyFromThickness(
109+
Object dependencyObject,
110+
Microsoft.UI.Xaml.DependencyProperty propertyToSet,
111+
Microsoft.UI.Xaml.Thickness value);
112+
```
113+
114+
### Parameters
115+
116+
| Parameter | Type | Description |
117+
|---|---|---|
118+
| `dependencyObject` | `object` | The target object that owns `propertyToSet`. |
119+
| `propertyToSet` | `DependencyProperty` | The dependency property to assign the value to. |
120+
| `value` | `Microsoft.UI.Xaml.Thickness` | The `Thickness` value to set. |
121+
122+
### Examples
123+
124+
* C#:
125+
```csharp
126+
var border = new Border();
127+
var thickness = new Thickness(2, 4, 2, 4);
128+
XamlBindingHelper.SetPropertyFromThickness(border, Border.BorderThicknessProperty, thickness);
129+
```
130+
131+
* C++:
132+
```cpp
133+
auto border = Border();
134+
Thickness thickness{ 2, 4, 2, 4 };
135+
XamlBindingHelper::SetPropertyFromThickness(border, Border::BorderThicknessProperty(), thickness);
136+
```
137+
138+
### Remarks
139+
140+
* If `dependencyObject` or `propertyToSet` is `null`, an exception is thrown by the WinRT layer from the underlying `E_POINTER` failure.
141+
142+
## XamlBindingHelper.SetPropertyFromCornerRadius method
143+
144+
Sets a `Microsoft.UI.Xaml.CornerRadius` value on the specified dependency property of an object,
145+
without requiring the caller to box the struct to `IInspectable`.
146+
147+
```idl
148+
static void SetPropertyFromCornerRadius(
149+
Object dependencyObject,
150+
Microsoft.UI.Xaml.DependencyProperty propertyToSet,
151+
Microsoft.UI.Xaml.CornerRadius value);
152+
```
153+
154+
### Parameters
155+
156+
| Parameter | Type | Description |
157+
|---|---|---|
158+
| `dependencyObject` | `object` | The target object that owns `propertyToSet`. |
159+
| `propertyToSet` | `DependencyProperty` | The dependency property to assign the value to. |
160+
| `value` | `Microsoft.UI.Xaml.CornerRadius` | The `CornerRadius` value to set. |
161+
162+
### Examples
163+
164+
* C#:
165+
```csharp
166+
var border = new Border();
167+
var cornerRadius = new CornerRadius(5, 10, 15, 20);
168+
XamlBindingHelper.SetPropertyFromCornerRadius(border, Border.CornerRadiusProperty, cornerRadius);
169+
```
170+
171+
* C++:
172+
```cpp
173+
auto border = Border();
174+
CornerRadius cornerRadius{ 5, 10, 15, 20 };
175+
XamlBindingHelper::SetPropertyFromCornerRadius(border, Border::CornerRadiusProperty(), cornerRadius);
176+
```
177+
178+
### Remarks
179+
180+
* If `dependencyObject` or `propertyToSet` is `null`, an exception is thrown by the WinRT layer from the underlying `E_POINTER` failure.
181+
182+
## XamlBindingHelper.SetPropertyFromColor method
183+
184+
Sets a `Windows.UI.Color` value on the specified dependency property of an object, without
185+
requiring the caller to box the struct to `IInspectable`.
186+
187+
```idl
188+
static void SetPropertyFromColor(
189+
Object dependencyObject,
190+
Microsoft.UI.Xaml.DependencyProperty propertyToSet,
191+
Windows.UI.Color value);
192+
```
193+
194+
### Parameters
195+
196+
| Parameter | Type | Description |
197+
|---|---|---|
198+
| `dependencyObject` | `object` | The target object that owns `propertyToSet`. |
199+
| `propertyToSet` | `DependencyProperty` | The dependency property to assign the value to. |
200+
| `value` | `Windows.UI.Color` | The `Color` value to set. |
201+
202+
### Examples
203+
204+
* C#:
205+
```csharp
206+
var brush = new SolidColorBrush();
207+
XamlBindingHelper.SetPropertyFromColor(brush, SolidColorBrush.ColorProperty, Colors.BlueViolet);
208+
DemoBorder.SetValue(Border.BorderBrushProperty, brush);
209+
```
210+
211+
* C++:
212+
```cpp
213+
auto brush = SolidColorBrush();
214+
XamlBindingHelper::SetPropertyFromColor(
215+
brush,
216+
SolidColorBrush::ColorProperty(),
217+
Colors::BlueViolet());
218+
DemoBorder().SetValue(Border::BorderBrushProperty(), brush);
219+
```
220+
221+
### Remarks
222+
223+
* If `dependencyObject` or `propertyToSet` is `null`, an exception is thrown by the WinRT layer from the underlying `E_POINTER` failure.
224+
225+
# API Details
226+
227+
```idl
228+
namespace Microsoft.UI.Xaml.Markup
229+
{
230+
[webhosthidden]
231+
[default_interface]
232+
runtimeclass XamlBindingHelper
233+
{
234+
// Existing members omitted for brevity
235+
236+
{
237+
static void SetPropertyFromThickness(
238+
Object dependencyObject,
239+
Microsoft.UI.Xaml.DependencyProperty propertyToSet,
240+
Microsoft.UI.Xaml.Thickness value);
241+
242+
static void SetPropertyFromCornerRadius(
243+
Object dependencyObject,
244+
Microsoft.UI.Xaml.DependencyProperty propertyToSet,
245+
Microsoft.UI.Xaml.CornerRadius value);
246+
247+
static void SetPropertyFromColor(
248+
Object dependencyObject,
249+
Microsoft.UI.Xaml.DependencyProperty propertyToSet,
250+
Windows.UI.Color value);
251+
}
252+
};
253+
}
254+
```

0 commit comments

Comments
 (0)