feat: Add XAML Fundamentals section with pages and examples

[Zakariathr22]

Description

This pull request introduces the "XAML Fundamentals" section, including pages and examples for XAML Resources, XAML Styles, Binding, and Templates, main changes are:

• Added sample code files for XAML Resources, XAML Styles, Binding, and Templates.
• Added new assets for theme resource examples and updated control images.
• Updated ControlInfoData.json to include the new "XAML Fundamentals" section.
• Added pages for XAML Resources, XAML Styles, Binding, and Templates, each with practical examples.
• Updated navigation to include the new section and handle its items programmatically.

Motivation and Context

I noticed that many learners, especially those new to WinUI 3, often turn to the WinUI 3 Gallery application as their starting point. While the app provides excellent explanations of controls and code samples, it sometimes introduces concepts that may be unfamiliar to beginners.

To address this, I had created a dedicated section in the application called XAML Fundamentals. This section is organized into key topics, including: XAML Resources, XAML Styles, Binding, and Templates.

The goal is to help learners better understand these foundational concepts by providing clear explanations, practical examples, and links to relevant documentation.

How Has This Been Tested?

This code was tested manually, and no issues were encountered during the testing. The changes are isolated to the new section and do not affect other areas of the app.

Screenshots:

XAML Resouces Page

XAML Styles

Binding

Templates

Search Page

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)

[Zakariathr22]

Nit: note the unnecessary use of Capital letters for a number of Words.

Adjusted as suggested.

[Jay-o-Way]

@niels9001 @karkarl (off-topic) I feel issue #1542 is quickly getting more and more important!

[Jay-o-Way]

Did you know?

Note

Starting in Windows 10, version 1607, the XAML framework provides a built in Boolean to Visibility converter. The converter maps true to the Visible enumeration value and false to Collapsed so you can bind a Visibility property to a Boolean without creating a converter. Note that this is not a feature of function binding, only property binding. To use the built in converter, your app's minimum target SDK version must be 14393 or later. You can't use it when your app targets earlier versions of Windows 10. For more info about target versions, see Version adaptive code.

https://learn.microsoft.com/windows/uwp/xaml-platform/x-bind-markup-extension#remarks

[Zakariathr22]

@Jay-o-Way
Thank you for your review and insightful feedback; I’ll work on implementing your suggestions.
Please let me know if there’s anything else I should address.

[niels9001]

LGTM! Amazing work @Zakariathr22!

[Zakariathr22]

@niels9001
Thank you for your help and reviews; they made a significant difference.

[niels9001]

@Zakariathr22 We've reviewed the PR and saw some (minor) improvements we could make.

Would you mind getting the latest changes from main and can I PR against your branch? It's probably faster that way :)!

[Zakariathr22]

Would you mind getting the latest changes from main and can I PR against your branch? It's probably faster that way :)!

@niels9001

The latest changes from main have been retrieved

Sure, feel free to go ahead, thanks for helping out!

[Zakariathr22]

@niels9001
I can also grant you a write access if you like :)

[marcelwgn]

Below my thoughts on the current content:

Theme resources page:

• Also, do we need a "visual" example for resource dictionaries if it looks almost the same as the previous example?
• I think having the following XAML as example of how resource scoping works might be a bit more helpful and in the source code, we reference the same brush every time so it is clear what is happening.
  

Styling page:

• The blue styled button flashes white upon hovering (at least in dark theme)
• Do we want to show non key based styling? It feels a bit of an anti pattern to teach it since I think you would ignore the base style through that pattern
• Not sure what the last example is trying to tell since the first example already uses BasedOn. I think it would be better to explain it there and skip that example

Binding page:

• For the one way and two way binding, I would probably use two columns to be able to compare it side by side instead of that toggle.
• Maybe we should use a more interesting converter than the nullability/visibility one given that already is handled somewhat natively already?
• Should we call out some of the key differences between x:Bind and binding instead of linking to the docs outright?

[AndrewKeepCoding]

IMHO, the API details button (the i button) is confusing in this case because Resources, Styles, Binding and Templates represent features rather than classes.

[Jay-o-Way]

• The blue styled button flashes white upon hovering (at least in dark theme)

Yep, the hover state is not affected...

• Maybe we should use a more interesting converter than the nullability/visibility one given that already is handled somewhat natively already?

Good one!

• Should we call out some of the key differences between x:Bind and binding instead of linking to the docs outright?

We actually had that, but Niels wanted it changed #1661 (comment)

[Zakariathr22]

Hi @marcelwgn, thanks for sharing this!

• I think having the following XAML as example of how resource scoping works might be a bit more helpful and in the source code, we reference the same brush every time so it is clear what is happening.
  

Great idea! I’ll do it.

• Also, do we need a "visual" example for resource dictionaries if it looks almost the same as the previous example?

You’re right; it’s quite similar to the previous example. I have two ideas to fix this:

1. Leave it as it is, since I’ll update the previous example as you suggested.
2. Or Remove the example and replace it with a code presenter instead.

What do you think?

• The blue styled button flashes white upon hovering (at least in dark theme)

Yes, I didn’t realize that either. I think we should apply the style to a different type of control. Do you have any suggestions?

• Do we want to show non key based styling? It feels a bit of an anti pattern to teach it since I think you would ignore the base style through that pattern

I think by presenting non-key-based styles, the user understands how styles are automatically applied to specific control types. This helps the user grasp the concept of TargetType and see the connection between styles and controls more clearly.

• Not sure what the last example is trying to tell since the first example already uses BasedOn. I think it would be better to explain it there and skip that example

Actually, the BasedOn property wasn’t implemented in the first example initially. We only added it to meet a11y requirements, as Niels requested here
For that reason, I can modify the first example as I suggested earlier without needing to use BasedOn. Do you think that would be a good idea?

• For the one way and two way binding, I would probably use two columns to be able to compare it side by side instead of that toggle.
• Maybe we should use a more interesting converter than the nullability/visibility one given that already is handled somewhat natively already?

Very good ideas.

• Should we call out some of the key differences between x:Bind and binding instead of linking to the docs outright?

As Jay mentioned, we actually had that setup before, but Niels wanted it changed, and I agree with Niels on this point.

this is something we should keep in the docs only? We should focus on samples for WinUI Gallery, and the link you have to MS Learn might already be sufficient

[Zakariathr22]

Hi @AndrewKeepCoding, thanks for sharing your opinion,

IMHO, the API details button (the i button) is confusing in this case because Resources, Styles, Binding and Templates represent features rather than classes.

• Style is a class in the Microsoft.UI.Xaml namespace. Check it out here.
• The templates, including ControlTemplate, DataTemplate, and ItemsPanelTemplate, are classes in the Microsoft.UI.Xaml.Controls namespace. You can explore them here: ControlTemplate, DataTemplate, and ItemsPanelTemplate.
• As for the others, it’s not entirely clear. We have ResourceDictionary as a class, but Resources and Theme Resources aren't.
• The same applies to Binding, but x:Bind is not a class.

Do you have any suggestions?

@Jay-o-Way, I'd like also to know your thoughts on this.