As shown in the previous chapter, you can open the Data Sources tool window in Visual Studio 2010, and drag an entity that is exposed from a domain service from this window onto your design surface. A DataGrid will be created in the view, with a column defined for each property on the entity.

Instead of creating a DataGrid, you can select Details from the drop-down menu when you select the entity in the Data Sources window (as shown in Figure 7-1) before dragging it onto the design surface.

Figure 7.1. Selecting what control will be generated for an entity

Now when you drag the entity onto the design surface, a field and corresponding label will be created for each property on the entity, laid out using a Grid control (as shown in Figure 7-2), with the field's binding to the source property already configured.

Figure 7.2. Details form generated by the Data Sources window

The control created for each property will default to the one best suited to the property's type (i.e., TextBox for strings, CheckBox for Booleans, DatePicker for dates, etc.), but you can change these as required by expanding the entity in the Data Sources window and selecting different control types for the properties that you want to change (as shown in Figure 7-3). The labels will contain the name of the property, but with some spaces intelligently inserted into the name, and a colon appended.

Figure 7.3. Selecting the control that will be generated for a property on the entity

A DomainDataSource control will be automatically configured for you (if one doesn't already exist in the view), and the DataContext property of the Grid control that is created will be bound to it (and will be inherited and available to all the controls within the Grid).

This is an easy way of creating the fields required for a data entry form (you will generally need to rearrange them to form a logical layout); however, it's not the only (or best) way, as you'll soon find.

Another method you can use to create a data entry form is to use the XAML Power Toys add-in for Visual Studio 2010, created by Karl Shifflet. After you download and install this add-in (from http://karlshifflett.wordpress.com/xaml-power-toys), it will add a new submenu to your right-click context menus in the XAML and code editors (as shown in Figure 7-4).

Figure 7.4. The XAML Power Toys menu

Right-click in the XAML editor, and select the Create Form, ListView, or DataGrid From Selected Class menu item from the XAML Power Toys submenu.

From the dialog that appears, select the object that you want to create the data entry form from (i.e., the object that the form will bind to), and click the Next button. The screen shown in Figure 7-5 will be displayed.

Figure 7.5. The XAML Power Toys add-in's Create Business Form For Class dialog

Start by ensuring that the Select Object To Create drop-down box at the top left of the dialog is set to Business Form. Now you can drag and drop properties that you want to create as fields in the form from the Class Properties section on the left side of the screen into the right side. You can then set any of the given properties for that field as required, including

Note how the tool splits the property name into separate words for the label by inserting a space before each capital letter in the property name, which (assuming the text to be displayed is similar to the property name) should save you time in renaming many of the labels. You can also reorder the fields if required by simply clicking and dragging the item up and down to a new position in the list.

There are numerous other features that I won't go into here, but essentially this method enables you to have a lot more control over the configuration of the data entry form before creating it than the previous method described.

Once you've completed configuring your form, you can click the Create button. However, this won't actually insert anything into your XAML as yet. The XAML that was generated has been copied to the clipboard and is ready for you to paste in the appropriate location in your XAML file. Place the cursor at the position in the XAML file to insert the form, and paste the contents of the clipboard to that location (press Ctrl+V). Your data entry form has now been created, and you can modify the XAML further as required. Note that you may have to declare various namespace prefixes used in the generated XAML—these are included when you paste the XAML into the XAML editor in commented-out form. You can then add them to your root element if they aren't already declared.

You can also configure other default property values to apply to each control in the form by selecting the XAML Power Toys

In addition to the previous two methods shown, there is another (and arguably better) method to create a data entry form, and that's using the DataForm control.

Creating a DataForm Control with Automatically Generated Fields

The DataForm control is a part of the Silverlight Toolkit, and provides a couple of different ways to create data entry forms. The first method is simply to let it do all the work in creating the data entry form for you at runtime. All you need to do is to drop a DataForm control onto the design surface, and bind the object for the user to edit to its CurrentItem property (or a collection of objects to its ItemsSource property if you want the user to be able to edit multiple objects). For example, the XAML to create a DataForm and bind it to a DomainDataSource control (which retrieves the collection to be modified from the server) is

<riaControls:DomainDataSource AutoLoad="True" QueryName="GetProducts"
                              LoadedData="productDomainDataSource_LoadedData"
                              Name="productDomainDataSource" Height="0" Width="0">
    <riaControls:DomainDataSource.DomainContext>
        <my:ProductContext />
    </riaControls:DomainDataSource.DomainContext>
</riaControls:DomainDataSource>

<toolkit:DataForm Header="Product Data Entry"
        ItemsSource="{Binding ElementName=productDomainDataSource, Path=Data}" />

The drag-and-drop approach will declare the toolkit namespace prefix for you if it hasn't already been defined:

xmlns:toolkit="http://schemas.microsoft.com/winfx/2006/xaml/presentation/toolkit"

This will generate a data entry form similar to that shown in Figure 7-6.

Figure 7.6. A DataForm control

Note

This data entry form is generated at runtime, so none of these fields will appear at design time unless you bind it to sample data (as discussed in Chapter 10).

Note that the fields are created in alphabetical order (of bound property name) rather than the required logical order, using the property names as their labels. In addition, a field will be created for all the properties on the object, and these fields won't necessarily generate the control that you want to be used for editing the property value.

This automatically generated form doesn't create a particularly satisfactory user experience in its current form, but there is a way you can have more control over the process and customize it to your needs.

In Chapter 5, you learned how to decorate the properties of your entities/objects with attributes—either directly or via metadata classes. You can use the Display attribute that was described to control the generation of the corresponding fields in the DataForm control. For example:

[Display(Name="Product Number:", Order=3)]
public string ProductNumber;

When the corresponding field for the ProductNumber property is generated in the data entry form, its label will have the text that is assigned to the Name property of the Display attribute, and will appear third in the list of fields, based on the value assigned to the Order property. Other useful properties of the Display attribute that you can use to control the field generation include AutoGenerateField (which can be used to stop a field from being generated for the property) and Description (which can be used to assign a tooltip description to the field, as will be described shortly). In scenarios where your application will be localized for different languages, instead of hard-coding these strings you can use the ResourceType property of the Display attribute and assign it the type created for the resources file (.resx) where the resources can be found. Then assign the name of the string resources to use to their corresponding properties, like so:

[Display(ResourceType = typeof(ProductResources), Name="ProductNumberLabel",
         Description="ProductNumberDescription")]
public string ProductNumber;

Note

You will need to add a link in your Silverlight project to the resource file in your web project so the resources can be used on the client side. If you are using the RIA Services class libraries for your middle tier, then the resource file should be linked between the server and client-side class library projects instead.

Now when the fields are generated at runtime in the DataForm, they will use this metadata and be laid out accordingly. However, there are some issues with generating the data entry form in this manner. The first is the still-limited control you have over how the data entry form is generated. For simple forms, this won't be too much of a problem; however, for more complex forms where you need to use other controls such as ComboBoxes, assign custom properties to each field control, or have less of a structured layout (e.g., with multiple fields in a single row), then this method really isn't satisfactory. Some of these issues can be worked around by handling the DataForm control's AutoGeneratingField event (which is raised when each field is being created, enabling you to make changes to the field being generated).

The most important issue, however, is really conceptual. Decorating your entities/objects with presentation-related attributes violates the separation-of-concerns principle. How the data entry form is laid out is a presentation tier/layer issue, not a middle tier/layer issue (where the entities/objects exist). By decorating your entities/objects with presentation-related attributes, you are creating a murky boundary between the two tiers/layers, which is against good design principles. Therefore, it's highly recommended that you avoid using this method when creating your data entry forms, and explicitly lay out the data entry form using the method described next instead.

Note

If you are binding the DataForm control to a ViewModel (a concept from the MVVM design pattern, which will be discussed in Chapter 12) and decorate its properties with the Display attribute instead, then the use of the Display attribute is more acceptable (with a ViewModel being a presentation-related object). However, even in this case it's recommended that you explicitly lay out the data entry form using the method that will now be described.

Configuring the Labels

As mentioned, the XAML for the fields in a DataForm control needs to conform to the DataForm's requirements, so let's take a look at how it is structured. We'll take a look at a very simple example of the XAML required to configure two fields in the EditTemplate of a DataForm control:

<toolkit:DataForm AutoGenerateFields="False" Header="Product Data Entry">
    <toolkit:DataForm.EditTemplate>
        <DataTemplate>
            <Grid>
                <Grid.RowDefinitions>
                    <RowDefinition Height="Auto" />
                    <RowDefinition Height="Auto" />
                </Grid.RowDefinitions>
                <Grid.ColumnDefinitions>
                    <ColumnDefinition />
                </Grid.ColumnDefinitions>

                <toolkit:DataField Grid.Row="0" Grid.Column="0"
                                   Label="Name:" LabelPosition="Auto">
                    <TextBox Text="{Binding Path=Name, Mode=TwoWay}"

Name="NameTextBox"
                            HorizontalAlignment="Stretch" VerticalAlignment="Top" />
                </toolkit:DataField>

                <toolkit:DataField Grid.Row="1" Grid.Column="0"
                                           Label="Product Number:"
                                           LabelPosition="Auto">
                    <TextBox Text="{Binding Path=ProductNumber, Mode=TwoWay}"
                            HorizontalAlignment="Stretch" VerticalAlignment="Top" />
                </toolkit:DataField>
            </Grid>
        </DataTemplate>
    </toolkit:DataForm.EditTemplate>
</toolkit:DataForm>

Note the following from this XAML:

• The fields are laid out in a Grid, but there is only a single column defined in the Grid (yet the DataForm control ensures that they will remain aligned regardless of the differing lengths of the labels).

• There is no Label or TextBlock control defined for each field to display the field label. Instead, each field is defined using a DataField control, to which you assign the input control as its content. The DataField control is then assigned to a cell in the Grid, and the text to use as its label is assigned to its Label property. If you wish, you can assign a string to the DataField control's Description property to display an icon next to the field that shows the string when the user hovers their mouse over it.

When the DataForm control in the preceding XAML is bound to an entity or collection of entities, the output shown in Figure 7-7 will be produced.

Figure 7.7. A DataForm control with a custom edit template

Note that the labels for the fields in Figure 7-7 are bold, indicating to the user that these fields require a value. This is because the bound properties are decorated with the Required validation attribute.

Although labels are by default positioned to the left of the fields, you can also position them above the fields by setting the DataForm control's LabelPosition property to Top. Top-aligned labels require less horizontal space, and some research has suggested that they enable users to complete forms faster because they can see both the label and the field together as they scan the form. In addition, you don't have to worry so much about how much room the label requires when a form is to be localized. Figure 7-8 demonstrates top-aligned labels.

Figure 7.8. A DataForm control with top-aligned labels

More information on this can be found at these two URLs:

• www.uxmatters.com/mt/archives/2006/07/label-placement-in-forms.php

• www.lukew.com/ff/entry.asp?504

ProductsDataForm.CommandButtonsVisibility = DataFormCommandButtonsVisibility.Add |
                                            DataFormCommandButtonsVisibility.Delete;

CommandButtonsVisibility="Add,Delete"

There are many data input controls available in Silverlight and the Silverlight Toolkit that you can use in your data entry forms. You can actually use any control you like in a DataForm control (including third-party controls), so you can choose the most appropriate controls for your needs. Let's take a brief look at some of the more common data input controls that you may wish to use.

The TextBox Control

The TextBox control enables users to enter free-form text (as shown in Figure 7-9).

Figure 7.9. A TextBox control

You can get/set the text in the TextBox via its Text property:

<TextBox Text="{Binding Path=Name, Mode=TwoWay}" />

Thanks to a new binding feature in Silverlight 4, you can format the bound value before displaying it. This is very useful when binding to a non-string property (such as a DateTime or a decimal). Use the StringFormat property on the binding to set the format (using the same types of formatting strings you would use if you were to format the value using its ToString method in code (using either standard or custom formats). For example, the following binding displays the value formatted as currency (as shown in Figure 7-10):

<TextBox Text="{Binding TotalCost, Mode=TwoWay, StringFormat=C}" />

Figure 7.10. A bound TextBox control with a custom string format

Note

You will find more information about the available standard formatting strings and creating custom formatting strings at the following MSDN page (and in related topics): http://msdn.microsoft.com/en-us/library/26etazsy.aspx. If you need to perform a more complex value format or conversion, then you may be better off using a value converter, as will be discussed in Chapter 10.

Unfortunately, the TextBox control doesn't have any masked edit functionality to restrict the input into the TextBox from the user. There are a number of third-party masked edit controls, as well as an open source one on CodePlex, which you can get here: http://sivlerlightinputctrl.codeplex.com (note the misspelling of Silverlight in the URL name).

Alternatively, you can assign a behavior that adds masked edit functionality to a text box. For example, you will find one (written by Jim Fisher) in the Microsoft Expression Gallery, here: http://gallery.expression.microsoft.com/en-us/CMEditMaskBehavior. How to use behaviors will be discussed in Chapter 10.

You can set the maximum number of characters accepted by the TextBox control using its MaxLength property.

If you want to stop the user from being able to enter text into the TextBox control (but still be able to select and copy the text, which can't be done when the TextBox control is disabled), you can set its IsReadOnly property to True. Doing so will change the background of the TextBox control to a light gray to indicate it cannot be edited.

You can horizontally align the text in the TextBox control using its TextAlignment property. You can left-align the text (the default), right-align it, or center it. Note that although Justify appears in IntelliSense and the Properties window as an alignment option, it will throw an exception when used.

By default, when more text is entered into the TextBox control than it can display, the text will remain on a single line and the beginning of the text will disappear off the TextBox's left edge. However, if you make your text box tall enough to display multiple lines, then you can get the text to wrap onto the next line by setting the TextBox control's TextWrapping property to Wrap (the default being NoWrap). If you want the user to be able to start new lines in the text box by pressing the Return/Enter key, then you will need to set the TextBox control's AcceptsReturn property to True.

By default, the vertical and horizontal scroll bars in the TextBox are hidden/disabled. You can enable them via the VerticalScrollBarVisibility and HorizontalScrollBarVisibility properties. Setting their value to Auto will cause the scroll bars to display only when the text exceeds the corresponding dimension of the text box, and setting them to Visible will cause them to display them regardless of whether they're required.

Note

Setting the horizontal scroll bar to visible will disable text wrapping.

The CheckBox Control

The CheckBox control enables the user to enter a True or False value (or a null value in the case of a three-state check box), as shown in Figure 7-11. You can get/set the value of the check box via its IsChecked property, and set its label using its Content property:

<CheckBox IsChecked="{Binding FinishedGoodsFlag, Mode=TwoWay}"
          Content="Is Finished Goods" />

Figure 7.11. A bound CheckBox control

You can turn it into a three-state check box by setting its IsThreeState property to True. This enables an additional state (with a value of null) for the check box, which you may use to indicate that a value has not been set. Figure 7-12 shows what the third state looks like.

Figure 7.12. The third state in a three-state check box

The RadioButton Control

Radio buttons (also known as option buttons) enable the user to select one option from a number of options, as shown in Figure 7-13.

Figure 7.13. Option buttons

Much like the CheckBox control, you can get/set the value of a radio button via its IsChecked property, and set its label using its Content property:

<RadioButton Content="Option 1" IsChecked="{Binding Option1, Mode=TwoWay}" />

To bind the radio buttons to an object/entity, you will need to have each option exposed as a separate Boolean property on the object/entity that you are binding to, and bind each radio button to the property representing its corresponding option. Alternatively, you could create a value converter (discussed in Chapter 10) that compares the value of a property with a given value, returning True if the values match and False if they don't.

All radio buttons are implicitly "linked," such that when you select one radio button, any currently selected radio button will be deselected. If you want to have multiple groups of radio buttons in you view that you don't want to interact, then you can separate them by assigning each radio button to a group via their GroupName property. You can give each group whatever name you wish, and only the radio buttons with the same group name will interact. When you group radio buttons, ensure that they are visually separated also in the view so that the user recognizes which options belong to which groups.

The ComboBox Control

The ComboBox control in Silverlight is not strictly a combo box as such, but a drop-down list (proper ComboBox controls accept text entry, where the Silverlight ComboBox does not). You can bind its ItemsSource property to a collection of objects to display (in much the same way as the List control), or declare the items in XAML using the Items property. You can then get/set the selected item using its SelectedItem property.

The following XAML demonstrates creating a ComboBox in XAML, with the items to be displayed in the list also declared in XAML. This gives the output shown in Figure 7-14.

<ComboBox>
    <ComboBox.Items>
        <ComboBoxItem Content="Option 1" />
        <ComboBoxItem Content="Option 2" />
        <ComboBoxItem Content="Option 3" />
        <ComboBoxItem Content="Option 4" />
    </ComboBox.Items>
</ComboBox>

Figure 7.14. A ComboBox control

Prior to Silverlight 4, data binding to a ComboBox control was a rather painful experience, as the control didn't have a SelectedValue, SelectedValuePath, or DisplayMemberPath property—all of which are needed when binding a property of the selected object to your entities/objects. Luckily, these properties are finally here for us to use. Say, for example, that we have a Product entity with a property named ModelID, and also a collection of Model objects, each with a ModelID and a ModelName property. What we want to do is to enable the user to select the model of the product from a drop-down list, assigning the ModelID of the selected Model to the ModelID property of the Product entity. However, in the list, we want to display the names of the models, not their IDs. For this scenario, we can bind the collection of Model objects to the ComboBox's ItemsSource property, set its SelectedValuePath to ModelID, and set its DisplayMemberPath to ModelName. The ComboBox will then be bound to our collection of Model objects, so we just need to bind its SelectedValue property to our Product's ModelID property (so that the ModelID property of the selected item in the ComboBox is assigned to the Product's ModelID property, and vice versa):

<ComboBox ItemsSource="{StaticResource modelsResource}" SelectedValuePath="ModelID"
          DisplayMemberPath="ModelName" SelectedValue="{Binding ModelID}" />

Note

As with the List control, you can customize the data template of each item by assigning a custom data template to the ComboBox's ItemTemplate property. This will allow you to show images, have multiple columns, and so on for your items.

The Date Input Controls

There are two controls for entering/selecting dates in the Silverlight SDK: the Calendar control and the DatePicker control.

The Calendar Control

The Calendar control (shown in Figure 7-15) enables the user to select a date from a calendar. You can get this selected date from the Calendar control's SelectedDate property:

<sdk:Calendar SelectedDate="{Binding StartDate, Mode=TwoWay}"/>

You can also allow the user to select a range of dates by changing the control's SelectionMode property from SingleDate to SingleRange or MultipleRange. You can then get the selected dates from the control's SelectedDates property. Alternatively, you can use the Calendar control for display purposes only by setting its SelectionMode property.

Figure 7.15. A Calendar control

You can narrow down the range of the date(s) that can be selected by assigning a start date for the range to the DisplayDateStart property, and the end date for the range to the DisplayDateEnd property. All dates outside this range will be blanked out and nonselectable. You can also use the BlackoutDates property to set additional dates that the user cannot select. Instead of being blanked out, these dates will display a gray cross over them. This feature can be used to prevent a weekend or a public holiday from being selected. To assign dates to the BlackoutDates property, you will need to add CalendarDateRange objects to the collection (with a from and to date), or bind the property to a collection of these objects in XAML.

By default, the current date is always highlighted in the calendar. You can disable this by setting the IsTodayHighlighted property to False. You can change the first day of the week using the FirstDayOfWeek property.

The month view isn't the only type of view supported by the Calendar control. Using the control's DisplayMode property, you change the mode between Month, Year, and Decade.

The DatePicker Control

The DatePicker control has a lot of features in common with the Calendar control (as shown in Figure 7-16). Clicking the button next to the text box (or pressing Ctrl+down arrow when the text box has focus) will pop up a calendar that the user can select the date from. Unlike the Calendar control, only a single date can be entered into/selected from the DatePicker control. However, you can still restrict the date entered to be within a range like the Calendar control, and black out various date ranges. It does have one additional property: the SelectedDateFormat property. Instead of using the default short date format used, you can change the date format to the long date format via that property.

<sdk:DatePicker SelectedDate="{Binding StartDate, Mode=TwoWay}" />

Figure 7.16. A DatePicker control

The Time Input Controls

In addition to the date data input controls in the Silverlight SDK, there are two controls for entering times in the Silverlight Toolkit: the TimeUpDown control and the TimePicker control.

The TimeUpDown Control

The TimeUpDown control (shown in Figure 7-17) lets the user either enter a time or select one using the up/down buttons. The control enables the user to enter a part of the time, and guesses the rest of it when the user tabs away (e.g., the user can simply enter 9, and the control will fill in 9:00 AM). The user can also select a particular part of the time (hour, minute, etc.) and use the up/down buttons to change it accordingly.

Figure 7.17. A TimeUpDown control

You can get/set the time via its Value property:

<toolkit:TimeUpDown Value="{Binding StartTime, Mode=TwoWay}" />

You can change the format of the time using the TimeUpDown control's Format property, using the standard or custom date formatting strings. For example, you could specify HH:mm:ss as the format, which uses 24-hour time and includes the seconds.

You can force the user to only enter the time via the up/down buttons by setting its IsEditable property to False. You can also stop the user from going past 11:59 p.m. or before 12:00 a.m. (and cycling through this period) by setting the IsCyclic property to False.

The TimePicker Control

The TimePicker control is similar to the TimeUpDown control, except it also has a drop-down list that the user can select a time from, as shown in Figure 7-18.

<toolkit:TimePicker Value="{Binding StartTime, Mode=TwoWay}" />

Figure 7.18. A TimePicker control

By default, the drop-down list contains an item for every half-hour, but you could change this to every quarter of an hour, for example, by setting PopupMinutesInterval to 15.

The Up/Down Controls

You've seen how the TimeUpDown and TimePicker controls have up/down buttons to enable the user to modify the time using only the mouse. There are also two other controls in the Silverlight Toolkit that implement this same feature for other data types: the NumericUpDown control (for numbers) and the DomainUpDown control (for selecting an item from a collection).

The NumericUpDown Control

The NumericUpDown control only allows the entry of numbers—attempting to enter a nonnumeric value will result in the value being reverted to its original value when the field loses the focus. You can set the number of decimal places that are displayed via the DecimalPlaces property, and how much the value will increment/decrement when using the up/down buttons with the Increment property. You can get/set the value via its Value property. The following code demonstrates creating a NumericUpDown control in XAML, and Figure 7-19 shows the result:

<toolkit:NumericUpDown DecimalPlaces="2" Increment="0.5"
                       Value="{Binding ListPrice, Mode=TwoWay}" />

Figure 7.19. A NumericUpDown control

The DomainUpDown Control

The DomainUpDown control is a bit like the ComboBox control in that it enables you to enter or select an item from a list of items (using the up/down buttons). You bind a list of items to the ItemsSource property to select from, which could be an array of strings or a collection of objects. The user is constrained to only entering values from that collection. You can choose from one of two options as to what happens if the value entered by the user does not match an item in the list via the InvalidInputAction property. The UseFallbackItem option will result in the value being reverted to the value of the FallBackItem property when the field loses the focus. If a value for the FallBackItem property has not been specified, then entering a value not in the list will result in the previous value being reinstated when the field loses the focus. Alternatively, the TextBoxCannotLoseFocus option forces the user to enter/select a valid item from the list before they can move on.

When binding the ItemsSource property to a collection of objects, you can use either the ValueMemberPath property or the ValueMemberBinding property on the DomainUpDown control to specify the property on the objects that will be displayed in the control. Generally, you will use the ValueMemberPath property, to which you simply assign the name of the property identifying that item. Alternatively, you can use the ValueMemberBinding property, to which you can assign a binding expression pointing to the property to use instead. This enables you to specify a value converter as a part of the binding if necessary. As an example, you might have a collection of objects representing US states, each with two properties: one for the name of the state, and one for its short code (e.g., NY) You can display the name of the state in the control (I'll discuss how to do this shortly), but set the ValueMemberPath property to the name of the short code property. If you do this, when the user edits the value of the field, they can enter the short code for the state, and upon tabbing away the corresponding state name will be displayed instead.

Unfortunately, unlike the ComboBox control, the DomainUpDown control has no DisplayMemberPath or SelectedValuePath property (nor does it have a SelectedValue property). When binding to a collection of objects (which aren't strings), the DomainUpDown control will simply call the ToString method on the object to get the text to display. Unless you have overridden the ToString method in your classes, you will therefore need to create a data template and assign it to the control's ItemTemplate property to customize what is displayed in the control. This also means that you can create a somewhat more complex custom layout to display in the control for each item if you wish.

The index of the currently selected item in the bound collection can be obtained via the CurrentIndex property. Much like the TimeUpDown control, this control also has IsCyclic and IsEditable properties.

The following code demonstrates creating a simple DomainUpDown control in XAML, and Figure 7-20 shows the result:

<toolkit:DomainUpDown ItemsSource="{StaticResource StatesResource}"  />

Figure 7.20. A DomainUpDown control

The AutoCompleteBox Control

The AutoCompleteBox control can be used to enable the user to start typing a value to filter a list of items (appearing below the control when they begin to type), and select an item from the filtered list to complete that field's data input (as shown in Figure 7-21). Under the covers, configuring the AutoCompleteBox control is similar to the DomainUpDown control. You bind its ItemsSource property to a collection that will used to populate the list of potential values. Usually this will be a collection of strings, but you can also bind it to a collection of objects and specify the property on these objects to be displayed using the control's ValueMemberPath/ValueMemberBinding property (in the same way as you do for the DomainUpDown control). You can also assign a data template to the AutoCompleteBox control's ItemTemplate property to customize how items appear in the list.

Figure 7.21. The AutoCompleteBox control

Note

You may wish to use this control in some instances instead of a ComboBox control to speed up data input for power users. Note, however, that this control does not restrict you from entering a value not in the bound collection.

By default, items only appear in the list that start with the entered text. However, you can alter this behavior using the Filter property. There are a number of different options, but the ones you will generally use are the StartsWith option (the default) and the Contains option. Alternatively, you could use the Custom option and create your own item or text filter, assigning it to the ItemFilter/TextFilter property accordingly. Further discussion of custom filters, however, is beyond the scope of this book.

You can have the text in the text box part of the control automatically complete with the first matching entry. Rather than having the user get partway through entering the value and then selecting an item from the list (which requires further effort), you can set the IsTextCompletionEnabled property to True to have the first matching item in the list already populate the text box (although the user can still keep typing to further refine the results). When the item within the text box is the one the user is after, they can simply press Tab to move to the next field.

The list of matches appears as soon as the user enters the first character, but if you have a very long list of items being filtered, then it may be best to increase the MinimumPrefixLength property, which specifies the number of characters that the user has to enter in order for the drop-down list to appear with the matching filtered items. Alternatively (or in addition), you could assign a value to the MinimumPopulateDelay property, which specifies a period of time (in milliseconds) to wait before populating this list.

A very simple example of using the AutoCompleteBox control in XAML is provided here:

<sdk:AutoCompleteBox ItemsSource="{StaticResource StatesResource}"  />

<sdk:Label Content="Name:" Target="{Binding ElementName=ProductNameTextBox}" />

In order for the user to navigate between the data input controls using the Tab key (and Shift+Tab to move back to the previous control) in a logical fashion, you should set the tab order for each data input control in the user interface. You do this by assigning a numeric value to each control's TabIndex property. When the user tabs away from a control, the control with the same or next highest TabIndex value will receive the focus. The values do not have to be sequential, so it is a good idea to separate TabIndex values in increments of five or ten (so that you can change the tab order of a control and insert it between two other controls without having to update the tab order of all the other controls).

You can prevent a control from getting the focus when the user is tabbing between controls by settings its IsTabStop property to False.

You can also customize the scope and behavior of tabbing using the TabNavigation property. The default value is Local, which tabs through all the data input fields, and then the controls outside the current view, the browser's address bar, and, so on, before coming back to tab through the controls again. If you change this property at the container level (such as the view/page level) to Cycle, then the focus will cycle between the controls in that container only (enabling you to restrict tab stops to only the data input controls in the data entry form). If you set this property to Once, the container and all its data input controls will only be able to be tabbed to once.

In addition to enabling the user to logically tab between the controls in your data entry form, you'll want to set the initial focus to a given data input control when a record is loaded. You will need to do this by handling the ContentLoaded event on the DataForm, as the edit template is not instated in the DataForm control until the data is bound to it. The next issue is that even though you give a data input control a name in XAML (within the DataForm control), it won't have a corresponding variable in the code-behind. This is because the control is within a data template, which can be repeated. Because this template (and its content) can be repeated, to avoid possible name collisions, each data template is created in its own namescope (a concept discussed back in Chapter 3). If you were to refer to a control within a data template in code, it wouldn't know which instance to use. Since a variable is not created for the control in the code-behind, you will need to search for it inside the data template. The DataForm control actually makes this procedure easier by providing a FindNameInContent method. Pass it the name of the control and it will return you its current instance. You can then set the focus to this control, as demonstrated here:

private void dataForm_ContentLoaded(object sender, DataFormContentLoadEventArgs e)
{
    TextBox NameTextBox = ((DataForm)sender).FindNameInContent("NameTextBox")
                                                                        as TextBox;
    NameTextBox.Focus();
}

You can obtain a reference to the control that currently has the focus by using the FocusManager object (which you can find in the System.Windows.Input namespace):

object element = FocusManager.GetFocusedElement();

It's generally a good idea to notify the user if they are navigating away from a data entry form where data has been entered or modified, but has not been saved (to prevent them from accidentally losing changes to the data). This is often referred to as checking whether the data is "dirty." If the data is dirty, you can then prompt the user to save or discard their changes.

If the data entry form has been configured to enable only a single item to be edited, and you are using the DataForm control as the container, then you should be able to check its IsItemChanged property to see if any changes have been made to the current item. However, this doesn't appear to work at the time of writing (only ever returning false). Alternatively, if your bound object was retrieved from the server via RIA Services, then you can cast the CurrentItem property of the DataForm control to a type of Entity and check its HasChanges property, like so:

bool hasChanges = ((Entity)ProductsDataForm.CurrentItem).HasChanges;

If the user can edit multiple items in the data entry form, then you will need to check whether the collection has changes. If the collection was returned from the server via RIA Services, then you can simply use the HasChanges property of the domain context instance that returned the collection to find out whether unsaved changes have been made to the collection.

How you handle adding/deleting of rows really depends on your requirements. Note that there are no AddRow or DeleteRow methods (or similar) on the DataGrid—instead, you will need to work directly with the underlying bound collection.

The simplest way to implement this behavior (although not particularly the most user-friendly) is to simply add a button to your view that adds (or inserts) a new item into the collection that the DataGrid is bound to. If you have a reference to the bound collection (or can cast the value of the DataGrid's ItemsSource property to that type), then you should be able to simply call its Add or Insert method. However, if the DataGrid control is bound to a DomainDataSource control, then you will need to cast the value of the DataGrid's ItemsSource property to a DomainDataSourceView (similar to the collection views discussed in the previous chapter). For example:

DomainDataSourceView view = productDataGrid.ItemsSource as DomainDataSourceView;
Product newProduct = new Product();
view.Add(newProduct);

// Scroll the first cell of the new row into view and start editing
productDataGrid.Focus();
productDataGrid.SelectedItem = newProduct;
productDataGrid.CurrentColumn = productDataGrid.Columns[0];
productDataGrid.ScrollIntoView(productDataGrid.SelectedItem,
                               productDataGrid.CurrentColumn);
productDataGrid.BeginEdit();

This code will add a new item to the collection, select this item in the DataGrid, scroll the item into view, and put the first cell of the item's row in edit mode.

Unfortunately, the DomainDataSourceView class doesn't have an Insert method, but if you have a reference to the bound collection that does support this method (such as an ObservableCollection) and want to insert a new row after the currently selected row, you can use the following code:

ObservableCollection<Product> collection =
    productDataGrid.ItemsSource as ObservableCollection<Product>;

int insertIndex = productDataGrid.SelectedIndex + 1;

// To counter some strange behavior by the DataGrid when the
// first row is selected, but not reported as such by the
// SelectedIndex property (right after the DataGrid is populated)
if (productDataGrid.SelectedIndex == −1 && collection.Count != 0)
    insertIndex = 1;

collection.Insert(insertIndex, new Product());

// Select and scroll the first cell of the new row into view and start editing
productDataGrid.SelectedIndex = insertIndex;
productDataGrid.CurrentColumn = productDataGrid.Columns[0];
productDataGrid.ScrollIntoView(productDataGrid.SelectedItem,
                               productDataGrid.CurrentColumn);
productDataGrid.BeginEdit();

Another way to let the user enter multiple rows in a spreadsheet-like fashion is to populate the bound collection with items, and remove the unused items from the collection before submitting the data back to the server. This is useful when you have a maximum number of rows that you will support. However, when the number of rows is undetermined, setting a fixed maximum number of rows isn't an ideal solution.

The final (and generally most user-friendly) method is to automatically maintain an empty row as the last row in the DataGrid. The user can enter data for a new item in this row, and the DataGrid should automatically add a new empty row once they do. Sadly, there is no built-in feature like this in the core Silverlight DataGrid. You could add it yourself (all the source code for the DataGrid control is available in the Silverlight Toolkit), but it's not a great idea, as you'd be tying yourself to that particular version of the DataGrid control, and wouldn't be able to (easily) take advantage of new features and bug fixes in future releases of Silverlight and the Silverlight Toolkit. You can, however, handle a number of events raised by the DataGrid control and manage this automatically. The steps are as follows:

Deleting the selected row(s) requires you to get the bound collection or collection view and enumerate through the SelectedItems property of the DataGrid, removing the corresponding item from the bound collection/collection view. This is can be somewhat of a messy process due to removing items in an enumerated collection, but the use of LINQ can simplify the code somewhat:

ObservableCollection<Product> collection =
    productDataGrid.ItemsSource as ObservableCollection<Product>;

// Convert the SelectedItems property to an array so its enumerator won't be
// affected by deleting items from the source collection
// Note that this line requires the System.Linq namespace to be declared
var removeItems = productDataGrid.SelectedItems.Cast<Product>().ToArray();

foreach (Product product in removeItems)
    collection.Remove(product);

Alternatively, you can force only one row to be selected at a time in the DataGrid by setting its SelectionMode property to Single (rather than the default value of Extended), meaning that you only need to worry about removing a single selected item. In this case, the following code would suffice:

ObservableCollection<Product> collection =
    productDataGrid.ItemsSource as ObservableCollection<Product>;

collection.Remove(productDataGrid.SelectedItem as Product);

Adding a delete button to each row is reasonably easy. Simply use a template column and define a data template for the cell containing a button:

<sdk:DataGridTemplateColumn Width="80">
    <sdk:DataGridTemplateColumn.CellTemplate>
        <DataTemplate>
            <Button Content="Delete" Click="DeleteButton_Click" />
        </DataTemplate>
    </sdk:DataGridTemplateColumn.CellTemplate>
</sdk:DataGridTemplateColumn>

Now handle the Click event of the button in code to delete the corresponding item. The bound item in the collection is assigned to the data context of the row, and this is inherited down the hierarchy to the cell and then the button. Therefore, you can get the object/entity that the row is bound to from the Button control's DataContext property, and remove it from the collection/view that the DataGrid is bound to:

private void DeleteButton_Click(object sender, RoutedEventArgs e)
{
    DomainDataSourceView view = productDataGrid.ItemsSource as DomainDataSourceView;
    view.Remove(((FrameworkElement)sender).DataContext);
}

To notify listeners of this event that a property value has been updated, you simply raise the PropertyChanged event, passing it a PropertyChangedEventArgs object that has the name of the property being updated. The following example demonstrates the code that you would use to notify the user interface that the value of a property named Name has changed:

if (PropertyChanged != null)
    PropertyChanged(this, new PropertyChangedEventArgs("Name"));

One thing that you must be aware of is that the PropertyChanged event is never raised when you use automatically implemented properties. For example, properties implemented in the following fashion:

public string Name { get; set; }

do not raise the PropertyChanged event on the object, even when that object implements the INotifyPropertyChanged interface. Therefore, the user interface will not be aware of any changes to the value of that property (that it did not make itself), and will not be updated when the underlying property value is changed. This unfortunately means that you must implement the getter and setter for the property, and maintain the property's value in a member variable. You can then raise the PropertyChanged event in the setter as required:

private string name = "";

public string Name
{
    get { return name; }
    set
    {
        name = value;

        if (PropertyChanged != null)
            PropertyChanged(this, new PropertyChangedEventArgs("Name"));
    }
}

The INotifyPropertyChanged interface is very commonly used, and many developers add an OnPropertyChanged (or similarly named) method that raises the PropertyChanged event (rather than actually raising the event in the property setters). This simplifies the property setters, as you do not have to check that the PropertyChanged event is not null (which it will be if nothing is handling the event) before calling it.

protected void OnPropertyChanged(string propertyName)
{
    if (PropertyChanged != null)
        PropertyChanged(this, new PropertyChangedEventArgs(propertyName));
}

In the property setter now, you can simply use a single line of code to raise the event:

OnPropertyChanged("Name");

This makes your property setters somewhat neater, although there is still the unfortunate requirement to pass the method the name of the property as a string. This is very open to issues in which the property name is different from the string. For example, the string may misspell the property name, or the property name may have been refactored but the string was not updated accordingly. These issues can lead to particularly difficult bugs to identify and track down. Let's look at some other alternatives that can avoid this issue. Which you should choose really comes down to personal taste.

You can use reflection to get the name of the property in its setter (ignoring the first four characters, set_) and pass that to the OnPropertyChanged method:

OnPropertyChanged(MethodBase.GetCurrentMethod().Name.Substring(4));

Alternatively, you may wish to continue with hard-coding the property name as a string, and check in your OnPropertyChanged method that the property exists. The best idea is to perform this check in a separate method (and call that method from the OnPropertyChanged method), as you can then decorate it with the Conditional attribute, and only have it run when in debug mode:

[Conditional("DEBUG")]
private void EnsurePropertyExists(string propertyName)
{
    PropertyInfo propInfo = this.GetType().GetProperty(propertyName);
    Debug.Assert(propInfo != null, "The property " + propertyName + " does not " +
                                   "exist on this class");
}

Yet another method is to use a lambda expression to specify the property name (instead of a string), and extract the name of the property from that. This is a popular method, is faster than reflection, and is refactoring-safe (no magic strings). Start by adding the following using directive to the top of your class:

using System.Linq.Expressions;

Now define the following method in your class (or a base class):

private string GetPropertyName<T>(Expression<Func<T>> property)
{
    MemberExpression expression = property.Body as MemberExpression;
    return expression.Member.Name;
}

You can then call the OnPropertyChanged method from your property's setter using the following code:

OnPropertyChanged(GetPropertyName(() => Name));

where Name is the name of the property. Emiel Jongerius has written up some other alternatives (including another way of implementing this method that also sets the property's value), and how they compare (performance-wise) here: www.pochet.net/blog/2010/06/25/inotifypropertychanged-implementations-an-overview. Einar Ingebrigtsen also has a blog post with an extended version of this code that provides additional functionality, here: www.ingebrigtsen.info/post/2008/12/11/INotifyPropertyChanged-revisited.aspx.

In the BeginEdit method you will need to write code to capture the state of the object at that time (i.e., generally all the property values). The easiest way to implement this is using the MemberwiseClone method on the object to take a shallow copy of the state of the object:

private Product originalState = null; // Member variable
public void BeginEdit()
{
    originalState = this.MemberwiseClone() as Product;
}

You can then discard this state in the EndEdit method, because any changes made to the object since the BeginEdit method was called will have been accepted (i.e., committed):

public void EndEdit()
{
    originalState = null;
}

In the CancelEdit method, you need to restore the original state of the object as it was taken when the BeginEdit method was called, copying that state back to the current instance of the object. You can implement this method in one of two ways—either by manually assigning the values from the "backup" object or by using reflection.

public void CancelEdit()
{
    if (originalState != null)
    {
        Name = originalState.Name;
        ProductNumber = originalState.ProductNumber;
        // Etc...

        originalState = null;
    }
}

public void CancelEdit()
{
    if (originalState != null)
    {
        PropertyInfo[] objectProperties =
            this.GetType().GetProperties(BindingFlags.Public |
                                         BindingFlags.Instance);

        foreach (PropertyInfo propInfo in objectProperties)
        {
            object originalValue = propInfo.GetValue(originalState, null);
            propInfo.SetValue(this, originalValue, null);
        }

        originalState = null;
    }
}

Both the DataForm and DataGrid have built-in support for calling the BeginEdit/EndEdit/CancelEdit methods on bound objects that implement the IEditableObject interface.

The DataForm control will call the BeginEdit method when changes are first made to the bound object via the bound controls, and commit them by calling the EndEdit method when the user navigates away from the current object, or when they user explicitly commits the changes (by clicking the OK button when the DataForm's AutoCommit property is set to False). As discussed earlier in the chapter, when a DataForm control is bound to an object that implements the IEditableObject interface, a Cancel button will appear in the data entry form. Clicking this Cancel button will call the CancelEdit method on the object to return it to its original state.

The DataGrid also calls the BeginEdit method when changes are first made to a row, and commits them by calling the EndEdit method when the user navigates away from the current row. Pressing the Esc key when editing a row will call the CancelEdit method on the object to return it to the state it was in prior to its being edited.

Data entry controls can be notified by their bindings of any problems with their bound properties, and will automatically restyle themselves accordingly (adding a red border) to notify the user as such. In addition, a red tooltip will appear next to the control, displaying the validation error message so that the user knows what the problem is. If a label control is bound to a data entry control that has a validation error, then it will also turn red. Figure 7-22 demonstrates what happens when the user enters invalid data into a TextBox control.

Figure 7.22. A TextBox control displaying a validation error

In order for the control to be notified of related validation errors by its bindings, the bindings need to be configured to listen for and handle validation errors. The appropriate property depends on the method you are using to expose the validation errors to the user interface, and will be discussed later in this chapter as we detail these methods.

The ValidationSummary control can be used to display a list of all the data validation errors associated with an object. It does so automatically via its DataContext property (which is inherited from its container), meaning that you can in many cases simply place it in a view like so:

<sdk:ValidationSummary />

and it will automatically display any validation errors on the object inherited by its DataContext property, as shown in Figure 7-23.

Figure 7.23. A ValidationSummary control

If you want to take a more manual approach to assigning errors for it to display, you can also manually assign errors to its Errors property in the code-behind (or bind this property to a collection of validation errors that you maintain), like so:

var error = new ValidationSummaryItem("The Name field is required", "Name",
                                      ValidationSummaryItemType.PropertyError,
                                      null, null);
validationSummary.Errors.Add(error);

The DataForm control has a built-in ValidationSummary control in addition to its standard validation error notification behavior. The ValidationSummary control will automatically appear at the bottom of the DataForm control when the bound object reports any data validation errors (as shown in Figure 7-24). The DataForm control also automatically validates the bound entity/object (at both the property and object level) before committing the changes, preventing the user from committing the changes or moving away from the record until the validation errors have been resolved.

Figure 7.24. A DataForm control displaying a field in error and a validation summary

Like the DataForm control, the DataGrid control also has a ValidationSummary control built in, which appears when the current row has validation errors reported by the bound entity/object. Validation errors will result in the background color of the row changing to a light red. Also, cells with associated validation errors will display a red border and a tooltip explaining the reason for the validation error, when they have the focus (as shown in Figure 7-25).

Figure 7.25. A DataGrid control displaying a cell in error and a validation summary

Prior to Silverlight 4, the only means of notifying the user interface of property-level data validation errors was to throw an exception in the setter of a property. The ValidationException exception (found in the System.ComponentModel.DataAnnotations namespace) was generally used for this purpose. An example of validating a property value and notifying the user interface of a data validation error using the exception method is demonstrated here:

public string Name
{
    get { return name; }
    set
    {
        name = value;

        // Check validation rule
        if (string.IsNullOrEmpty(value))
            throw new ValidationException("You must enter a name for the product");
    }
}

If you set the ValidatesOnExceptions property on the binding to True, then any exception that was thrown when assigning a value to a property via a control will be treated by the binding as a validation error (i.e., when an exception is thrown in the property setter, or when a type converter throws an exception converting the user input before assigning a value to the bound property). As shown earlier, many controls in Silverlight have excellent support for notifying the user of data validation errors, which you can see by setting the ValidatesOnExceptions property on the binding to True (its default value is False) and raising an exception assigning in the bound property's setter. The result will be that the control is restyled appropriately to notify the user that a validation error has been encountered.

In order to deal with the validation error in code, the NotifyOnValidationError property on the binding must have a value of True (which is its default value), and the ValidatesOnExceptions property on the binding must be explicitly set to True. This will cause the BindingValidationError event to be raised on the bound control, which you can then handle. A typical binding for this scenario is demonstrated here:

<TextBox Text="{Binding Path=Name, Mode=TwoWay, NotifyOnValidationError=True,
                        ValidatesOnExceptions=True}"
         BindingValidationError="NameTextBox_BindingValidationError" />

You can then handle the BindingValidationError event on the bound control like so:

private void NameTextBox_BindingValidationError(object sender,

ValidationErrorEventArgs e)
{
    if (e.Action == ValidationErrorEventAction.Added)
    {
        // Do something with the error
        string errorMessage = e.Error.ErrorContent.ToString();
    }
}

Historically, the process of throwing data validation errors as exceptions has never been popular with most developers, as conceptually data validation errors are not "exceptional" scenarios—and exceptions should be confined to only being used when something unexpected occurs. Additionally, in the past when debugging your application, every time an exception was thrown due to a data validation error, the execution of the application would break and throw you back into Visual Studio. You could still continue running the application, but it was a frustrating development experience (unless you opened the Exceptions window from the Debug menu in Visual Studio and specified that the application should not break when a ValidationException exception is raised). This method was also a problem when populating an entity with data, as exceptions could be raised when a value was assigned to a property that may have been invalid at the time (due to a validation rule that compares the values of two properties), but would become valid as further properties were assigned their values.

WPF provided a better way of handling data validation, in which you could implement the IDataErrorInfo interface on your entity, exposing validation errors for an entity/object via two properties, Error and Item, without requiring exceptions to be thrown. In addition, these properties could report all the validation errors on an entity/object instead of just that of the property being updated—a big advantage, especially when updating one property invalidates one or more other properties. Silverlight 4 introduced the IDataErrorInfo interface from WPF, which we can now use instead of throwing exceptions. The Error property exposes a string identifying the validation status of the entity/object as a whole (i.e., a single validation error message). The Item property accepts the name of a property as a parameter, and returns any validation error as a string relating to that property. The following code snippet demonstrates implementing the IDataErrorInfo interface in a simple class:

public class Product : IDataErrorInfo , INotifyPropertyChanged
{
    private string name;
    private Dictionary<string, string> validationErrors =
        new Dictionary<string, string>();

    public string Name
    {
        get { return name; }

set
        {
            name = value;

            // Check validation rule
            if (string.IsNullOrEmpty(value))
            {
                validationErrors["Name"] =
                    "You must enter a name for the product";
            }
            else
            {
                if (validationErrors.ContainsKey("Name"))
                    validationErrors.Remove("Name");
            }

            RaisePropertyChanged("Name");
        }
    }

    public string Error
    {
        get
        {
            string error = "";

            if (validationErrors.Count != 0)
                error = "This object is invalid";

            return error;
        }
    }

    public string this[string columnName]
    {
        get
        {
            string error = "";

            if (validationErrors.ContainsKey(columnName))
                error = validationErrors[columnName];

            return error;
        }
    }

    private void RaisePropertyChanged(string propertyName)
    {
        if (PropertyChanged != null)
            PropertyChanged(this, new PropertyChangedEventArgs(propertyName));
    }

public event PropertyChangedEventHandler PropertyChanged;
}

There is no event included in the IDataErrorInfo interface to raise when there is a data validation error, so you may be wondering how the user interface is automatically aware of data validation errors on a bound entity/object. When using the exception method of raising data validation errors, the user interface would be immediately notified of a validation error by the "bubbling up" nature of exceptions. Instead, with this new method, the user interface becomes aware of data validation errors by handling the PropertyChanged event on the bound entity/object if it implements the INotifyPropertyChanged interface (as was demonstrated in the code snippet). When the value of a property is changed, the entity/object implementing this interface should raise the PropertyChanged event, and any bindings to this entity/object will handle this event and be notified of the change accordingly. If the entity/object also implements the IDataErrorInfo interface, then the bindings will check the Error/Item properties for any data validation errors corresponding to their bound property, and handle them appropriately.

In conjunction with the new IDataErrorInfo interface, bindings now have a new property called ValidatesOnDataErrors (whose default value is False), which will treat any errors exposed by the IDataErrorInfo interface as data validation errors. You must set this to True on your bindings (even in the DataForm control), or else the controls will not look for validation errors associated with their bound properties (and thus will be unaware of them, and won't restyle themselves accordingly).

<TextBox Text="{Binding Path=Name, Mode=TwoWay, ValidatesOnDataErrors=True}" />

If the NotifyOnValidationError property on the binding is set to True (in addition to ValidatesOnDataErrors being set to True), then the BindingValidationError event will be raised on any controls bound to the property being updated if that property has a validation error associated with it (which is implemented in the same way as demonstrated for validation exceptions).

However, not only do we now have the IDataErrorInfo interface, but we also have a new interface in Silverlight 4 called INotifyDataErrorInfo (which WPF doesn't have). This interface enables data validation to be performed asynchronously (such as on the server), notifying the user interface of any data validation errors by raising an event. The IDataErrorInfo interface exposes one method (GetErrors, which returns a collection of all the errors related to a given property), one property (HasErrors, which returns a Boolean value indicating whether the entity/object has any errors), and one event (ErrorsChanged, which is raised when an error is encountered). When using this interface for validation purposes, instead of checking for a data validation error when the PropertyChanged event on the bound entity/object is raised, bindings will wait for the ErrorsChanged event to be raised on the bound entity/object to check for data validation errors (using the GetErrors method) relating to their bound property. In order for the bindings to listen for the ErrorsChanged event, they have a property called ValidatesOnNotifyDataErrors (whose default value is True), which will treat any errors exposed by the INotifyDataErrorInfo interface as data validation errors.

<TextBox Text="{Binding Path=Name, Mode=TwoWay, ValidatesOnNotifyDataErrors=True}"/>

If the NotifyOnValidationError property on the binding is set to True (assuming ValidatesOnNotifyDataErrors still has its default value of True), then the BindingValidationError event will be raised on any controls bound to the property being updated if that property has a validation error associated with it (which is implemented in the same way as demonstrated for validation exceptions).

The following code snippet demonstrates implementing the INotifyDataErrorInfo interface in a simple class:

public class Product : INotifyDataErrorInfo
{
    private string name;
    private Dictionary<string, List<string>> validationErrors =
        new Dictionary<string, List<string>>();

    public string Name
    {
        get { return name; }
        set
        {
            name = value;

            // Check validation rule
            if (string.IsNullOrEmpty(value))
            {
                validationErrors["Name"] = new List<string>();
                validationErrors["Name"].Add(
                    "You must enter a name for the product");
            }
            else
            {
                if (validationErrors.ContainsKey("Name"))
                    validationErrors.Remove("Name");
            }

            RaiseErrorsChanged("Name");
        }
    }

private void RaiseErrorsChanged(string propertyName)
    {
        if (ErrorsChanged != null)
            ErrorsChanged(this, new DataErrorsChangedEventArgs(propertyName));
    }

    public event EventHandler<DataErrorsChangedEventArgs> ErrorsChanged;

    public System.Collections.IEnumerable GetErrors(string propertyName)
    {
        List<string> errors = null;

        if (validationErrors.ContainsKey(propertyName))
            errors = validationErrors[propertyName];

        return errors;
    }

    public bool HasErrors
    {
        get { return validationErrors.Count != 0; }
    }
}

As you can see, there are now three different methods for exposing data validation errors from your entities/objects, any of which the validation attributes can take advantage of (as will be demonstrated shortly). I've already discussed the major disadvantages of using the exception-based method of data validation, but you may be wondering which of the other two methods (the IDataErrorInfo interface or the INotifyDataErrorInfo interface) you should use. In general, you are better off implementing the INotifyDataErrorInfo interface, as it can handle asynchronous validation, and you can also store multiple validation errors for each property. Although you could technically use all three methods together, it is best to standardize on a single method for data validation to avoid confusion.

To validate the new value for a property (in its setter), you can use either the ValidateProperty method or the TryValidateProperty method. When you call the ValidateProperty method, if the given value for a property fails a validation rule, then it will raise a ValidationException exception. When you call the TryValidateProperty method, it will simply return a Boolean value (indicating whether the new value will be valid) and a collection of the failed rules (i.e., it won't raise an exception). This is the preferred method, as it then allows you to handle the validation errors using the means provided by implementing either the IDataErrorInfo or INotifyDataErrorInfo interface in your class.

Here's the process to use the property validation methods on the Validator object:

An example of this process is demonstrated following:

[Required]
public string Name
{
    get { return name; }
    set

{
        name = value;

        List<ValidationResult> validationResults = new List<ValidationResult>();

        ValidationContext validationContext =
            new ValidationContext(this, null, null);
        validationContext.MemberName = "Name";

        bool isValid = Validator.TryValidateProperty(value, validationContext,
                                                     validationResults);

        if (isValid)
        {
            // Remove any validation errors associated with this property
            // (depending on which interface you are implementing)
        }
        else
        {
            // Add the errors in the validationResults variable to your list
            // of errors (depending on which interface you are implementing)
        }

        if (PropertyChanged != null)
            PropertyChanged(this, new PropertyChangedEventArgs("Name"));

        Raise any other required events (e.g., ErrorsChanged)
    }
}

You can also use the Validator class to validate the object as a whole, based upon its validation attributes using the ValidateObject or TryValidateObject method (these methods are fairly similar to their property validation counterparts). These methods validate the object using the validation attributes applied to the object itself, and check that any properties with the Required attribute have a value. You'll generally validate the object in its EndEdit method (when implementing the IEditableObject interface).

Note that by default, the ValidateObject and TryValidateObject methods do not validate the object based upon any of its property-level validation attributes other than the Required attribute (i.e., StringLength, Range, etc.). To include these property-level validations in the object-level validation, you will need to use the overload of the ValidateObject and TryValidateObject methods that includes the validateAllProperties parameter (which you should set to True, as demonstrated in the example following).

An example of performing object-level validation that also validates all of the properties on the object is demonstrated following:

List<ValidationResult> validationResults = new List<ValidationResult>();
ValidationContext validationContext = new ValidationContext(this, null, null);

bool isValid = Validator.TryValidateObject(this, validationContext,
                                           validationResults, true);