diff --git a/components/DependencyPropertyGenerator/samples/Assets/icon.png b/components/DependencyPropertyGenerator/samples/Assets/DependencyPropertyGenerator.png similarity index 100% rename from components/DependencyPropertyGenerator/samples/Assets/icon.png rename to components/DependencyPropertyGenerator/samples/Assets/DependencyPropertyGenerator.png diff --git a/components/DependencyPropertyGenerator/samples/DependencyPropertyGenerator.md b/components/DependencyPropertyGenerator/samples/DependencyPropertyGenerator.md new file mode 100644 index 000000000..1942fdc0d --- /dev/null +++ b/components/DependencyPropertyGenerator/samples/DependencyPropertyGenerator.md @@ -0,0 +1,110 @@ +--- +title: DependencyPropertyGenerator +author: Sergio0694 +description: A source generator for DependencyProperty registration. +keywords: DependencyPropertyGenerator +dev_langs: + - csharp +category: Xaml +subcategory: Developer +experimental: true +discussion-id: 449 +issue-id: 621 +icon: Assets/DependencyPropertyGenerator.png +--- + +The `DependencyPropertyGenerator` is a source generator that simplifies the registration of `DependencyProperty` fields in your XAML projects. +It automatically generates the boilerplate code needed for property registration, making it easier to work with dependency properties. + +Dependency properties are a key feature in WinUI, allowing for property value inheritance, change notification, and data binding. + +## Features + +- Automatically generates dependency property boilerplate code. +- Supports customization through attributes. +- Ensures consistency and reduces manual errors. +- Improves readability and maintainability of code. + +Like other Windows Community Toolkit components, the `DependencyPropertyGenerator` supports UWP, Uno Platform and the Windows App SDK. + +## Using `GeneratedDependencyPropertyAttribute` + +To use the `DependencyPropertyGenerator`, you need to add the `GeneratedDependencyPropertyAttribute` to your properties. +This attribute specifies the name of the dependency property and its default value. + +> Other DP generators might prefer using an attribute on the class instead, however the Community Toolkit's generator requires you to put the attribute on individual properties. + +For example, if you were to consume the `DependencyPropertyGenerator` from UWP: + +```cs +namespace MyNamespace; + +public partial class MyControl : DependencyObject +{ + // The GeneratedDependencyPropertyAttribute is used to specify which property to generate the DependencyProperty for. + [GeneratedDependencyProperty(IsLocalCacheEnabled = true)] + // It is required that you mark the property as partial, so that the generator can add additional code to its get() method. + public partial int Number { get; set; } +} +``` + +The source generator would generate the following partial methods: + +- `OnNumberSet`: "Executes the logic for when the `set` accessor `Number` is invoked" +- `OnNumberChanging`: "Executes the logic for when `Number` is changing." +- `OnNumberChanged`: "Executes the logic for when `Number` has just changed." +- `OnNumberPropertyChanged`: "Executes the logic for when `Number` has just changed." +- `OnPropertyChanged`: "Executes the logic for when any dependency property has just changed." + +Alongside the following changes to the `Number` property: + +```cs +public partial int Number +{ + get => field; + set + { + OnNumberSet(ref value); + + if (EqualityComparer.Default.Equals(field, value)) + { + return; + } + + int __oldValue = field; + + OnNumberChanging(value); + OnNumberChanging(__oldValue, value); + + field = value; + + object? __boxedValue = value; + + OnNumberSet(ref __boxedValue); + + SetValue(NumberProperty, __boxedValue); + + OnNumberChanged(value); + OnNumberChanged(__oldValue, value); + } +} +``` + +The `DependencyPropertyGenerator` of course also generates the DP registration code itself, aside from the helpful methods listed above. + +For the `Number` property mentioned earlier, the generator would create a static field called `NumberProperty`: + +```cs +/// +/// The backing instance for . +/// +public static readonly DependencyProperty NumberProperty = DependencyProperty.Register( + name: "Number", + propertyType: typeof(int), + ownerType: typeof(MyControl), + typeMetadata: null); +``` + + + +> [!Sample DependencyPropertyGeneratorCustomSample] diff --git a/components/DependencyPropertyGenerator/samples/DependencyPropertyGeneratorCustomSample.xaml b/components/DependencyPropertyGenerator/samples/DependencyPropertyGeneratorCustomSample.xaml new file mode 100644 index 000000000..92ba87a9c --- /dev/null +++ b/components/DependencyPropertyGenerator/samples/DependencyPropertyGeneratorCustomSample.xaml @@ -0,0 +1,17 @@ + + + + + + diff --git a/components/DependencyPropertyGenerator/samples/DependencyPropertyGeneratorCustomSample.xaml.cs b/components/DependencyPropertyGenerator/samples/DependencyPropertyGeneratorCustomSample.xaml.cs new file mode 100644 index 000000000..72d6e903d --- /dev/null +++ b/components/DependencyPropertyGenerator/samples/DependencyPropertyGeneratorCustomSample.xaml.cs @@ -0,0 +1,16 @@ +// Licensed to the .NET Foundation under one or more agreements. +// The .NET Foundation licenses this file to you under the MIT license. +// See the LICENSE file in the project root for more information. + +using CommunityToolkit.WinUI; + +namespace DependencyPropertyGenerator.Samples; + +[ToolkitSample(id: nameof(DependencyPropertyGeneratorCustomSample), "Custom control", description: $"A sample for showing how to use {nameof(GeneratedDependencyPropertyAttribute)} to register dependency properties.")] +public sealed partial class DependencyPropertyGeneratorCustomSample : Page +{ + public DependencyPropertyGeneratorCustomSample() + { + this.InitializeComponent(); + } +}