The WPF test team has recently released a new version of TestApi!  This version includes libraries for fault injection, combinatorial varitation generation, new application control APIs, and updated tests and documentation.  I think all the new libraries are really cool, especially the fault injection libraries.  Learn more about it here.

WPF Control Verifier v0.1

In addition to TestApi, the test team has also developed a tool to verify the behavior of WPF controls.  WPF Control Verifier is a tool that verifies the correctness of WPF Controls. This tool is geared towards WPF Control developers with the goal of providing a set of verifications that all controls can run and consume. Version 0.1 includes one category for verification – default style verification. These tests verify that your control can be styled such that its dependency properties are inheriting or template binding correctly. Future versions will include additional categories of verification.  You can download the tool here.  This is our first beta and we will be updating it based on your feedback. We have a planned set of features for future iterations but this will evolve based on your suggestions. Please send your feedback to wpfcvt@microsoft.com.

Previously I did a post on the “Control Local Values bug” and how a subtle bug can be introduced when setting dependency properties of controls to local values.  In WPF 4.0 (dev10), a mechanism was added to the property engine to solve this problem.  Here are the new APIs in dev10:

Basically, when using DependencyObject.SetCurrentValue instead of DependencyObject.SetValue you set its effective value but its ValueSource remains the same.  This is very similar to coercion. 

Sample Test App

To make it more clear, I wrote a sample test app that shows the BaseValueSource and ValueSource properties when changing a DependencyProperty (DP) via SetCurrentValue.  I created a custom control with a DP, TitleProperty, where I track its values.  In addition, I setup several scenarios where the TitleProperty is initially set by a particular BaseValueSource.  I’ll go through one scenario here. 

I setup the custom control where the TitleProperty is set from a Style with a binding.

Initially it will look like this:

Notice the BaseValueSource is ‘Style’, IsExpression is ‘True’, and IsCurrent is ‘False’ as expected.  After pressing the “Set Current Value” button the values will update accordingly:

Now the local value has updated to a new string that I set and IsCurrent has updated to ‘True’.  Also notice that BaseValueSource and IsExpression have not changed which is also expected.  If you press “Clear Local Value” the values will update back to their initial values.  Now to bring back the original issue with the control local values bug, if you were to set or clear the local value any previous BaseValueSource would be overwritten and any expression lost.  I have created other scenarios in the sample with different BaseValueSource behavior so you can understand how setting the current value behaves in those scenarios.  Please be sure to check it out below.

Usage Recommendation

For a control developer, the general recommendation is to always use DependencyObject.SetCurrentValue over DependencyObject.SetValue in Control code.  You’ll notice that our stock controls in the 4.0 framework have all been updated to use this API instead of setting the properties with local values.

Here is the sample app which works with VS 2010 beta 1.

ControlLocalValuesSample.zip

·         MultiTouch

·         EasingFunctions for animations

·         DataGrid, Calendar, DatePicker, and VisualStateManager in PresentationFramework.dll

·         New APIs to support the control local values bug

·         And tons of bug fixes on the new controls as well as existing control and element services areas

I’ll be going over some of these new features in more depth so stay tuned!

Ivo has a great post about the visual verification APIs and usage that you can view here.  Please try it out and let us know your feedback!

DataGridColumn.SortDirection is used to queue the visual arrow in the DataGridColumnHeader to point up, down, or to not show.  To actually sort the columns other than clicking on the DataGridColumnHeader, you can set the DataGrid.Items.SortDescriptions programmatically. 

Here is an example of an ICommand used to trigger grouping of a particular column in the DataGrid.  In addition to grouping it, I also sort it on the same column name that I grouped it with.  Note that this code will programmatically sort the column but will not update the sorting arrow since I did not update SortDirection.  

2.       DataGridColumns cannot be styled as they are not FrameworkElements.

DataGridColumn derives from DependencyObject, not FrameworkElement, and therefore cannot be styled like many of the other elements on DataGrid.  You can think of a DataGridColumn as data storage for what each cell’s content will be template with and a couple other properties like the width of each cell and how it is sorted.  They are not meant to be visual elements like DataGridCell or DataGridRow.

3.       While editing a row, the row is committed by pressing Enter, pressing tab on the last cell of the row, losing focus, clicking the column header to sort the column, programmatically calling DataGrid.CommitEdit, updating DataGrid.CurrentCell to a cell outside the current row, or updating DataGrid.CurrentItem.

The actions described above are the default actions to commit a row.  One action that deserves a little more clarification is the commit on losing focus.  Each DataGridCell listens for changes to its IsKeyboardFocusWithin property and when it changes it updates the CurrentCell accordingly (which causes the row to commit).

4.       Disable commit behavior through the DataGrid.RowEditEnding event

In the previous gotcha I explain all the ways that a row can be committed.  If you want to customize that behavior, the best way to do it is through DataGrid.RowEditEnding.  This event is fired at the start of any and all row commits and you have the ability to cancel the commit behavior in this event through DataGridRowEditEndingEventArgs.Cancel.  See more about editing behavior here.

