XAML - izznogooood/dotnet-wiki GitHub Wiki

Extensible Application Markup Language (XAML) is a declarative language that's based on XML. XAML is used in the WinUI app to declare the user interface.

The following XAML code defines a simple button control.

<Button Content="Save" Command="{x:Bind ViewModel.SaveChanges}" />

In XAML, properties of classes are normally set as XML attributes:

<Label Text="Hello, XAML!"
       VerticalOptions="Center"
       FontAttributes="Bold"
       FontSize="Large"
       TextColor="Aqua" />

However, when the value of a property is too complex to be expressed as a simple string (XML attribute). You can use the property-element syntax; within the property-element tags you can instantiate another object and set its properties. The sample below shows the use of property-element to declare the RowDefinitions property of the Grid control.

<Page
    x:Class="MyWinUIApp.Views.MainPage"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml">

    <Grid>
        <Grid.RowDefinitions>
            <RowDefinition Height="Auto" />
            <RowDefinition Height="*" />
            <RowDefinition Height="100" />
        </Grid.RowDefinitions>
        ...
    </Grid>
</Page>

For the Grid class to layout its content (controls) on the appropriate row it defines a Row property that the child elements can be tagged with. These are special types of bindable properties known as attached properties. They are defined by the Grid class but set on children of the Grid.

Attached properties are always recognizable in XAML files as attributes containing both a class and a property name separated by a period. They are called attached properties because they are defined by one class (in this case, Grid) but attached to other objects (in this case, children of the Grid). During layout, the Grid can interrogate the values of these attached properties to know where to place each child.

The sample below shows the use of the attached property Row on the child controls of the Grid control.

<Grid>
    <Grid.RowDefinitions>
        <RowDefinition Height="Auto" />
        <RowDefinition Height="*" />
        <RowDefinition Height="100" />
    </Grid.RowDefinitions>

    <Label Text="Autosized cell" Grid.Row="0" TextColor="White" BackgroundColor="Blue" />

    <BoxView Color="Teal" Grid.Row="1" />

    <Label Text="Fixed 100" Grid.Row="2" TextColor="Aqua" BackgroundColor="Red" HorizontalTextAlignment="Center" VerticalTextAlignment="Center" />
</Grid>

In general, you use XAML to set properties of an object to explicit values, such as a string, a number, an enumeration member, or a string that is converted to a value behind the scenes.

Sometimes, however, properties must instead reference values defined somewhere else, or which might require a little processing by code at runtime. For these purposes, XAML markup extensions are available.

These XAML markup extensions are not extensions of XML. XAML is entirely legal XML. They’re called “extensions” because they are backed by code in classes that implement IMarkupExtension. You can write your own custom markup extensions.

In many cases, XAML markup extensions are instantly recognizable in XAML files because they appear as attribute settings delimited by curly braces: { and }, but sometimes markup extensions appear in markup as conventional elements.

Below follows an explanation of the most used extensions; shared resources and binding.

XAML supports a resource dictionary, this is a dictionary with keys of type string and values of type object. You can put objects into this dictionary and then reference them from markup, all in XAML. Although it is most common to define the Resources collection at the top of the page, keep in mind that the Resources property is defined by VisualElement, and you can have Resources collections on other elements on the page.

The sample below shows a DataTemplate stored in the page's resource dictionary.

<Page.Resources>
    <DataTemplate x:Key="DetailsTemplate">
        <Grid Background="{ThemeResource ApplicationPageBackgroundThemeBrush}">
            <views:ListDetailsDetailControl ListDetailsMenuItem="{Binding}" />
        </Grid>
    </DataTemplate>
</Page.Resources>

Use the StaticResource markup extension delimited with curly braces, and includes the dictionary key, to use the DataTemplate, as shown in the sample below.

DetailsTemplate="{StaticResource DetailsTemplate}"

Data bindings allow properties of two objects to be linked so that a change in one causes a change in the other, see the section on Data binding.

WinUI offers a plethora of controls to build your user interface. See this list of controls in the Win UI controls namespace, list of shapes in the Win UI controls namespace, and try out the controls with the WinUI 3 Controls Gallery app that demonstrates all of the Windows UI 3 library controls and styles available to make a WinUI 3 app with the Windows App SDK.