As mentioned previously and as indicated by the arrow in the figure above, the data flow of a binding can go from the binding target to the binding source (for example, the source value changes when a user edits the value of a TextBox) and/or from the binding source to the binding target (for example, your TextBox content gets updated with changes in the binding source) if the binding source provides the proper notifications.

You may want your application to enable users to change the data and propagate it back to the source object. Or you may not want to enable users to update the source data. You can control this by setting the Mode property of your Binding object. The following figure illustrates the different types of data flow:

• OneWay binding causes changes to the source property to automatically update the target property, but changes to the target property are not propagated back to the source property. This type of binding is appropriate if the control being bound is implicitly read-only. For instance, you may bind to a source such as a stock ticker or perhaps your target property has no control interface provided for making changes, such as a data-bound background color of a table. If there is no need to monitor the changes of the target property, using the OneWay binding mode avoids the overhead of the TwoWay binding mode.

• TwoWay binding causes changes to either the source property or the target property to automatically update the other. This type of binding is appropriate for editable forms or other fully-interactive UI scenarios. Most properties default to OneWay binding, but some dependency properties (typically properties of user-editable controls such as the Text property of TextBox and the IsChecked property of CheckBox) default to TwoWay binding. A programmatic way to determine whether a dependency property binds one-way or two-way by default is to get the property metadata of the property using GetMetadata and then check the Boolean value of the BindsTwoWayByDefault property.

• OneWayToSource is the reverse of OneWay binding; it updates the source property when the target property changes. One example scenario is if you only need to re-evaluate the source value from the UI.

• Not illustrated in the figure is OneTime binding, which causes the source property to initialize the target property, but subsequent changes do not propagate. This means that if the data context undergoes a change or the object in the data context changes, then the change is not reflected in the target property. This type of binding is appropriate if you are using data where either a snapshot of the current state is appropriate to use or the data is truly static. This type of binding is also useful if you want to initialize your target property with some value from a source property and the data context is not known in advance. This is essentially a simpler form of OneWay binding that provides better performance in cases where the source value does not change.

Note that to detect source changes (applicable to OneWay and TwoWay bindings), the source must implement a suitable property change notification mechanism such as INotifyPropertyChanged. See How to: Implement Property Change Notification for an example of an INotifyPropertyChanged implementation.

The Mode property page provides more information about binding modes and an example of how to specify the direction of a binding.

Bindings that are TwoWay or OneWayToSource listen for changes in the target property and propagate them back to the source. This is known as updating the source. For example, you may edit the text of a TextBox to change the underlying source value. As described in the last section, the direction of the data flow is determined by the value of the Mode property of the binding.

However, does your source value get updated while you are editing the text or after you finish editing the text and point your mouse away from the TextBox? The UpdateSourceTrigger property of the binding determines what triggers the update of the source. The dots of the right arrows in the following figure illustrate the role of the UpdateSourceTrigger property:

If the UpdateSourceTrigger value is PropertyChanged, then the value pointed to by the right arrow of TwoWay or the OneWayToSource bindings gets updated as soon as the target property changes. However, if the UpdateSourceTrigger value is LostFocus, then that value only gets updated with the new value when the target property loses focus.

Similar to the Mode property, different dependency properties have different default UpdateSourceTrigger values. The default value for most dependency properties is PropertyChanged, while the Text property has a default value of LostFocus. This means that source updates usually happen whenever the target property changes, which is fine for CheckBoxes and other simple controls. However, for text fields, updating after every keystroke can diminish performance and it denies the user the usual opportunity to backspace and fix typing errors before committing to the new value. That is why the Text property has a default value of LostFocus instead of PropertyChanged.

See the UpdateSourceTrigger property page for information about how to find the default UpdateSourceTrigger value of a dependency property.

The following table provides an example scenario for each UpdateSourceTrigger value using the TextBox as an example:

For an example, see How to: Control When the TextBox Text Updates the Source.

Notice that in the previous example, the binding source is specified by setting the DataContext property on the DockPanel element. The Button then inherits the DataContext value from the DockPanel, which is its parent element. To reiterate, the binding source object is one of the four necessary components of a binding. Therefore, without the binding source object being specified, the binding would do nothing.

There are several ways to specify the binding source object. Using the DataContext property on a parent element is useful when you are binding multiple properties to the same source. However, sometimes it may be more appropriate to specify the binding source on individual binding declarations. For the previous example, instead of using the DataContext property, you can specify the binding source by setting the Source property directly on the binding declaration of the button, as in the following example:

<DockPanel.Resources>
  <c:MyData x:Key="myDataSource"/>
</DockPanel.Resources>
<Button Width="150" Height="30"
        Background="{Binding Source={StaticResource myDataSource},
                             Path=ColorName}">I am bound to be RED!</Button>

Other than setting the DataContext property on an element directly, inheriting the DataContext value from an ancestor (such as the button in the first example), and explicitly specifying the binding source by setting the Source property on the Binding (such as the button the last example), 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 How to: Specify the Binding Source.

If your binding source is an object, you use the Path property to specify the value to use for your binding. If you are binding to XML data, you use the XPath property to specify the value. In some cases, it may be applicable to use the Path property even when your data is XML. For example, if you want to access the Name property of a returned XmlNode (as a result of an XPath query), you should use the Path property in addition to the XPath property.

For syntax information and examples, see the Path and XPath property pages.

Note that although we have emphasized that the Path to the value to use is one of the four necessary components of a binding, in the scenarios which you want to bind to an entire object, the value to use would be the same as the binding source object. In those cases, it is applicable to not specify a Path. Consider the following example:

<ListBox ItemsSource="{Binding}"
         IsSynchronizedWithCurrentItem="true"/>

The above example uses the empty binding syntax: {Binding}. In this case, the ListBox inherits the DataContext from a parent DockPanel element (not shown in this example). When the path is not specified, the default is to bind to the entire object. In other words, in this example, the path has been left out because we are binding the ItemsSource property to the entire object. (See the Binding to Collections section for an in-depth discussion.)