5.       Customize focus behavior after a row commit through the DataGrid.RowEditEnding event

While there isn’t a DataGrid.RowEditEnded at this time (March 2009 Release), you can use the Dispatcher trick to get custom behavior after a row commit has occurred.  In DataGrid.RowEditEnding, you can specify a Dispatcher.BeginInvoke so that the code in the delegate is executed after the row commit has completed.  Here is some example code which sets focus to the second cell of the next row and puts it in edit mode but only when I press tab on the last cell of the row before the NewItemPlaceholder.               

See more WPF DataGrid gotchas.

I decided that the way to launch the custom dialog will be through double-clicking on the row.  To get that behavior, I will use the attached behavior pattern on DataGridRow.  The behavior is defined like so:

The behavior is then used on the DataGridRow like this:           

What’s happening is the OnDoubleClick attached property listens for a property change on itself.  I define an ICommand, ShowEditItemDialogCommand, on OnDoubleClick which then hooks up the actual event handler, PreviewMouseDoubleClick, on the target element.  In that event handler, OnPreviewMouseDoubleClick, I retrieve the value of OnDoubleClick which is my ICommand and execute it.  So now we have the behavior to launch a dialog through a double-click action.  The next thing is to define the ICommand ShowEditItemDialogCommand.

I have defined a DataGridRow ViewModel which hosts the actual item data as well as any properties that will drive the view (the DataGridRow).  It also will host any commands on a DataGridRow which for our purposes will be the ShowEditItemDialogCommand.  My commands are also implemented using the RelayCommand mechanism that is discussed on this MSDN article.  So here is the basic implementation:                           

So when DataGridRowBehavior.OnPreviewMouseDoubleClick executes the command, my ShowEditItemDialogCommand will initiate the launch of the new dialog.  The dialog that is being launched is basically a new Window which is considered a View.  From a MVVM purist perspective this does not belong in a ViewModel.  To handle this you can use the mediator design pattern to host the communication between the ViewModel and the View.  There are a couple ways to implement this pattern which include implementing it as an observer pattern or using a specialized communication mechanism through interfaces and references.  I’ve chosen the latter and in the sample code you can see I’ve named it EditDialogDirector to be clear on its behavior.  I won’t show all the details here.

Now, I said earlier that I set a requirement that editing can only come from the dialog that I provide.  While there are a lot of ways to customize the editing behavior, I decided to keep it really simple and set DataGrid.IsReadOnly to true.  It does mean that I will lose the default editing capabilities that DataGrid provides, but I won’t have to keep state on DataGrid begin and commit edits.  There are some other details that I’m leaving out but the full sample code below will give you a good idea of how everything is pieced together.  Also, there is a lot of great reference material and samples on MVVM to further enhance your knowledge on the subject.

https://blogs.msdn.com/johngossman/archive/2005/10/08/478683.aspx

https://karlshifflett.wordpress.com/mvvm/

https://www.codeproject.com/KB/WPF/InternationalizedWizard.aspx

Download the full sample here.  

DataGridMVVMEditingSample.zip

1.       DataGridColumns are not part of the visual tree. 

Since a DataGridColumn has a Binding DP it is easy to think that bindings to other DataGridColumn DPs will work just the same but they don't.  Below is an example showing a DataGridCheckBoxColumn setting the Binding DP and CanUserSort through data binding.  While Binding will bind correctly, CanUserSort will not.                                          

Note that the reason Binding does work is because the internal code dynamically sets the binding of DataGridColumn.Binding to the DataGridCell.Content.  It does not do so for the other DataGridColumn DPs.

Workaround => Check out Jaime’s post on how to get the DataGridColumns to use the same DataContext as the DataGrid.

2.       DataGridColumn.Binding will automatically coerce the binding to BindingMode.TwoWay and UpdateSourceTrigger.Explicit

No matter how you declare the binding for DataGridColumn.Binding, internally it will coerce the BindingMode to TwoWay and UpdateSourceTrigger to Explicit (even if you set them explicitly yourself).  This is because the DataGrid manages the binding operations itself for editing functionality.  Now, you might run into an issue when you have a read-only property with a TwoWay binding mode.  If you set DataGridColumn.IsReadOnly to true, then the BindingMode will not be coerced to TwoWay.

3.       You manage the bindings when using a DataGridTemplateColumn.

The DataGrid internal code does not coerce the bindings set on DataGridTemplateColumn because DataGridTemplateColumn doesn’t even have a Binding DP.  Since you are setting the bindings up yourself, you have to tell it when to commit.  One common way to do this is to setup a OneWay binding on the UIElement in the CellTemplate and a TwoWay binding on the CellEditingTemplate.  See this previous post for example code (under “Template Columns”).  The example code uses an UpdateSourceTrigger of PropertyChanged.  If that does not suite your needs for committing the data, you can mimic what the DataGrid internal code does and update the source yourself.  Set the UpdateSourceTrigger to Explicit and listen to the DataGrid.CellEditEnding event.  You can then update the source explicitly in that event.

