Data Binding

Silverlight

Data Binding

Data binding provides a simple way for Silverlight-based applications to display and interact with data. The way data is displayed is separated from the management of the data. A connection, or binding, between the UI and a data object allows data to flow between the two. When a binding is established and the data changes, the UI elements that are bound to the data can reflect changes automatically. Similarly, changes made by the user in a UI element can be reflected in the data object. For example, if the user edits the value in a TextBox, the underlying data value is automatically updated to reflect that change.

Some common binding scenarios include binding a ListBox to a list of headlines, an input form's TextBox to a customer data object, or an Image to the current user's photo.

This topic contains the following sections:

Connecting User Interface Elements with Data
Direction of the Data Flow
Change Notification
Updating the Data Source
Binding to Collections
Data Validation
Data Conversions

Connecting User Interface Elements with Data

Every binding must specify a source and a target. The following illustration shows the basic concepts of a binding.

The binding engine gets information from the Binding object about the following:

The target UI property that displays and possibly allows user changes to the data. The target can be any DependencyProperty of a FrameworkElement.
The source object that contains the data that flows between the source and target. The source can be any CLR object, including the target element itself or other UI elements. If the target is in a data template, the source can be the UI element to which the template is applied.
The direction of the data flow. The direction is specified by setting the Mode property on the Binding object.
The optional value converter that applies to the data as it is passed. The value converter is a class that implements IValueConverter.

For example, the Foreground property of a TextBox can be bound to a SolidColorBrush so that the color of the text can change based on the data. In this scenario, the Foreground property is the target, and the SolidColorBrush object is the source for the binding.

The following example shows how to bind the Foreground color of a TextBox to a SolidColorBrush in code and XAML. The binding source is a property of the MyColors class, which is described later in this topic.

<TextBox x:Name="MyTextBox" Text="Text" Foreground="{Binding Brush1, Mode=OneWay}"/>

Visual Basic

' Create an instance of the MyColors class 
' that implements INotifyPropertyChanged. 
Dim textcolor As New MyColors()

' Brush1 is set to be a SolidColorBrush with the value Red. 
textcolor.Brush1 = New SolidColorBrush(Colors.Red)

' Set the DataContext of the TextBox MyTextBox. 
MyTextBox.DataContext = textcolor

// Create an instance of the MyColors class 
// that implements INotifyPropertyChanged.
MyColors textcolor = new MyColors();

// Brush1 is set to be a SolidColorBrush with the value Red.
textcolor.Brush1 = new SolidColorBrush(Colors.Red);

// Set the DataContext of the TextBox MyTextBox.
MyTextBox.DataContext = textcolor;

Note:
This example uses the XAML attribute syntax for creating the binding. You could also use the object element syntax to create the binding in XAML. For more information, see XAML Overview.

The binding is created in XAML using the {Binding ...} syntax. The source is set in code by setting the DataContext property for the TextBox.

Data context is inherited. If you set the data context on a parent element, all its children will use the same data context. A child element can override this behavior by setting the Source property on its binding object or by setting its DataContext, which will then apply to all its children.

Setting the data context is useful when you want to have multiple bindings that all use the same source. To set the source for a single binding, set the Source property on the Binding object. For more information, see How to: Create a Binding.

You can also use the ElementName property or the RelativeSource property to specify the binding source. The ElementName property is useful when you are binding to other elements in your application, such as when you are using a slider to adjust the width of a button. The RelativeSource property is useful when the binding is specified in a ControlTemplate or a Style. For more information, see Binding Markup Extension and RelativeSource Markup Extension.

Altogether, the preceding example causes the binding engine to create a binding, which is OneWay by default, connecting the Foreground property of the TextBox to the brush1 property of the TextColor object.

Direction of the Data Flow

Each binding has a Mode property, which determines how and when the data flows. Silverlight enables three types of bindings:

OneTime bindings update the target with the source data when the binding is created.
OneWay bindings update the target with the source data when the binding is created and anytime the data changes. This is the default mode.
TwoWay bindings update both the target and the source when either changes. Alternately, you can disable automatic source updates and update the source only at times of your choosing.

In order for automatic target updates to occur, the source object must implement the INotifyPropertyChanged interface, as described in the next section.

Change Notification

In order for changes to the source object to propagate to the target, the source must implement the INotifyPropertyChanged interface. INotifyPropertyChanged has the PropertyChanged event, which tells the binding engine that the source has changed so that the binding engine can update the target value.

In the following example, the MyColors class implements the INotifyPropertyChanged interface for OneWay binding.