Other than binding to a collection, this scenario is also useful when you want to bind to an entire object instead of just a single property of an object. For example, if your source object is of type string and you simply want to bind to the string itself. Another common scenario is when you want to bind an element to an object with several properties.

Note that you may need to apply custom logic so that the data is meaningful to your bound target property. The custom logic may be in the form of a custom converter (if default type conversion does not exist). See Data Conversion for information about converters.

Before getting into other features and usages of data binding, it would be useful to introduce the BindingExpression class. As you have seen in previous sections, the Binding class is the high-level class for the declaration of a binding; the Binding class provides many properties that allow you to specify the characteristics of a binding. A related class, BindingExpression, is the underlying object that maintains the connection between the source and the target. A binding contains all the information that can be shared across several binding expressions. A BindingExpression is an instance expression that cannot be shared and contains all the instance information of the Binding.

For example, consider the following, where myDataObject is an instance of MyData class, myBinding is the source Binding object, and MyData class is a defined class that contains a string property named MyDataProperty. This example binds the text content of mytext, an instance of TextBlock, to MyDataProperty.

Dim data1 As New MyData(DateTime.Now)
Dim binding1 As New Binding("MyDataProperty")
binding1.Source = data1
Me.myText.SetBinding(TextBlock.TextProperty, binding1)

//make a new source
  MyData myDataObject = new MyData(DateTime.Now);      
  Binding myBinding = new Binding("MyDataProperty");
  myBinding.Source = myDataObject;
  myText.SetBinding(TextBlock.TextProperty, myBinding);

You can use the same myBinding object to create other bindings. For example, you may use myBinding object to bind the text content of a check box to MyDataProperty. In that scenario, there will be two instances of BindingExpression sharing the myBinding object.

A BindingExpression object can be obtained through the return value of calling GetBindingExpression on a data-bound object. The following topics demonstrate some of the usages of the BindingExpression class:

• How to: Get the Binding Object from a Bound Target Property

• How to: Control When the TextBox Text Updates the Source

You can enumerate over any collection that implements the IEnumerable interface. However, to set up dynamic bindings so that insertions or deletions in the collection update the UI automatically, the collection must implement the INotifyCollectionChanged interface. This interface exposes an event that should be raised whenever the underlying collection changes.

WPF provides the ObservableCollection<(Of <(T>)>) class, which is a built-in implementation of a data collection that exposes the INotifyCollectionChanged interface. Note that to fully support transferring data values from source objects to targets, each object in your collection that supports bindable properties must also implement the INotifyPropertyChanged interface. For more information, see Binding Sources Overview.

Before implementing your own collection, consider using ObservableCollection<(Of <(T>)>) or one of the existing collection classes, such as List<(Of <(T>)>), Collection<(Of <(T>)>), and BindingList<(Of <(T>)>), among many others. If you have an advanced scenario and want to implement your own collection, consider using IList, which provides a non-generic collection of objects that can be individually accessed by index and thus the best performance.

Once your ItemsControl is bound to a data collection, you may want to sort, filter, or group the data. To do that, you use collection views, which are classes that implement the ICollectionView interface.

This section contains the following subsections.

• What Are Collection Views?
• How to Create a View
• Sorting
• Filtering
• Grouping
• Current Item Pointers
• Master-Detail Binding Scenario

What Are Collection Views?

How to Create a View

<Window.Resources>


...


<CollectionViewSource 
      Source="{Binding Source={x:Static Application.Current}, Path=AuctionItems}"   
      x:Key="listingDataView" />


...


</Window.Resources>

<ListBox Name="Master" Grid.Row="2" Grid.ColumnSpan="3" Margin="8"
    ItemsSource="{Binding Source={StaticResource listingDataView}}">


...


</ListBox>

Sorting

private void AddSorting(object sender, RoutedEventArgs args)
{
    // This sorts the items first by Category and within each Category,
    // by StartDate. Notice that because Category is an enumeration,
    // the order of the items is the same as in the enumeration declaration
    listingDataView.SortDescriptions.Add(
        new SortDescription("Category", ListSortDirection.Ascending));
    listingDataView.SortDescriptions.Add(
        new SortDescription("StartDate", ListSortDirection.Ascending));
}

Filtering

listingDataView.Filter += new FilterEventHandler(ShowOnlyBargainsFilter);

private void ShowOnlyBargainsFilter(object sender, FilterEventArgs e)
{
    AuctionItem product = e.Item as AuctionItem;
    if (product != null)
    {
        // Filter out products with price 25 or above
        if (product.CurrentPrice < 25)
        {
            e.Accepted = true;
        }
        else
        {
            e.Accepted = false;
        }
    }
}

Grouping

// This groups the items in the view by the property "Category"
PropertyGroupDescription groupDescription = new PropertyGroupDescription();
groupDescription.PropertyName = "Category";
listingDataView.GroupDescriptions.Add(groupDescription);

Current Item Pointers

<Button Content="{Binding }" />
<Button Content="{Binding Path=/}" />
<Button Content="{Binding Path=/Description}" /> 

<Button Content="{Binding /Offices/}" />

Master-Detail Binding Scenario

<ListBox Name="Master" Grid.Row="2" Grid.ColumnSpan="3" Margin="8"
    ItemsSource="{Binding Source={StaticResource listingDataView}}">


...


</ListBox>


...


<ContentControl Name="Detail" Grid.Row="3" Grid.ColumnSpan="3" 
        Content="{Binding Source={StaticResource listingDataView}}" 
        ContentTemplate="{StaticResource detailsProductListingTemplate}" 
        Margin="9,0,0,0"/>

The WPF data binding model allows you to associate ValidationRules with your Binding object. For example, the following example binds a TextBox to a property named StartPrice and adds a ExceptionValidationRule object to the Binding..::.ValidationRules property.

<TextBox Name="StartPriceEntryForm" Grid.Row="2" Grid.Column="1"
    Style="{StaticResource textStyleTextBox}" Margin="8,5,0,5">
  <TextBox.Text>
    <Binding Path="StartPrice" UpdateSourceTrigger="PropertyChanged">
      <Binding.ValidationRules>
        <ExceptionValidationRule />
      </Binding.ValidationRules>
    </Binding>
  </TextBox.Text>
