Creating a Data Binding

You can bind a dynamic property of a user interface element to a property of any CLR object. To do this, you must describe the desired correspondence between some item of a data source and the target user-interface element. Each such correspondence, or binding, must specify the following:

• The data source item

• The path to the appropriate value in the data source item

• The target user-interface element

• The appropriate property of the target user-interface element

The Data Binding

The Framework represents a data binding by an instance of the MSAvalon.Data.Bind class. This class has a number of properties that control the data binding: Path , BindType , UpdateType , Transformer , Culture , BindFlags , and Source .

You set the Path property to a string that specifies the property or value in the data source to which the bind object binds. The BindType property controls the direction and frequency of the data bind. It must be one of three values: OneWay, TwoWay, and OneTime. A OneWay bind type causes the data binding to transfer new values from the data source to the target property but it does not propagate changes in the target property back to the data source. A TwoWay bind type propagates changes in both directions. When you specify the OneTime bind type, the data binding transfers the value from the data source to the target property only when you first activate the binding.

You can set the Transformer property to any object that implements the IDataTransformer interface. When the data binding propagates a value, it passes the value through the transformer. The transformer examines the incoming value and produces a new value as output. Note that the input and output values don t need to be the same type. You could have an integer flag as input and produce different image files as output.

The UpdateType property determines when changes to the target property propagate back to the data source when the bind type is TwoWay. You can specify one of three values: Immediate means propagate the new value to the data source immediately after the target property changes; OnLostFocus means propagate the value when the target control loses the input focus; and Explicit says to wait until code calls the bind object and tells it to propagate the new value.

The Source property references the source data item of the binding. You can use the DataSource, ElementSource, DataContextSource, or ObjectSource attributes to set the bind object s Source property. You use the ElementSource attribute to set the Source to an Element by providing the element ID as the value of the ElementSource attribute. The DataContextSource attribute allows you to set the Source to the data context of another element by setting the element ID to the DataContextSource. You use the ObjectSource attribute to specify an object as the source of the binding. Finally, the DataSource attribute allows you to set the Source to the Data property of the DataSource. This will be discussed in detail in The Data Source Item section.

The Culture property allows you to specify a CultureInfo for bindings that need to be culture-aware.

The BindFlags property supports a single nonzero value: NotifyOnTransfer. It s very important to understand that a data binding is inherently asynchronous. When you change the value in the data source, the corresponding target property doesn t receive the updated value right away. It might take an arbitrary amount of time before the new value propagates to the target property. When you need to know when the binding has completed updating the target property, you set the BindFlags property to the NotifyOnTransfer value. The data binding will then fire the MSAvalon.Data.DataTransfer event after updating the target property.

Defining a Binding Expression Using Code

You can create a data binding programmatically, although I expect you ll rarely need or want to do so. Simply create an instance of the Bind class and call the method SetBinding . Here s one possible example:

 using MSAvalon.Data; 
 
 Bind binding = new Bind (); 
 binding.Path = path; 
 binding.BindType = bindType; 
 binding.Source = source; 
 binding.UpdateType = updateType; 
 
 element.SetBinding (property, binding); 

Alternatively, here s another way to write the prior code using one of the Bind class s convenience constructors:

 using MSAvalon.Data; 
 
 Bind binding = new Bind (path, bindType, source, updateType); 
 element.SetBinding (property, binding); 

You could use other convenience methods , such as the SetBinding method on an element, and simplify the prior code to this:

 element.SetBinding (property, path, bindType, source, updateType); 

Defining a Binding Expression Using Markup

I expect you ll prefer to define most data bindings using markup. All the previous concepts still apply ”you create a Bind object, set its properties to the appropriate values, and associate it with a property of a target element. For example, the following markup creates a Bind object as the value of the Button object s Text property.

 <DockPanel xmlns="http://schemas.microsoft.com/2003/xaml" /> 
 <DockPanel.Resources> 
 <myNameSpace:Person def:Name="MyPerson" Name="Bob"/> 
 </DockPanel.Resources> . . . 
 <Button> 
 <Button.Content> 
 <Bind Path="Name" BindType="OneWay" ObjectSource="{MyPerson}" /> 
 </Button.Content> 
 </Button> 

To associate a data binding with a particular user interface element s property, you use the data binding as the value of the property. In the example just shown, the data binding binds the resource called MyPerson to the Text property of the Button element because I defined the data binding between the Button.Text start and end tags.

The DockPanel Resources property declares that the following child elements are resources. Unlike regular XAML elements, which are instantiated when the runtime parses the XAML file, the runtime does not instantiate a resource until you actually use it.

In the prior example, the Source of the bindings is a Person object, therefore the Bind instance references this Person object instance.

The Path attribute specifies the path within the data source item to the value of interest. In the prior example, the path is simply Name , so the binding retrieves the Name property of the Person instance. However, the path could be more complex. For example, if the Name property returned an object with additional structure, the path could be something like Name.FirstName .

The prior example showed how to define a data binding using a complex property definition for the Button.Text property s value. However, you can use an alternative, and considerably more compact, definition for a data-binding expression. In this case, you define a string as the data-binding expression. The string begins with an asterisk character, which the XAML compiler interprets as an escape character, and then the name of the class to instantiate, and then, enclosed in parentheses, a series of semicolon-separated name value pairs.

 <DockPanel > 
   
 <Button Text="*Bind(Path=Name;BindType=OneWay)" /> 
   
 </DockPanel> 

When you define a data binding but don t specify a value for the Source property (using DataSource , ElementSource, DataContextSource or ObjectSource ), the data binding retrieves the data source from the DataContext property for the current element. When the current element has no DataContext , the binding object retrieves the parent element s DataContext recursively. This allows you to define a data source once on the appropriate element in your markup and then use that data source in various bindings on child elements.

In the following example, I set the DataContext property of the DockPanel element to a data binding that references my data source. Effectively, all child elements inherit this DataContext property when they don t otherwise set it to a different value. Because the data bindings on the Button elements do not specify a value for the Source property, the binding uses the source from the inherited DataContext . Of course, you can always specify a source to cause a particular data binding to use a different data source.

 <DockPanel xmlns="http:////schemas.microsoft.com//2003//xaml//" 
 DataContext="{MyPerson}> 
   
 <Button Text=