Visual Basic

' Create a class that implements INotifyPropertyChanged. 
Public Class MyColors
    Implements INotifyPropertyChanged
    Private _Brush1 As SolidColorBrush

    ' Declare the PropertyChanged event. 
    Public Event PropertyChanged As PropertyChangedEventHandler _
        Implements INotifyPropertyChanged.PropertyChanged

    ' Create the property that will be the source of the binding. 
    Public Property Brush1() As SolidColorBrush
        Get
            Return _Brush1
        End Get
        Set(ByVal value As SolidColorBrush)
            _Brush1 = value
            ' Call NotifyPropertyChanged when the source property 
            ' is updated. 
            NotifyPropertyChanged("Brush1")
        End Set
    End Property


    ' NotifyPropertyChanged will raise the PropertyChanged event, 
    ' passing 
the source property that is being updated. 
    Public Sub NotifyPropertyChanged(ByVal propertyName As String)
        RaiseEvent PropertyChanged(Me, _
            New PropertyChangedEventArgs(propertyName))
    End Sub


End Class

// Create a class that implements INotifyPropertyChanged.
public class MyColors : INotifyPropertyChanged
{
    private SolidColorBrush _Brush1;

    // Declare the PropertyChanged event.
    public event PropertyChangedEventHandler PropertyChanged;

    // Create the property that will be the source of the binding.
    public SolidColorBrush Brush1
    {
        get { return _Brush1; }
        set
        {
            _Brush1 = value;
            // Call NotifyPropertyChanged when the source property 
            // is updated.
            NotifyPropertyChanged("Brush1");
        }
    }


    // NotifyPropertyChanged will raise the PropertyChanged event, 
    // passing the source property that is being updated.
    public void NotifyPropertyChanged(string propertyName)
    {
        if (PropertyChanged != null)
        {
            PropertyChanged(this, 
                new PropertyChangedEventArgs(propertyName));
        }
    }
}

To get change notification for collections bound to an ItemsControl, implement INotifyCollectionChanged in addition to INotifyPropertyChanged. If you implement INotifyCollectionChanged, changes to the collection, such as adding or removing an object, will propagate to the target. To get property change notification for objects in the collection, the objects must implement INotifyPropertyChanged.

Before implementing your own collection, consider using the ObservableCollection<(Of <(T>)>) class, which has a built-in implementation of INotifyCollectionChanged and INotifyPropertyChanged.

Updating the Data Source

In TwoWay bindings, changes to the target automatically update the source, except when binding to the Text property of a TextBox. In this case, the update occurs when the TextBox loses focus.

You can disable automatic source updates and update the source at times of your choosing. For example, you can do this to validate user input from multiple controls before you update the bound data sources.

To disable automatic source updates, set the UpdateSourceTrigger property to Explicit. This setting affects all bindings that use the same Binding object (for example, when using an inherited data context). You must update the source for each binding individually, however. To update a binding, first call the FrameworkElement..::.GetBindingExpression method of a target element, passing in the target DependencyProperty. You can then use the return value to call the BindingExpression..::.UpdateSource method. The following example code demonstrates this process.

<TextBox x:Name="textBox1" Text="{Binding Test, Mode=TwoWay, UpdateSourceTrigger=Explicit}" />
<Button Content="Update" Click="Button_Click" />

Visual Basic

Public Class TestData
    Private testValue As String
    Public Property Test() As String
        Get
            Return testValue
        End Get
        Set(ByVal value As String)
            testValue = value
        End Set
    End Property
End Class

Private data As TestData

Public Sub New()

    InitializeComponent()

    data = New TestData
    With data
        .Test = "one"
    End With

    textBox1.DataContext = data

End Sub

Private Sub Button_Click(ByVal sender As Object, _
    ByVal e As RoutedEventArgs)

    Dim expression As BindingExpression = _
        textBox1.GetBindingExpression(TextBox.TextProperty)
    MessageBox.Show("Before UpdateSource, Test = " & data.Test)
    expression.UpdateSource()
    MessageBox.Show("After UpdateSource, Test = " & data.Test)

End Sub

public class TestData
{
    public String Test { get; set; }
}

TestData data;

public MainPage()
{
    InitializeComponent();
    data = new TestData { Test = "one" };
    textBox1.DataContext = data;
}

private void Button_Click(object sender, RoutedEventArgs e)
{
    BindingExpression expression = textBox1.GetBindingExpression(TextBox.TextProperty);
    MessageBox.Show("Before UpdateSource, Test = " + data.Test);
    expression.UpdateSource();
    MessageBox.Show("After UpdateSource, Test = " + data.Test);
}