</TextBox>

A ValidationRule object checks whether the value of a property is valid. WPF has the following two types of built-in ValidationRule objects:

• A ExceptionValidationRule checks for exceptions thrown during the update of the binding source property. In the previous example, StartPrice is of type integer. When the user enters a value that cannot be converted to an integer, an exception is thrown, causing the binding to be marked as invalid. An alternative syntax to setting the ExceptionValidationRule explicitly is to set the ValidatesOnExceptions property to true on your Binding or MultiBinding object.

• A DataErrorValidationRule object checks for errors that are raised by objects that implement the IDataErrorInfo interface. For an example of using this validation rule, see DataErrorValidationRule. An alternative syntax to setting the DataErrorValidationRule explicitly is to set the ValidatesOnDataErrors property to true on your Binding or MultiBinding object.

You can also create your own validation rule by deriving from the ValidationRule class and implementing the Validate method. The following example shows the rule used by the Add Product Listing "Start Date" TextBox from the What Is Data Binding? section:

class FutureDateRule : ValidationRule
{
    public override ValidationResult Validate(object value, CultureInfo cultureInfo)
    {
        DateTime date;
        try
        {
            date = DateTime.Parse(value.ToString());
        }
        catch (FormatException)
        {
            return new ValidationResult(false, "Value is not a valid date.");
        }
        if (DateTime.Now.Date > date)
        {
            return new ValidationResult(false, "Please enter a date in the future.");
        }
        else
        {
            return ValidationResult.ValidResult;
        }
    }
}

The StartDateEntryForm TextBox uses this FutureDateRule, as shown in the following example:

<TextBox Name="StartDateEntryForm" Grid.Row="3" Grid.Column="1" 
    Validation.ErrorTemplate="{StaticResource validationTemplate}" 
    Style="{StaticResource textStyleTextBox}" Margin="8,5,0,5">
    <TextBox.Text>
        <Binding Path="StartDate" UpdateSourceTrigger="PropertyChanged" 
            Converter="{StaticResource dateConverter}" >
            <Binding.ValidationRules>
                <src:FutureDateRule />
            </Binding.ValidationRules>
        </Binding>
    </TextBox.Text>
</TextBox>

Note that because the UpdateSourceTrigger value is PropertyChanged, the binding engine updates the source value on every keystroke, which means it also checks every rule in the ValidationRules collection on every keystroke. We discuss this further in the Validation Process section.

If the user enters an invalid value, you may want to provide some feedback about the error on the application UI. One way to provide such feedback is to set the Validation..::.ErrorTemplate attached property to a custom ControlTemplate. As shown in the previous subsection, the StartDateEntryForm TextBox uses an ErrorTemplate called validationTemplate. The following example shows the definition of validationTemplate:

<ControlTemplate x:Key="validationTemplate">
  <DockPanel>
    <TextBlock Foreground="Red" FontSize="20">!</TextBlock>
    <AdornedElementPlaceholder/>
  </DockPanel>
</ControlTemplate>

The AdornedElementPlaceholder element specifies where the control being adorned should be placed.

In addition, you may also use a ToolTip to display the error message. Both the StartDateEntryForm and the StartPriceEntryForm TextBoxes use the style textStyleTextBox, which creates a ToolTip that displays the error message. The following example shows the definition of textStyleTextBox. The attached property Validation..::.HasError is true when one or more of the bindings on the properties of the bound element are in error.

<Style x:Key="textStyleTextBox" TargetType="TextBox">
  <Setter Property="Foreground" Value="#333333" />
  <Setter Property="MaxLength" Value="40" />
  <Setter Property="Width" Value="392" />
  <Style.Triggers>
    <Trigger Property="Validation.HasError" Value="true">
      <Setter Property="ToolTip"
        Value="{Binding RelativeSource={RelativeSource Self},
                        Path=(Validation.Errors)[0].ErrorContent}"/>
    </Trigger>
  </Style.Triggers>
</Style>

With the custom ErrorTemplate and the ToolTip, the StartDateEntryForm TextBox looks like the following when there is a validation error:

If your Binding has associated validation rules but you do not specify an ErrorTemplate on the bound control, a default ErrorTemplate will be used to notify users when there is a validation error. The default ErrorTemplate is a control template that defines a red border in the adorner layer. With the default ErrorTemplate and the ToolTip, the UI of the StartPriceEntryForm TextBox looks like the following when there is a validation error:

For an example of how to provide logic to validate all controls in a dialog box, see the Custom Dialog Boxes section in the Dialog Boxes Overview.

Validation usually occurs when the value of a target is transferred to the binding source property. This occurs on TwoWay and OneWayToSource bindings. To reiterate, what causes a source update depends on the value of the UpdateSourceTrigger property, as described in the What Triggers Source Updates section.

The following describes the validation process. Note that if a validation error or other type of error occurs at any time during this process, the process is halted.

1. The binding engine checks if there are any custom ValidationRule objects defined whose ValidationStep is set to RawProposedValue for that Binding, in which case it calls the Validate method on each ValidationRule until one of them runs into an error or until all of them pass.

2. The binding engine then calls the converter, if one exists.

3. If the converter succeeds, the binding engine checks if there are any custom ValidationRule objects defined whose ValidationStep is set to ConvertedProposedValue for that Binding, in which case it calls the Validate method on each ValidationRule that has ValidationStep set to ConvertedProposedValue until one of them runs into an error or until all of them pass.

4. The binding engine sets the source property.

5. The binding engine checks if there are any custom ValidationRule objects defined whose ValidationStep is set to UpdatedValue for that Binding, in which case it calls the Validate method on each ValidationRule that has ValidationStep set to UpdatedValue until one of them runs into an error or until all of them pass. If a DataErrorValidationRule is associated with a binding and its ValidationStep is set to the default, UpdatedValue, the DataErrorValidationRule is checked at this point. This is also the point when bindings that have the ValidatesOnDataErrors set to true are checked.

