Data Binding Syntax

In Avalonia, you can define data binding in XAML or code. To define data binding in XAML, you use the data binding mark-up extension, and this has its own syntax which is described here.

Data Binding Mark-up Extension

The data binding mark-up extension uses the keyword Binding in combination with parameters that define the data source, and other options. The format of the mark-up extension is like this:

<SomeControl SomeProperty="{Binding Path, Mode=ModeValue, StringFormat=Pattern>

When there is more than one option parameter, the list is comma-separated.

Parameter	Description
Path	The data binding path.
Mode	One of the binding modes, see below.
StringFormat	A pattern showing how the value is to be formatted.
ElementName	Can be shortened by using # in the path.
Converter	A function that converts the value.
RelativeSource	Works on the visual tree instead of the logical tree.

Data Binding Path

The first parameter is usually the path to the data source. This is an object in a data context that Avalonia locates when it performs data binding.

There is no need to use the parameter name Pathhere. So these bindings are equivalent:

<TextBlock Text="{Binding Name}"/>
<TextBlock Text="{Binding Path=Name}"/>

The binding path can be a single property, or it can be a chain of properties. For example if the data source has a Student property, and the object returned by that property has a property Name, you can bind to the student name using syntax like this:

<TextBlock Text="{Binding Student.Name}"/>

If the data source has an array or list (with an indexer), then you can add the index to the binding path like this:

<TextBlock Text="{Binding Students[0].Name}"/>

Empty Binding Path

You can specify data binding without a path. This binds to the data context of the control itself (where the binding is defined). These two syntaxes are equivalent:

<TextBlock Text="{Binding}"/>
<TextBlock Text="{Binding .}"/>

Data Binding Mode

You can change how data is moved in a data binding by specifying the data binding mode.

For example:

<TextBlock Text="{Binding Name, Mode=OneTime}">

The available binding modes are:

Mode	Description
OneWay	Changes in the data source are automatically propagated to the binding target
TwoWay	Changes in the data source are automatically propagated to the binding target, and the other way around as well.
OneTime	The value from the data source is propagated at initialization to the binding target, but subsequent changes are ignored
OneWayToSource	Changes in the binding target are propagated to the data source, but not the other way.
Default	The binding mode is based on a default mode defined in the code for the property. See below.

When no mode is specified, then the default is always used. For a control property that does not change value due to user interaction, the default mode is generally OneWay. For a control property that does change value due to user input, then the default mode is usually TwoWay.

For example, the default mode for a TextBlock.Text property is OneWay, and the default mode for a TextBox.Text property is TwoWay.

Converting Bound Values

There are a number of ways to convert the value supplied by a data binding into what is actually displayed in the target control.

String Formatting

You can apply a pattern to a binding to define how the value is to be displayed. There are a number of syntaxes for this

The pattern index is zero-based, and must always be inside curly braces. When the curly braces are at the beginning of the pattern, even when also inside single quotes, they must be escaped. This can be done either by adding an extra pair of curly braces to the front of the pattern, or by escaping the curly braces using backslashes.

This means that when your pattern starts with a zero, you can use a pair of curly braces to escape the pattern, then supply the pattern itself inside a second pair of curly braces. For example:

<TextBlock Text="{Binding FloatProperty, StringFormat={}{0:0.0}}" />

Alternatively, you can use backslashes to escape the curly brackets needed for the pattern. For example:

<TextBlock Text="{Binding FloatValue, StringFormat=\{0:0.0\}}" />

However, if your pattern does not start with a zero, you do not need the escape. Also, if you have whitespace in your pattern, you must surround it with single quotes. For example:

<TextBlock Text="{Binding Animals.Count, StringFormat='I have {0} animals.'}" />

Notice that this means that if your pattern starts with the value that you are binding, then you do need the escape. For example:

<TextBlock Text="{Binding Animals.Count, 
                                StringFormat='{}{0} animals live in the farm.'}" />

info

Whenever a StringFormat parameter is present, the value of the binding will actually be converted using the StringFormatValueConverter (this is one of the built-in converters - see below).

Built-in Conversions

Avalonia has a range of built-in data binding converters. These include:

• a string formatting converter
• null testing converters
• Boolean operation converters

info

For full information on Avalonia built-in data binding converters, see the reference here.

Custom Conversions

If none of the built-in converters are meet your requirements, then you can implement a custom converter.

info

An example of a custom converter can bind an image file. For guidance on how to create a custom converter for an image, see here.