4.       Use DataGridColumn.ElementStyle and DataGridColumn.EditingElementStyle to set properties on a cell’s Content.

Each stock DataGridColumn type produces a specific type of Control as the content for each DataGridCell in the column.  See this previous post for more info on that.  It seems that the first instinct to set properties on the cell’s content is to set them through the DataGridCell Style when they should instead be set on DataGridColumn.ElementStyle and/or DataGridColumn.EditingElementStyle.  ElementStyle is the Style applied to the non-editing element.  EditingElementStyle is for the editing element.

In a previous gotcha, I mention that DataGridColumns are not part of the visual tree.  With that said, you can still create bindings that map to the same DataContext as DataGridColumn.Binding on DPs from a Style set on DataGridColumn.ElementStyle and DataGridColumn.EditingElementStyle.  That is because these styles are applied dynamically to the cell’s content which has the correct DataContext.  Below I am setting a DataGridTextBoxColumn’s ElementStyle.  Notice that I have a binding setup on Background with a “MyBrush” property path.  I am assuming that property is coming from the DataContext of the DataGridCell (which is the same DataContext of the DataGridRow).                                                                                                 

5.       Data source items should implement IEditableObject to get transactional editing functionality.

If you are not familiar with IEditableObject, see this MSDN article which has a good explanation and code sample.  The DataGrid has baked in functionality for transactional editing via the IEditableObject interface.  When you begin editing a cell, the DataGrid gets into cell editing mode as well as row editing mode.  What this means is that you can cancel/commit cells as well as cancel/commit rows.  For example, I edit cell 0 and press tab to the next cell.  Cell 0 is committed when pressing tab.  I start typing in cell 1 and realize I want to cancel the operation.  I press ‘Esc’ which reverts cell 1.  I now realize I want to cancel the whole operation so I press ‘Esc’ again and now cell 0 is reverted back to its original value.

See more WPF DataGrid gotchas.

WPF dependency properties are properties that are registered through the WPF property system.  By registering with the property system, the property will be provided a set of services such as data binding, styling, change notifications, animation, expressions, invalidation, and coercion.  What I will be discussing here is dynamic value resolution and the issue of setting local values in controls.

Background

A dependency property’s value is dependent on multiple providers where there is a level of precedence for each provider.  The BaseValueSource enum captures these providers (with the first being the lowest precedence and last being the highest)

·         Unknown

·         Default

·         Inherited

·         ThemeStyle

·         ThemeStyleTrigger

·         Style

·         TemplateTrigger

·         StyleTrigger

·         ImplicitStyleReference

·         ParentTemplate

·         PatentTemplateTrigger

·         Local

In addition to these base value sources, the dependency property can also come from an expression, animation, or coercion (which the internal WPF code represents them as ModifiedValues).  Note that ModifiedValues are mutually exclusive from BaseValueSource.  For example you can have a value that is set locally and coerced at the same time.  

So how does this relate to the control local values bug? 

As a control author, dependency properties are the general mechanism to communicate the state and behavior of the control.  They will be used in data binding scenarios, visual representation, interaction, etc.  This means that you will possibly and most likely be setting values on your dependency properties internally as state changes about your control.  So as you are setting new values to a dependency property that you own, you may not realize that you are introducing a very subtle bug relating to dynamic value resolution precedence.  I’ll use an example to clarify.

The DatePicker control from WPFToolkit has a DP called IsDropDownOpen.  It is used by the DatePicker control to update when the calendar popup opens and closes.  It listens for a change event and sets the Popup.IsOpen accordingly. 

The Popup also listens for when it opens and closes and makes sure IsDropDownOpen is toggled to the correct state. 

Notice the bug?  The bug lies in PopUp_Opened when setting IsDropDownOpen to a local value.  This really appears harmless and you probably won’t actually see the bug in action until you hand it over to the app developer who will actually set different value providers on your control DPs.  The problem is that setting a DP locally as an internal operation in your control will trump any and all value providers set on that DP (as local is the highest precedence).  That means that the app developer who uses your control and decides to put some fancy styles, binding, triggers, and all that goodness will find that it will stop working for some reason and not immediately know what caused it.

To further describe how this can occur, here is an example using that same DatePicker (note that this has already been fixed in later version of the toolkit).   

I’ve setup a style on the DatePicker where I’ve bound a CheckBox.IsChecked DP to the DatePicker.IsDropDownOpen DP.  If you click on the CheckBox, the popup opens as expected.  If you take a look at the BaseValueSource on IsDropDownOpen it will read Style.  However, as soon as you close the popup, the binding does not work anymore which is expected since a local value is set on IsDropDownOpen. 

Summary

To make it really short and sweet, setting dependency properties to local values in internal operations of a control can lead to the dreaded control local values bug.  I’m sure you’re next question is, how can this be prevented?  Well, I will be doing a follow-up post on what has been added in dev10 to easily prevent this bug so stay tuned!

UPDATE: Check out the follow up post here.

Also, a new set of WPF Themes has also been released in the WPF Futures section.  This is a collection of 9 themes that are also found in the Silverlight Toolkit.