6. The binding engine checks if there are any custom ValidationRule objects defined whose ValidationStep is set to CommittedValue for that Binding, in which case it calls the Validate method on each ValidationRule that has ValidationStep set to CommittedValue until one of them runs into an error or until all of them pass.

If a ValidationRule does not pass at any time throughout this process, the binding engine creates a ValidationError object and adds it to the Validation..::.Errors collection of the bound element. Before the binding engine runs the ValidationRule objects at any given step, it removes any ValidationError that was added to the Validation..::.Errors attached property of the bound element during that step. For example, if a ValidationRule whose ValidationStep is set to UpdatedValue failed, the next time the validation process occurs, the binding engine removes that ValidationError immediately before it calls any ValidationRule that has ValidationStep set to UpdatedValue.

When Validation..::.Errors is not empty, the Validation..::.HasError attached property of the element is set to true. Also, if the NotifyOnValidationError property of the Binding is set to true, then the binding engine raises the Validation..::.Error attached event on the element.

Also note that a valid value transfer in either direction (target to source or source to target) clears the Validation..::.Errors attached property.

If the binding either has an ExceptionValidationRule associated with it, or had the ValidatesOnExceptions property is set to true and an exception is thrown when the binding engine sets the source, the binding engine checks to see if there is a UpdateSourceExceptionFilter. You have the option to use the UpdateSourceExceptionFilter callback to provide a custom handler for handling exceptions. If an UpdateSourceExceptionFilter is not specified on the Binding, the binding engine creates a ValidationError with the exception and adds it to the Validation..::.Errors collection of the bound element.

Come accennato in precedenza e come si evince dalla freccia nella figura precedente, il flusso di dati di un'associazione può andare dalla destinazione dell'associazione all'origine dell'associazione (ad esempio, il valore di origine viene modificato quando un utente modifica il valore di un oggetto TextBox) e/o dall'origine dell'associazione alla destinazione dell'associazione (ad esempio, il contenuto di TextBox viene aggiornato in seguito alle modifiche apportate nell'origine dell'associazione) se l'origine dell'associazione fornisce le notifiche appropriate.

È possibile fare in modo che l'applicazione consenta agli utenti di modificare i dati e propagarli all'oggetto origine. Oppure è possibile fare in modo che gli utenti non aggiornino i dati di origine. A tal proposito occorre impostare la proprietà Mode dell'oggetto Binding. Nella figura che segue vengono illustrati i diversi tipi di flusso di dati:

• L'associazione OneWay fa sì che le modifiche apportate alla proprietà di origine comportino un aggiornamento automatico della proprietà di destinazione. Tuttavia, le modifiche apportate alla proprietà di destinazione non vengono propagate alla proprietà di origine. Questo tipo di associazione è adatto nel caso in cui il controllo associato sia implicitamente di sola lettura. Può accadere ad esempio che si effettui un'associazione a un'origine quale un controllo Stock Ticker oppure che la proprietà di destinazione non possieda un'interfaccia di controllo tramite la quale apportare modifiche, come nel caso di un colore di sfondo con associazione a dati di una tabella. Se non vi è alcuna necessità di controllare le modifiche della proprietà di destinazione, è consigliabile utilizzare la modalità di associazione OneWay, in quanto l'associazione TwoWay implicherebbe operazioni inutili.

• L'associazione TwoWay fa sì che le modifiche apportate alla proprietà di origine o alla proprietà di destinazione comportino un aggiornamento automatico dell'altra proprietà. Questo tipo di associazione è adatto ai moduli modificabili o ad altri scenari di UI completamente interattiva. La maggior parte delle proprietà utilizza per impostazione predefinita l'associazione OneWay. Tuttavia, alcune proprietà di dipendenza, in genere proprietà di controlli modificabili dall'utente quali ad esempio la proprietà Text di TextBox e la proprietà IsChecked di CheckBox, utilizzano per impostazione predefinita l'associazione TwoWay. Per stabilire a livello di codice se, per impostazione predefinita, una proprietà di dipendenza utilizza l'associazione unidirezionale o bidirezionale, è possibile ottenere i metadati della proprietà utilizzando GetMetadata, quindi controllare il valore booleano della proprietà BindsTwoWayByDefault.

• OneWayToSource è la modalità di associazione inversa rispetto a OneWay. Con questa modalità, la proprietà di origine viene aggiornata in seguito a una modifica della proprietà di destinazione. Può essere utilizzata, ad esempio, nel caso in cui si debba semplicemente rivalutare il valore di origine dall'UI.

• Un altro tipo di associazione non illustrato nella figura è l'associazione OneTime, la quale fa sì che la proprietà di origine inizializzi la proprietà di destinazione ma non prevede la propagazione delle successive modifiche. Ciò significa che se il contesto dati subisce una modifica o l'oggetto nel contesto dati viene modificato, la modifica non si riflette nella proprietà di destinazione. Questo tipo di associazione è adatto nel caso in cui i dati utilizzati siano effettivamente statici oppure richiedano l'utilizzo di uno snapshot dello stato corrente. È utile anche nel caso in cui si desideri inizializzare la proprietà di destinazione con un valore derivante da una proprietà di origine senza conoscere in anticipo il contesto dati. Si tratta essenzialmente di una forma più semplice di associazione OneWay, in grado di garantire prestazioni migliori nei casi in cui il valore di origine non viene modificato.

Per rilevare le modifiche apportate all'origine, nel caso delle associazioni OneWay e TwoWay, l'origine deve implementare un meccanismo appropriato di notifica delle modifiche alle proprietà, quale ad esempio INotifyPropertyChanged. Per un esempio di implementazione di INotifyPropertyChanged, vedere Procedura: implementare notifiche di modifiche alle proprietà.

La pagina delle proprietà Mode fornisce ulteriori informazioni sulle modalità di associazione e un esempio in cui viene illustrato come specificare la direzione di un'associazione.

