Introduction to XAML
Avalonia uses XAML to define user-interfaces. XAML is an XML-based markup language that is used by many UI frameworks.
This section is intended as a basic introduction to using XAML in Avalonia. For more information see the Microsoft XAML documentation for WPF or Microsoft XAML documentation for UWP - many of the concepts are the same between frameworks.
The traditional extension for XAML files is
.xaml
but due to problems with Visual Studio we have been forced to move to our own .axaml
extension for Avalonia XAML files. From version 0.9.11 Avalonia XAML files created in Visual Studio use the .axaml
extension and from version 0.10 all of our templates will be standardized on using the .axaml
extension.Both
.xaml
and .axaml
will be supported going forward, so feel free to use the extension you prefer.A basic Avalonia XAML file looks like this:
<Window xmlns="https://github.com/avaloniaui"
xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
x:Class="AvaloniaApplication1.MainWindow">
</Window>
There are three parts to this file:
- The root element
Window
- this describes the type of the root control in the XAML file; in this caseWindow
xmlns="https://github.com/avaloniaui"
- this is the XAML namespace for Avalonia. Without this, the file will not be recognised as an Avalonia XAML document.xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
- this is the XAML-language XAML namespace. This isn't strictly necessary, but you will probably need it for accessing certain features of the XAML language.x:Class="AvaloniaApplication1.MainWindow"
- this tells the XAML compiler where to find the associated class for this file, defined in code-behind
In every
XML
-file you can declare namespaces, where the processor of the document can look up the nodes defined. If you are completely new to X(A)ML
, please read more about XML-Namespaces
here.A new namespace can be added via the
xmlns
-attribute. Most of the times the namespaces used are defined at the root node, but they can be added at each level of your file. Only one namespace can be defined without an alias, all other namespaces must have an unique alias defined:xmlns:myAlias="MyNamespaceDefinition"
Option 1: Using the
clr-namespace
-syntax:xmlns:myAlias1="clr-namespace:My.NameSpace"
xmlns:myAlias2="clr-namespace:My.NameSpace.InOtherAssembly;assembly=TheOtherAssembly"
`My.NameSpace` is the namespace in `C#` you want to use
You can omit the `assembly` part if your namespace is in the same assembly.
Option 2: Using the
using
-syntax:xmlns:myAlias3="using:My.NameSpace"
`My.NameSpace` is the namespace in `C#` you want to use
Option 3: Using a common namespace which can combine multiple namespaces:
Some libraries have their own common namespace defined, like Avalonia does. Often they use an URL like
https://github.com/avaloniaui
, but it can be any string. Usage:xmlns:myAlias4="https://github.com/avaloniaui"
If you want to create your own common namespace, add these lines to any
*.cs
-file, for example in Properties ► AssemblyInfo.cs
:using Avalonia.Metadata;
[assembly: XmlnsDefinition("https://my.controls.url", "My.NameSpace")]
[assembly: XmlnsDefinition("https://my.controls.url", "My.NameSpace.Other")]
Controls are added to the XAML by adding an XML element with the control's class name. For example to add a button as the child of the window you would write:
<Window xmlns="https://github.com/avaloniaui"
xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml">
<Button>Hello World!</Button>
</Window>
You can set a property of a control by adding an XML attribute to an element. For example to create a button with a blue background you could write:
<Window xmlns="https://github.com/avaloniaui"
xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml">
<Button Background="Blue">Hello World!</Button>
</Window>
You can also use property element syntax for setting properties. For more information see the WPF documentation.
You may notice that the button above has its "Hello World!" content placed directly inside the XML element. This could also be written as a property using:
<Window xmlns="https://github.com/avaloniaui"
xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml">
<Button Content="Hello World"/>
</Window>
This is because
Button.Content
is declared as a [Content]
Property which means that any content placed inside its XML tag will be assigned to this property.You can bind a property using the
{Binding}
markup extension:<Window xmlns="https://github.com/avaloniaui"
xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml">
<Button Content="{Binding Greeting}"/>
</Window>
Many XAML files also have an associated code-behind file which usually has the extension
.xaml.cs
. For more information see the codebehind documentation.Last modified 4mo ago