Binding to Collections

A binding source object can be treated either as a single object whose properties contain data or as a collection of objects. For example, you might want to display a list of items, such as monthly credit card bills. To do this, use an ItemsControl and repeat over a DataTemplate to display each item in a collection. For more information on data templates, see How to: Customize Data Display with Data Templates.

    <Grid.Resources>

      <DataTemplate x:Name="dataTemplate">
   
        <Grid>
          <Grid.ColumnDefinitions>
 
            <ColumnDefinition />

            <ColumnDefinition />
          </Grid.ColumnDefinitions>
<TextBlock Grid.Column="0" 
 
  Text="{Binding Month, Converter={StaticResource Converter1}}"/>

          <TextBlock Grid.Column="1" Text="{Binding Total}"/>    
        </Grid>
      </DataTemplate>

    </Grid.Resources>

    <ItemsControl x:Name="IC1" ItemsSource="{Binding}" 
      ItemTemplate="{StaticResource dataTemplate}"/>

You can enumerate over any collection that implements IEnumerable. If you want the target to update the ItemsSource when the collection changes, implement INotifyCollectionChanged. For more information on change notification, see the Change Notification section earlier in this topic.

For more information on creating a binding to a data collection, see Walkthrough: Binding to a Collection and Creating a Master/Details View.

For information about encapsulating a generic list in an object so that you can bind a control to it, see the first code examples for List<(Of <(T>)>) and Dictionary<(Of <(TKey, TValue>)>).

Data Validation

Silverlight supports basic data validation in TwoWay bindings for target-to-source updates. Silverlight reports a validation error in the following cases:

Exceptions thrown from the binding engine's type converter.
Exceptions thrown from the binding object's set accessor.
Exceptions thrown from a validation attribute that is applied to a data object or member.

Silverlight provides visual feedback for validation errors when you set the ValidatesOnExceptions property to true on the binding object. The visual feedback indicates the control that contains the error, and displays the error message nearby, as shown in the following illustration.

the visual feedback for a validation error

You can customize the visual feedback for a control by modifying or replacing its default ControlTemplate. For more information, see Control Customization.

In order to receive notification that a validation error has occurred, you must also set the NotifyOnValidationError property to true on the binding object. Setting ValidatesOnExceptions to true tells the binding engine to create a validation error when an exception occurs. Setting NotifyOnValidationError to true tells the binding engine to raise the BindingValidationError event when a validation error occurs and resolves. For example, you can handle the error event to log the error or provide additional visual feedback.

To handle the BindingValidationError event, create an event handler on the target object or any of its parents. The BindingValidationError event is a routed event, so if you do not handle it on the element that raised the event, it will continue to bubble up until it is handled. For more information on routed events, see Events Overview for Silverlight.

The following example shows how to provide custom binding validation.

The binding is created in XAML.

<StackPanel BindingValidationError="StackPanel_BindingValidationError" >
    <StackPanel.Resources>
        <my:Bills x:Name="MyBills"/>
    </StackPanel.Resources>
    <TextBox x:Name="MyTextBox" Width="50" Margin="10">
        <TextBox.Text>
            <Binding Mode="TwoWay" Source="{StaticResource MyBills}" 
                     Path="Amount" NotifyOnValidationError="true" 
                     ValidatesOnExceptions="true"/>
        </TextBox.Text>
    </TextBox>
    <Button Height="50" Width="150" Content="Click To Update Source"/>
</StackPanel>

The source object throws an exception in the set accessor if the value is negative.

Visual Basic

Public Class Bills
    Private _Amount As Double
    Public Property Amount() As Double
        Get
            Return _Amount
        End Get
        Set(ByVal value As Double)
            If value < 0 Then
                Throw New Exception("Amount must be greater than zero.")
            End If
            _Amount = value
        End Set
    End Property

End Class

public class Bills
{
    private double _Amount;
    public double Amount
    {
        get { return _Amount; }
        set
        {
            if (value < 0)
                throw new Exception("Amount must be greater than zero.");
            _Amount = value;
        }
    }

}

The StackPanel implements a handler for the BindingValidationError event.

Visual Basic

Private Sub StackPanel_BindingValidationError(ByVal sender As Object, _
    ByVal e As ValidationErrorEventArgs)

    If e.Action = ValidationErrorEventAction.Added Then

        MyTextBox.Background = New SolidColorBrush(Colors.Red)
    ElseIf e.Action = ValidationErrorEventAction.Removed Then
        MyTextBox.Background = New SolidColorBrush(Colors.White)
    End If