Le associazioni di tipo TwoWay o OneWayToSource attendono le modifiche apportate alla proprietà di destinazione e le propagano all'origine. Questo processo è noto come aggiornamento dell'origine. Può accadere ad esempio che si modifichi il testo di un oggetto TextBox per modificare il valore di origine sottostante. Come descritto nella sezione precedente, la direzione del flusso di dati è determinata dal valore della proprietà Mode dell'associazione.

Ma il valore di origine viene aggiornato durante la modifica del testo o una volta terminata la modifica, quando si sposta il puntatore del mouse da TextBox? La proprietà UpdateSourceTrigger dell'associazione determina l'evento che genera l'aggiornamento dell'origine. Nella figura che segue, i puntini delle frecce rivolte verso destra illustrano il ruolo della proprietà UpdateSourceTrigger:

Se il valore di UpdateSourceTrigger è PropertyChanged, il valore indicato dalla freccia a destra dell'associazione TwoWay o OneWayToSource viene aggiornato non appena si modifica la proprietà di destinazione. Se invece il valore di UpdateSourceTrigger è LostFocus, il valore indicato dalla freccia viene aggiornato con il nuovo valore soltanto quando la proprietà di destinazione perde lo stato attivo.

Analogamente alla proprietà Mode, diverse proprietà di dipendenza possiedono valori di UpdateSourceTrigger predefiniti diversi. Il valore predefinito per la maggior parte delle proprietà di dipendenza è PropertyChanged, mentre il valore predefinito per la proprietà Text è LostFocus. Ciò significa che gli aggiornamenti dell'origine avvengono in genere quando si modifica la proprietà di destinazione. Questo comportamento è appropriato nel caso di oggetti CheckBox e di altri controlli semplici. Nel caso dei campi di testo, tuttavia, l'esecuzione di un aggiornamento a ogni pressione di tasto può comportare un calo di prestazioni nonché negare all'utente la possibilità di tornare indietro e correggere eventuali errori di digitazione prima di confermare il nuovo valore. Per questo motivo il valore predefinito della proprietà Text è LostFocus anziché PropertyChanged.

Vedere la pagina delle proprietà UpdateSourceTrigger per informazioni su come individuare il valore di UpdateSourceTrigger predefinito di una proprietà di dipendenza.

Nella tabella che segue viene fornito uno scenario esemplificativo per ogni valore di UpdateSourceTrigger utilizzando TextBox come esempio:

Per un esempio, vedere Procedura: controllare il momento in cui il database di origine viene aggiornato dal testo di TextBox.

Nell'esempio precedente, l'origine dell'associazione viene specificata impostando la proprietà DataContext nell'elemento DockPanel. Button eredita quindi il valore di DataContext da DockPanel, il quale costituisce l'elemento padre. Come già detto, l'oggetto origine dell'associazione è uno dei quattro componenti necessari di un'associazione. Di conseguenza, se non si specifica l'oggetto origine dell'associazione, questa non viene creata.

Esistono diversi modi per specificare l'oggetto origine dell'associazione. L'utilizzo della proprietà DataContext in un elemento padre è utile in caso di associazione di più proprietà alla stessa origine. In alcuni casi, tuttavia, è preferibile specificare l'origine dell'associazione in singole dichiarazioni di associazione. Nel caso dell'esempio precedente, anziché utilizzare la proprietà DataContext, è possibile specificare l'origine dell'associazione impostando la proprietà Source direttamente nella dichiarazione di associazione del pulsante, come avviene nell'esempio che segue:

<DockPanel.Resources>
  <c:MyData x:Key="myDataSource"/>
</DockPanel.Resources>
<Button Width="150" Height="30"
        Background="{Binding Source={StaticResource myDataSource},
                             Path=ColorName}">I am bound to be RED!</Button>

