Tools

Namespaces

Variants

Views

Actions

Search

Contents

Please note that as of October 24, 2014, the Nokia Developer Wiki will no longer be accepting user contributions, including new entries, edits and comments, as we begin transitioning to our new home, in the Windows Phone Development Wiki. We plan to move over the majority of the existing entries. Thanks for all your past and future contributions.

{{Anchor|BindingMode}}There are a number of different binding modes, as defined in the [http://msdn.microsoft.com/en-us/library/system.windows.data.bindingmode.aspx BindingMode] enumeration:

{{Anchor|BindingMode}}There are a number of different binding modes, as defined in the [http://msdn.microsoft.com/en-us/library/system.windows.data.bindingmode.aspx BindingMode] enumeration:

−

* ''TwoWay'' - changes to the UI or model automatically update the other. This is used for editable forms or other interactive scenarios.

+

* {{Icode|TwoWay}} - changes to the UI or model automatically update the other. This is used for editable forms or other interactive scenarios.

−

* ''OneWay'' - updates the UI when the model changes. This is approriate for read-only controls populated from data.

+

* {{Icode|OneWay}} - updates the UI when the model changes. This is appropriate for read-only controls populated from data.

−

* ''OneTime'' - updates the UI when the application starts or when the data context changes. This is used when the source data is static/does not change.

+

* {{Icode|OneTime}} - updates the UI when the application starts or when the data context changes. This is used when the source data is static/does not change.

−

* ''OneWayToSource'' - changes to the UI update the model

+

* {{Icode|OneWayToSource}} - changes to the UI update the model

* ''Default'' - uses the default mode for the particular binding target (UI control). This differs based on the control.

* ''Default'' - uses the default mode for the particular binding target (UI control). This differs based on the control.

−

This code example shows how bind {{Icode|TextBox}} controls in XAML to a source object defined in the C# file. It covers ''OneTime'', ''OneWay'' and ''TwoWay'' modes. For the modes where the source (model) updates the UI (target) it also shows how to use the [http://msdn.microsoft.com/en-us/library/system.componentmodel.inotifypropertychanged%28v&#61;vs.95%29.aspx INotifyPropertyChanged] interface class to ensure that the UI is updated whenever the underlying code changes.

+

This code example shows how bind {{Icode|TextBox}} controls in XAML to a source object defined in the C# file. It covers {{Icode|OneTime}}, {{Icode|OneWay}} and {{Icode|TwoWay}} modes. For the modes where the source (model) updates the UI (target) it also shows how to use the [http://msdn.microsoft.com/en-us/library/system.componentmodel.inotifypropertychanged%28v&#61;vs.95%29.aspx INotifyPropertyChanged] interface class to ensure that the UI is updated whenever the underlying code changes.

The associated example creates three text boxes in XAML, and uses binding to update their values with information from C# objects.

The associated example creates three text boxes in XAML, and uses binding to update their values with information from C# objects.

Line 76:

Line 73:

In this example we specify the particular properties of the bound object to use for the Text (ie the {{Icode|manufacturer}} property of the bound object will be used for the text value of the {{Icode|manufacturerBox}} property). We also specify the mode as ''OneTime'' so that the UI is updated from the model on page load (only).

In this example we specify the particular properties of the bound object to use for the Text (ie the {{Icode|manufacturer}} property of the bound object will be used for the text value of the {{Icode|manufacturerBox}} property). We also specify the mode as ''OneTime'' so that the UI is updated from the model on page load (only).

{{Tip|It is always best to specify the mode you want to use explicitly as this will often result in better performance. <br />

{{Tip|It is always best to specify the mode you want to use explicitly as this will often result in better performance. <br />

−

If we omitted the mode the code would still "work" - the default mode of the {{Icode|TextBox}} is ''TwoWay'' but without implementing {{Icode|INotifyPropertyChanged}} the result would be a one time update. However it would be less efficient because ''OneTime'' mode offers better performance. }}

+

If we omitted the mode the code would still "work" - the default mode of the {{Icode|TextBox}} is ''TwoWay''. But without implementing {{Icode|INotifyPropertyChanged}} the result would be a one time update of the TextBox's content from code. Input into the {{Icode|TextBox}} will still be stored in the bound property though. }}

+

The updated XAML code looks like:

The updated XAML code looks like:

<code xml>

<code xml>

Line 88:

Line 86:

At this point we still haven't defined the data source (though we know from the XAML it has properties {{Icode|manufacturer}}, {{Icode|model}} and {{Icode|software}}) and bound it to the XAML. This is done in the C# code, which we define in the following sections.

At this point we still haven't defined the data source (though we know from the XAML it has properties {{Icode|manufacturer}}, {{Icode|model}} and {{Icode|software}}) and bound it to the XAML. This is done in the C# code, which we define in the following sections.

Windows Phone apps typically define their UI declaratively using XAML (in Expression Blend). While some UI component values may be hardcoded in XAML, many will be provided by data sources (objects, databases, XML feeds). Data binding is the technique which provides the connection between the XAML components and their values as defined in code.

There are a number of different binding modes, as defined in the BindingMode enumeration:

TwoWay - changes to the UI or model automatically update the other. This is used for editable forms or other interactive scenarios.

OneWay - updates the UI when the model changes. This is appropriate for read-only controls populated from data.

OneTime - updates the UI when the application starts or when the data context changes. This is used when the source data is static/does not change.

OneWayToSource - changes to the UI update the model

Default - uses the default mode for the particular binding target (UI control). This differs based on the control.

This code example shows how bind TextBox controls in XAML to a source object defined in the C# file. It covers OneTime, OneWay and TwoWay modes. For the modes where the source (model) updates the UI (target) it also shows how to use the INotifyPropertyChanged interface class to ensure that the UI is updated whenever the underlying code changes.

The associated example creates three text boxes in XAML, and uses binding to update their values with information from C# objects.

First we create a simple Windows Phone page which contains a title panel followed by a content panel (Grid) containing three TextBox - which will display manufacturer, software and model text. Note that the content Grid is named ContentPanel, and we will later use this name to bind to the XAML from the C# code (and similarly the Names of each of the TextBoxes).

<!--LayoutRoot is the root grid where all page content is placed--><Gridx:Name="LayoutRoot"Background="Transparent"><Grid.RowDefinitions><RowDefinitionHeight="Auto"/><RowDefinitionHeight="*"/></Grid.RowDefinitions>

<!--TitlePanel contains the name of the application and page title--><StackPanelx:Name="TitlePanel"Grid.Row="0"Margin="12,17,0,28"><TextBlockx:Name="ApplicationTitle"Text="MY APPLICATION"Style="{StaticResource PhoneTextNormalStyle}"/><TextBlockx:Name="PageTitle"Text="DataBindingExample"Margin="9,-7,0,0"Style="{StaticResource PhoneTextTitle1Style}"/></StackPanel>

The above XAML code contains hard-coded Text property values for the manufacturer, model and software. To bind the controls to data we first need to update the required properties with the {Binding} keyword. The keyword allows us to specify the name of the property we want to bind to, and the binding mode (ie whether changes to the UI will propagate to the underlying object and visa versa). Both of these two properties are optional: if you just specify {Binding} then the bound object's ToString() method will be called to get the property value and the binding will be the default for the target object..

In this example we specify the particular properties of the bound object to use for the Text (ie the manufacturer property of the bound object will be used for the text value of the manufacturerBox property). We also specify the mode as OneTime so that the UI is updated from the model on page load (only).

Tip: It is always best to specify the mode you want to use explicitly as this will often result in better performance.
If we omitted the mode the code would still "work" - the default mode of the TextBox is TwoWay. But without implementing INotifyPropertyChanged the result would be a one time update of the TextBox's content from code. Input into the TextBox will still be stored in the bound property though.

At this point we still haven't defined the data source (though we know from the XAML it has properties manufacturer, model and software) and bound it to the XAML. This is done in the C# code, which we define in the following sections.

The next step is to create an instance of the PhoneModel and bind it to the XAML, which we do using the DataContext property. The best place to perform the binding is when page initialisation completes, in the MainPage_Loaded() event handler as shown below.

The ContentPanel is a reference to the Grid object defined in XAML (Grid x:Name="ContentPanel"). We bind to this by assigning our PhoneModel instance to the referenced object's DataContext. Now when the page is loaded the the properties will be taken from our PhoneModel instance when the page is loaded. This results in the screen shown in #Figure1.

At this point the binding is OneTime (the properties are updated in the UI only on page load and changes to the UI do not affect the C# object values). The following sections explain how you can make the UI responsive to changes to the model, and how to make the model responsive to changes in the UI after loading (TwoWay binding).

To update the UI in response to changes in the source (model) we first need to update the XAML to state that this the Mode is OneWay or TwoWay binding. For a one-way binding all the TextBox definitions would be changed as below:

In addition, in order to update the UI when a property changes in code, we also need to update the PhoneModel class to implement INotifyPropertyChanged. The new PhoneModel.cs with this change is shown below:

The above code snippet creates a utility method named NotifyPropertyChanged, that raises the PropertyChanged event with the name of the property which needs to be updated in the UI. All properties need to call this NotifyPropertyChanged utility method.

To update the properties of the model and to see whether the UI get's updated or not we will add a button and on click event of the button we will change our properties and will see if the UI get updates or not, so the code for MainPage.xaml.cs goes like:

To integrate TwoWay mode binding in our example application, lets add one Button and three TextBlock's to the Grid. We then change the data in the TextBox, and will see if updated data is pushed back to the DataContext by clicking the Read Model Button - this reads the data from the model object and should update the TextBlock's Text property.