End Sub

private void StackPanel_BindingValidationError(object sender, 
    ValidationErrorEventArgs e)
{
    if (e.Action == ValidationErrorEventAction.Added)
    {
        MyTextBox.Background = new SolidColorBrush(Colors.Red);

    }
    else if (e.Action == ValidationErrorEventAction.Removed)
    {
        MyTextBox.Background = new SolidColorBrush(Colors.White);
    }
}

Run this sample

After the sample starts, type in letters instead of numbers to get an error caused by the type converter. Type in a negative number to get an error from the source object's set accessor. Type in a positive number to resolve the validation error. TextBox target-to-source updates occur only when the TextBox loses focus. The button is provided to change the focus. If you prefer, you can update the source manually in response to the button click, as described earlier in the Updating the Data Source section.

For information about applying validation attributes to specify the allowed values for a property or object, see Using Data Annotations to Customize Data Classes. For information about providing more detailed validation reporting, see the ValidationSummary class overview.

Data Conversions

You may need to display data in a format that differs from how it is stored. Some examples are the following:

Storing a color as an RGBA value but displaying it as a string name.
Storing a number as a floating-point value but displaying it as a currency value.
Storing a date as DateTime but displaying it in a calendar.

A converter can be set on any binding. The converter is customized for each scenario by creating a class and implementing the IValueConverter interface. The following example shows how to implement IValueConverter.

Visual Basic

' Custom class implements the IValueConverter interface.
Public Class DateToStringConverter
    Implements IValueConverter

    ' Define the Convert method to change a DateTime object to
    ' a month string.
    Public Function Convert(ByVal value As Object, _
        ByVal targetType As Type, ByVal parameter As Object, _
        ByVal culture As System.Globalization.CultureInfo) As Object _
        Implements IValueConverter.Convert

        ' value is the data from the source object.
        Dim thisdate As DateTime = CType(value, DateTime)
        Dim monthnum As Integer = thisdate.Month
        Dim month As String
        Select Case (monthnum)
            Case 1
                month = "January"
            Case 2
                month = "February"
            Case Else
                month = "Month not found"
        End Select
        ' Return the value to pass to the target.
        Return month

    End Function

    ' ConvertBack is not implemented for a OneWay binding.
    Public Function ConvertBack(ByVal value As Object, _
        ByVal targetType As Type, ByVal parameter As Object, _
        ByVal culture As System.Globalization.CultureInfo) As Object _
        Implements IValueConverter.ConvertBack



        Throw New NotImplementedException

    End Function
End Class

// Custom class implements the IValueConverter interface.
public class DateToStringConverter : IValueConverter
{

    #region IValueConverter Members

    // Define the Convert method to change a DateTime object to 
    // a month string.
    public object Convert(object value, Type targetType, 
        object parameter, 
System.Globalization.CultureInfo culture)
    {
        // value is the data from the source object.
        DateTime thisdate = (DateTime)value;
        int monthnum = thisdate.Month;
        string month;
        switch (monthnum)
        {
            case 1:
                month = "January";
                break;
            case 2:
                month = "February";
                break;
            default:
                month = "Month not found";
                break;
        }
        // Return the value to pass to the target.
        return month;

    }

    // ConvertBack is not implemented for a OneWay binding.
    public object ConvertBack(object value, Type targetType, 
        object parameter, System.Globalization.CultureInfo culture)
    {
        throw new NotImplementedException();
    }

    #endregion
}

The Convert and ConvertBack methods are called by the binding engine if the Converter parameter is defined for the binding. When data is passed from the source, the binding engine calls Convert and passes the returned data to the target. When data is passed from the target, the binding engine calls ConvertBack and passes the returned data to the source. The following example shows how to set the Converter parameter.

<UserControl.Resources>
  <local:DateToStringConverter x:Key="Converter1"/>
</UserControl.Resources>


...


<TextBlock Grid.Column="0" 
 
  Text="{Binding Month, Converter={StaticResource Converter1}}"/>

The converter also has optional parameters: ConverterCulture, which allows specifying the culture to be used in the conversion, and ConverterParameter, which allows passing a parameter for the conversion logic. For an example using these parameters, see IValueConverter.

If there is an error in the conversion, do not throw an exception. Instead, return DependencyProperty..::.UnsetValue, which will stop the data transfer.

Tasks

Reference

Concepts

Other Resources