Oltre a impostare la proprietà DataContext direttamente in un elemento, ereditare il valore di DataContext da un predecessore (si veda il pulsante nel primo esempio) e specificare in modo esplicito l'origine dell'associazione impostando la proprietà Source in Binding (si veda il pulsante nell'ultimo esempio), è anche possibile utilizzare la proprietà ElementName o la proprietà RelativeSource per specificare l'origine dell'associazione. La proprietà ElementName è utile in caso di associazione ad altri elementi nell'applicazione, ad esempio in caso di utilizzo di un dispositivo di scorrimento per regolare la larghezza di un pulsante. La proprietà RelativeSource è utile nel caso di un'associazione specificata in un oggetto ControlTemplate o Style. Per ulteriori informazioni, vedere Procedura: specificare l'origine di associazione.

Se l'origine dell'associazione è un oggetto, si utilizza la proprietà Path per specificare il valore da utilizzare per l'associazione. In caso di associazione a dati XML, utilizzare la proprietà XPath per specificare il valore. In alcuni casi è possibile utilizzare la proprietà Path anche se i dati sono in formato XML. Ad esempio, per accedere alla proprietà Name di un XmlNode restituito in seguito a una query XPath, è necessario utilizzare la proprietà Path oltre alla proprietà XPath.

Per informazioni sulla sintassi e alcuni esempi, vedere le pagine delle proprietà Path e XPath.

Benché sia stato sottolineato che la proprietà Path del valore da utilizzare è uno dei quattro componenti necessari di un'associazione, negli scenari di associazione a un intero oggetto il valore da utilizzare corrisponde all'oggetto origine dell'associazione. In tali casi è possibile non specificare Path. Si consideri l'esempio seguente:

<ListBox ItemsSource="{Binding}"
         IsSynchronizedWithCurrentItem="true"/>

Nell'esempio viene utilizzata la sintassi di associazione vuota: {Binding}. In questo caso, ListBox eredita DataContext da un elemento DockPanel padre, assente nell'esempio. Quando il percorso non viene specificato, per impostazione predefinita si esegue un'associazione all'intero oggetto. In altre parole, in questo esempio il percorso è stato tralasciato poiché la proprietà ItemsSource viene associata all'intero oggetto. Per informazioni più dettagliate, vedere la sezione Associazione agli insiemi.

Diversamente dall'associazione a un insieme, questo scenario è utile anche in caso di associazione a un intero oggetto anziché a un'unica proprietà di un oggetto. Si consideri ad esempio un oggetto origine di tipo stringa con un'associazione alla stringa stessa. Un altro scenario comune riguarda l'associazione di un elemento a un oggetto con diverse proprietà.

Alcuni scenari richiedono l'applicazione di una logica personalizzata affinché i dati siano significativi per la proprietà di destinazione associata. Tale logica potrebbe essere un convertitore personalizzato, in assenza della conversione di tipi predefinita. Per informazioni sui convertitori, vedere Conversione dei dati.

Prima di analizzare altre funzionalità e modalità di utilizzo dell'associazione dati, è opportuno introdurre la classe BindingExpression. Come si è visto nelle sezioni precedenti, la classe Binding è la classe di alto livello per la dichiarazione di un'associazione e fornisce diverse proprietà che consentono di specificare le caratteristiche dell'associazione. Una classe correlata, BindingExpression, è l'oggetto sottostante che gestisce la connessione tra origine e destinazione. Un'associazione contiene tutte le informazioni condivisibili tra diverse espressioni di associazione. BindingExpression è un'espressione di istanza non condivisibile e contiene tutte le informazioni sull'istanza di Binding.

Si consideri l'esempio che segue, nel quale myDataObject è un'istanza della classe MyData, myBinding è l'oggetto Binding di origine e la classe MyData è una classe definita contenente una proprietà stringa denominata MyDataProperty. Nell'esempio viene associato il contenuto di testo di mytext, un'istanza di TextBlock, a MyDataProperty.

Dim data1 As New MyData(DateTime.Now)
Dim binding1 As New Binding("MyDataProperty")
binding1.Source = data1
Me.myText.SetBinding(TextBlock.TextProperty, binding1)

//make a new source
  MyData myDataObject = new MyData(DateTime.Now);      
  Binding myBinding = new Binding("MyDataProperty");
  myBinding.Source = myDataObject;
  myText.SetBinding(TextBlock.TextProperty, myBinding);

È possibile utilizzare lo stesso oggetto myBinding per creare altre associazioni. Ad esempio, è possibile utilizzare l'oggetto myBinding per associare il contenuto di testo di una casella di controllo a MyDataProperty. In un simile scenario si avranno due istanze di BindingExpression che condividono l'oggetto myBinding.

Un oggetto BindingExpression può essere ottenuto tramite il valore restituito di una chiamata a GetBindingExpression in un oggetto con associazione a dati. Negli argomenti che seguono vengono illustrate alcune modalità di utilizzo della classe BindingExpression:

• Procedura: ottenere l'oggetto di associazione da una proprietà di destinazione associata

• Procedura: controllare il momento in cui il database di origine viene aggiornato dal testo di TextBox

È possibile eseguire enumerazioni in qualsiasi insieme che implementa l'interfaccia IEnumerable. Tuttavia, per impostare associazioni dinamiche in modo tale che l'UI venga automaticamente aggiornata in seguito a operazioni di inserimento o eliminazione nell'insieme, è necessario che questo implementi l'interfaccia INotifyCollectionChanged. Questa interfaccia espone un evento che deve essere generato a ogni modifica dell'insieme sottostante.

In WPF viene fornita la classe ObservableCollection<(Of <(T>)>), un'implementazione incorporata di un insieme di dati che espone l'interfaccia INotifyCollectionChanged. Per supportare pienamente il trasferimento dei valori dei dati dagli oggetti origine alle destinazioni, ogni oggetto nell'insieme che supporta proprietà associabili deve implementare anche l'interfaccia INotifyPropertyChanged. Per ulteriori informazioni, vedere Cenni preliminari sulle origini di associazione.

Prima di implementare un insieme personalizzato, considerare la possibilità di utilizzare ObservableCollection<(Of <(T>)>) o una delle classi di insiemi esistenti, ad esempio List<(Of <(T>)>), Collection<(Of <(T>)>) e BindingList<(Of <(T>)>). Se si desidera implementare un insieme personalizzato in uno scenario avanzato, è opportuno utilizzare IList, il quale fornisce un insieme non generico di oggetti accessibili singolarmente tramite indice e garantisce prestazioni ottimali.

Una volta associato ItemsControl a un insieme di dati, è possibile ordinare, filtrare o raggruppare tali dati. A tale scopo si utilizzano le visualizzazioni di insiemi, ovvero classi che implementano l'interfaccia ICollectionView.

Nella presente sezione sono contenute le seguenti sottosezioni.

• Definizione di visualizzazione di insieme
• Procedura per la creazione di una visualizzazione
• Ordinamento
• Filtraggio
• Raggruppamento
• Puntatori dell'elemento corrente
• Scenario di associazione Master-Details

Definizione di visualizzazione di insieme

Procedura per la creazione di una visualizzazione

<Window.Resources>


...


<CollectionViewSource 
      Source="{Binding Source={x:Static Application.Current}, Path=AuctionItems}"   
      x:Key="listingDataView" />


...


</Window.Resources>

<ListBox Name="Master" Grid.Row="2" Grid.ColumnSpan="3" Margin="8"
    ItemsSource="{Binding Source={StaticResource listingDataView}}">


...


</ListBox>

Ordinamento

private void AddSorting(object sender, RoutedEventArgs args)
{
    // This sorts the items first by Category and within each Category,
    // by StartDate. Notice that because Category is an enumeration,
    // the order of the items is the same as in the enumeration declaration
    listingDataView.SortDescriptions.Add(
        new SortDescription("Category", ListSortDirection.Ascending));
    listingDataView.SortDescriptions.Add(
        new SortDescription("StartDate", ListSortDirection.Ascending));
}

Filtraggio

listingDataView.Filter += new FilterEventHandler(ShowOnlyBargainsFilter);

private void ShowOnlyBargainsFilter(object sender, FilterEventArgs e)
{
    AuctionItem product = e.Item as AuctionItem;
    if (product != null)
    {
        // Filter out products with price 25 or above
        if (product.CurrentPrice < 25)
        {
            e.Accepted = true;
        }
        else
        {
            e.Accepted = false;
        }
    }
}

Raggruppamento

// This groups the items in the view by the property "Category"
PropertyGroupDescription groupDescription = new PropertyGroupDescription();
groupDescription.PropertyName = "Category";
listingDataView.GroupDescriptions.Add(groupDescription);

Puntatori dell'elemento corrente

<Button Content="{Binding }" />
<Button Content="{Binding Path=/}" />
<Button Content="{Binding Path=/Description}" /> 

<Button Content="{Binding /Offices/}" />

Scenario di associazione Master-Details

<ListBox Name="Master" Grid.Row="2" Grid.ColumnSpan="3" Margin="8"
    ItemsSource="{Binding Source={StaticResource listingDataView}}">


...


</ListBox>


...


<ContentControl Name="Detail" Grid.Row="3" Grid.ColumnSpan="3" 
        Content="{Binding Source={StaticResource listingDataView}}" 
        ContentTemplate="{StaticResource detailsProductListingTemplate}" 
        Margin="9,0,0,0"/>

Il modello di associazione dati WPF consente di associare ValidationRules all'oggetto Binding. Nell'esempio seguente viene ad esempio associato un oggetto TextBox a una proprietà denominata StartPrice e viene aggiunto un oggetto ExceptionValidationRule alla proprietà Binding..::.ValidationRules.

<TextBox Name="StartPriceEntryForm" Grid.Row="2" Grid.Column="1"
    Style="{StaticResource textStyleTextBox}" Margin="8,5,0,5">
  <TextBox.Text>
    <Binding Path="StartPrice" UpdateSourceTrigger="PropertyChanged">
      <Binding.ValidationRules>
        <ExceptionValidationRule />
      </Binding.ValidationRules>
    </Binding>
  </TextBox.Text>
</TextBox>

Un oggetto ValidationRule controlla se il valore di una proprietà è valido. In WPF sono disponibili i due tipi di oggetti ValidationRule incorporati seguenti:

• Un oggetto ExceptionValidationRule verifica la presenza di eccezioni generate durante l'aggiornamento della proprietà di origine dell'associazione. Nell'esempio precedente, StartPrice è di tipo Integer. Quando l'utente immette un valore che non può essere convertito in un intero, viene generata un'eccezione e l'associazione viene contrassegnata come non valida. Una sintassi alternativa all'impostazione esplicita dell'oggetto ExceptionValidationRule è rappresentata dall'impostazione della proprietà ValidatesOnExceptions su true per l'oggetto Binding o MultiBinding corrente.

• Un DataErrorValidationRule verifica la presenza di errori generati dagli oggetti che implementano l'interfaccia IDataErrorInfo. Per un esempio di utilizzo di questa regola di convalida, vedere DataErrorValidationRule. Una sintassi alternativa all'impostazione esplicita dell'oggetto DataErrorValidationRule è rappresentata dall'impostazione della proprietà ValidatesOnDataErrors su true per l'oggetto Binding o MultiBinding corrente.

È anche possibile creare una regola di convalida personalizzata mediante derivazione dalla classe ValidationRule e implementazione del metodo Validate. Di seguito viene illustrata la regola utilizzata dall'oggetto TextBox "Start Date" contenuto in Add Product Listing, secondo l'esempio riportato nella sezione Definizione di associazione dati:

class FutureDateRule : ValidationRule
{
    public override ValidationResult Validate(object value, CultureInfo cultureInfo)
    {
        DateTime date;
        try
        {
            date = DateTime.Parse(value.ToString());
        }
        catch (FormatException)
        {
            return new ValidationResult(false, "Value is not a valid date.");
        }
        if (DateTime.Now.Date > date)
        {
            return new ValidationResult(false, "Please enter a date in the future.");
        }
        else
        {
            return ValidationResult.ValidResult;
        }
    }
}

L'oggetto TextBox StartDateEntryForm utilizza FutureDateRule, come illustrato nell'esempio che segue:

<TextBox Name="StartDateEntryForm" Grid.Row="3" Grid.Column="1" 
    Validation.ErrorTemplate="{StaticResource validationTemplate}" 
    Style="{StaticResource textStyleTextBox}" Margin="8,5,0,5">
    <TextBox.Text>
        <Binding Path="StartDate" UpdateSourceTrigger="PropertyChanged" 
            Converter="{StaticResource dateConverter}" >
            <Binding.ValidationRules>
                <src:FutureDateRule />
            </Binding.ValidationRules>
        </Binding>
    </TextBox.Text>
</TextBox>

Poiché il valore di UpdateSourceTrigger è PropertyChanged, il motore di associazione aggiorna il valore di origine a ogni pressione di tasto, il che significa che controlla anche ogni regola nell'insieme ValidationRules a ogni pressione di tasto. L'argomento verrà ulteriormente trattato nella sezione Processo di convalida.

Se l'utente immette un valore non valido, è possibile fornire un feedback relativo all'errore nell'UI dell'applicazione. Un modo per fornire tale feedback consiste nell'impostare la proprietà associata Validation..::.ErrorTemplate su un oggetto ControlTemplate personalizzato. Come illustrato nella sottosezione precedente, l'oggetto TextBox StartDateEntryForm utilizza un oggetto ErrorTemplate definito validationTemplate. Nell'esempio seguente viene illustrata la definizione di validationTemplate:

<ControlTemplate x:Key="validationTemplate">
  <DockPanel>
    <TextBlock Foreground="Red" FontSize="20">!</TextBlock>
    <AdornedElementPlaceholder/>
  </DockPanel>
</ControlTemplate>

L'elemento AdornedElementPlaceholder specifica il punto in cui deve essere posizionato il controllo decorato.

In aggiunta, è anche possibile utilizzare un oggetto ToolTip per visualizzare il messaggio di errore. Gli oggetti TextBox StartDateEntryForm e StartPriceEntryForm utilizzano entrambi lo stile textStyleTextBox, il quale crea un oggetto ToolTip in cui viene visualizzato il messaggio di errore. Nell'esempio seguente viene illustrata la definizione di textStyleTextBox. Il valore della proprietà associata Validation..::.HasError è true quando una o più associazioni nelle proprietà dell'elemento associato sono in errore.

<Style x:Key="textStyleTextBox" TargetType="TextBox">
  <Setter Property="Foreground" Value="#333333" />
  <Setter Property="MaxLength" Value="40" />
  <Setter Property="Width" Value="392" />
  <Style.Triggers>
    <Trigger Property="Validation.HasError" Value="true">
      <Setter Property="ToolTip"
        Value="{Binding RelativeSource={RelativeSource Self},
                        Path=(Validation.Errors)[0].ErrorContent}"/>
    </Trigger>
  </Style.Triggers>
</Style>

Utilizzando ErrorTemplate personalizzato e ToolTip, in caso di errore di convalida l'oggetto TextBox StartDateEntryForm appare come segue:

Se Binding possiede regole di convalida associate ma non viene specificato alcun oggetto ErrorTemplate nel controllo associato, verrà utilizzato un oggetto ErrorTemplate predefinito per avvisare gli utenti in caso di errore di convalida. L'oggetto ErrorTemplate predefinito è un modello di controllo che definisce un bordo rosso nel livello dello strumento decorativo visuale. Utilizzando ErrorTemplate predefinito e ToolTip, in caso di errore di convalida l'UI dell'oggetto TextBox StartPriceEntryForm appare come segue:

Per un esempio di come fornire una logica di convalida per tutti i controlli in una finestra di dialogo, vedere la sezione Finestre di dialogo personalizzate contenuta in Cenni preliminari sulle finestre di dialogo.

La convalida avviene solitamente quando si trasferisce un valore di destinazione alla proprietà di origine dell'associazione. Ciò si verifica con associazioni TwoWay e OneWayToSource. Come già detto, gli eventi che generano un aggiornamento dell'origine dipendono dal valore della proprietà UpdateSourceTrigger, come descritto nella sezione Eventi che generano gli aggiornamenti dell'origine.

Gli elementi seguenti descrivono il processo di convalida. Si noti che se in un qualsiasi momento del processo si verifica un errore di convalida o di altro tipo, il processo viene interrotto.

1. Successivamente controlla se siano stati definiti oggetti ValidationRule personalizzati con ValidationStep impostato su RawProposedValue per tale oggetto Binding, nel qual caso chiama il metodo Validate su ciascun oggetto ValidationRule fino a che non viene rilevato un errore per uno di essi o finché non restituiscono tutti esito positivo.

2. Il motore di associazione chiama quindi il convertitore, se presente.

3. Se il convertitore riesce, il motore di associazione controlla se sono stati definiti oggetti ValidationRule personalizzati il cui valore di ValidationStep sia impostato su ConvertedProposedValue per Binding, nel qual caso chiama il metodo Validate su ciascun oggetto ValidationRule con ValidationStep impostato su ConvertedProposedValue fino a che non viene rilevato un errore per uno di essi o finché non restituiscono tutti esito positivo.

4. Il motore di associazione imposta la proprietà di origine.

5. Il motore di associazione controlla se sono stati definiti oggetti ValidationRule personalizzati la cui proprietà ValidationStep sia impostata su UpdatedValue per l'oggetto Binding in questione, nel qual caso chiama il metodo Validate su ciascun oggetto ValidationRule con la proprietà ValidationStep impostata su UpdatedValue fino a che non viene rilevato un errore per uno di essi o finché non restituiscono tutti esito positivo. Se un oggetto DataErrorValidationRule è associato a un'associazione e la relativa proprietà ValidationStep è impostata sul valore predefinito, vale a dire UpdatedValue, DataErrorValidationRule viene controllato a questo punto. Si tratta inoltre del momento in cui vengono controllate le associazioni la cui proprietà ValidatesOnDataErrors è impostata su true.

6. Il motore di associazione controlla se sono stati definiti oggetti ValidationRule personalizzati la cui proprietà ValidationStep sia impostata su CommittedValue per l'oggetto Binding in questione, nel qual caso chiama il metodo Validate su ciascun oggetto ValidationRule con la proprietà ValidationStep impostata su CommittedValue fino a che non viene rilevato un errore per uno di essi o finché non restituiscono tutti esito positivo.

Se in un qualsiasi momento del processo l’oggetto ValidationRule restituisce esito negativo, il motore di associazione crea un oggetto ValidationError e lo aggiunge all’insieme Validation..::.Errors dell’elemento associato. Prima che il motore di associazione venga eseguito sugli oggetti ValidationRule in un determinato passaggio, esso rimuove qualsiasi oggetto ValidationError aggiunto alla proprietà associata Validation..::.Errors dell’elemento associato durante quel passaggio. Ad esempio, se un oggetto ValidationRule il cui ValidationStep è impostato su UpdatedValue ha avuto esito negativo, la volta successiva in cui si verifica il processo di convalida, il motore di associazione rimuove l'oggetto ValidationError immediatamente prima di chiamare ValidationRule con ValidationStep impostato su UpdatedValue.

Se la proprietà Validation..::.Errors non è vuota, la proprietà associata Validation..::.HasError dell'elemento viene impostata su true. Se, inoltre, la proprietà NotifyOnValidationError dell'oggetto Binding è impostata su true, il motore di associazione genera l'evento associato Validation..::.Error sull'elemento.

Il trasferimento di un valore valido in una delle due direzioni (dalla destinazione all'origine o viceversa) comporta la cancellazione della proprietà associata Validation..::.Errors.

Se all’associazione è associato un oggetto ExceptionValidationRule o se la proprietà ValidatesOnExceptions è impostata su true e viene generata un’eccezione quando il motore di associazione imposta l’origine, il motore di associazione controlla se è presente un oggetto UpdateSourceExceptionFilter. È possibile utilizzare il callback UpdateSourceExceptionFilter per fornire un gestore personalizzato per la gestione delle eccezioni. Se un UpdateSourceExceptionFilter non viene specificato sull'oggetto Binding, il modulo di associazione crea un ValidationError con l'eccezione e lo aggiunge all'insieme Validation..::.Errors dell'elemento associato.