Data See, Data Do : Anatomy

TreeView and HierarchicalDataTemplate, Step-by-Step

MikeHillberg — Fri, 30 Oct 2009 19:40:00 GMT

I’ve never found TreeView to be terribly confusing by itself. But usually I want to data bind a TreeView to a collection with some hierarchy, which leads me to HierarchicalDataTemplate, which didn’t always just write itself for me. If you look at it in steps, though, there really is a pretty nice progression from ListBox to TreeView. Like a lot of my posts, this goes way too deep if you just want to create a quick TreeView. But it’s useful to look at it if you want the HierarchicalDataTemplate to just write itself …

First, start with the example of a simple ListBox:

<sys:String>Western Conference</sys:String>

<sys:String>Eastern Conference</sys:String>

</ListBox>

We can add a trivial ItemTemplate to it:

<ListBox.ItemTemplate>

</DataTemplate>

</ListBox.ItemTemplate>

<sys:String>Western Conference</sys:String>

<sys:String>Eastern Conference</sys:String>

</ListBox>

… and now the list box items are red.

A ListBox is an ItemsControl, and what ItemsControls like to do is wrap their items in a container (more on that here). So the above essentially becomes:

<ListBoxItem.ContentTemplate>

</DataTemplate>

</ListBoxItem.ContentTemplate>

</ListBoxItem>

<ListBoxItem Content="Western Conference"

ContentTemplate="{Binding ElementName=_template1}" />

</ListBox>

That is, for each item in the ListBox, a ListBoxItem is created. The ListBoxItem’s Content property is bound to the item, and the ListBoxItem’s ContentTemplate property is bound to the ListBox’s ItemTemplate.

On to TreeView …

A TreeView is also an ItemsControl; it generates TreeViewItem controls for its items. And actually, if you just take the original example and change “ListBox” to “TreeView”, it looks almost the same:

<sys:String>Eastern Conference</sys:String>

<sys:String>Western Conference</sys:String>

</TreeView>

You can similarly set an explicit item template:

<TreeView.ItemTemplate>

</DataTemplate>

</TreeView.ItemTemplate>

<sys:String>Western Conference</sys:String>

<sys:String>Eastern Conference</sys:String>

</TreeView>

The next step here caught be by surprise when I first saw it. The TreeView is going to create a TreeViewItem for each of its items (the two strings). A TreeViewItem is a HeaderedItemsControl, which is an ItemsControl (just like ListBox and TreeView), but also has a Header (and HeaderTemplate) property. (The Header is the part of the tree view item that you always see, right next to the expand/collapse button.) The Header/HeaderTemplate of a HeaderedItemsControl is analogous to the Content/ContentTemplate of a ContentControl. So, whereas the ListBox items were bound to each ListBoxItem’s Content property, in the TreeView case the items are bound to the TreeViewItem’s Header property. Similarly, the TreeView’s ItemTemplate property is bound to the TreeViewItem’s HeaderTemplate property. And in the end we essentially have:

<TreeViewItem.HeaderTemplate>

</DataTemplate>

</TreeViewItem.HeaderTemplate>

</TreeViewItem>

<TreeViewItem Header='Eastern Conference'

HeaderTemplate='{Binding ElementName=_template2}' />

</TreeView>

Now what we need is some hierarchy. Those items are the MLS conferences, and there’s supposed to be teams in those conferences. Here’s the full data:

var western = new Conference("Western")

{

Teams =

{

new Team("Club Deportivo Chivas USA"),

new Team("Colorado Rapids"),

new Team("FC Dallas"),

new Team("Houston Dynamo"),

new Team("Los Angeles Galaxy"),

new Team("Real Salt Lake"),

new Team("San Jose Earthquakes"),

new Team("Seattle Sounders FC"),

new Team("Portland 2011"),

new Team("Vancouver 2011")

}

};

var eastern = new Conference("Eastern")

{

Teams =

{

new Team("Chicago Fire"),

new Team("Columbus Crew"),

new Team("D.C. United"),

new Team("Kansas City Wizards"),

new Team("New York Red Bulls"),

new Team("New England Revolution"),

new Team("Toronto FC"),

new Team("Philadelphia Union 2010")

}

};

var league = new Collection<Conference>() { western, eastern };

DataContext = new

{

WesternConference = western,

EasternConference = eastern,

League = league

};

(Note that the DataContext now has this sample data.)

And now we can show all the teams with some explicit hierarchy:

<TreeViewItem Header='Western Conference'

ItemsSource="{Binding WesternConference.Teams}">

<TreeViewItem.ItemTemplate>

</DataTemplate>

</TreeViewItem.ItemTemplate>

</TreeViewItem>

<TreeViewItem Header='Eastern Conference'

ItemsSource="{Binding EasternConference.Teams}">

<TreeViewItem.ItemTemplate>

</DataTemplate>

</TreeViewItem.ItemTemplate>

</TreeViewItem>

</TreeView>

Of course, what you really want to do is bind the TreeView itself to the hierarchical collection (the League of the DataContext). I.e.:

As you can see, there’s two items, as you’d expect, just like a ListBox. Also just like a ListBox, it doesn’t show anything except for the ToString() of the Conference object. So we need to give it an ItemTemplate to show the conference Name:

<TreeView.ItemTemplate>

</DataTemplate>

</TreeView.ItemTemplate>

</TreeView>

Now, recall that the TreeView here is creating two TreeViewItems, binding the TreeViewItem’s Header to the Conference object, and setting the TreeViewItem’s HeaderTemplate to the TreeView’s ItemTemplate. Next question is, how do we get the TreeViewItem’s ItemsSource bound to Conference.Teams? That’s where the HierarchicalDataTemplate comes in.

A HierarchicalDataTemplate is a DataTemplate with some extra properties. But if you don’t use the extra properties, it’s no different than DataTemplate. For example, change the last markup from DataTemplate to HierarchicalDataTemplate, and nothing changes:

<TreeView.ItemTemplate>

</HierarchicalDataTemplate>

</TreeView.ItemTemplate>

</TreeView>

But HierarchicalDataTemplate adds two key properties: ItemsSource and ItemTemplate. The ItemsSource gets mapped to the TreeViewItem.ItemsSource, and the ItemTemplate gets mapped to the TreeViewItem.ItemTemplate. So now we can show the conferences and the teams:

<TreeView.ItemTemplate>

<HierarchicalDataTemplate.ItemTemplate>

</DataTemplate>

</HierarchicalDataTemplate.ItemTemplate>

</HierarchicalDataTemplate>

</TreeView.ItemTemplate>

</TreeView>

And if you want to show one level deeper in the hierarchy, you can change that team DataTemplate to a HierarchicalDataTemplate:

<TreeView.ItemTemplate>

<HierarchicalDataTemplate.ItemTemplate>

<HierarchicalDataTemplate.ItemTemplate>

</DataTemplate>

</HierarchicalDataTemplate.ItemTemplate>

</HierarchicalDataTemplate>

</HierarchicalDataTemplate.ItemTemplate>

</HierarchicalDataTemplate>

</TreeView.ItemTemplate>

</TreeView>

In the end, the bottom line that I keep in mind when I’m writing a HierarchicalDataTemplate, is that it’s the template for the TreeViewItem.Header, and it lets me set the TreeViewItem’s ItemsSource and ItemTemplate properties.

Why is it called a "DependencyProperty"?

MikeHillberg — Fri, 27 Mar 2009 20:04:00 GMT

When we create new classes and members we spend a lot of time and effort to make them as usable, understandable, and discoverable as possible. We follow the .Net Design Guidelines in general, and in particular we constantly look at how this new class relates to other classes, future plans, etc.

So we went through all that when naming DependencyProperty and DependencyObject. All told we probably spent hours just on the name. What dependency properties (DPs) boil down to in the end is property calculation and dependency tracking. Property calculation isn’t terribly distinctive, lots of properties do that, so the essence of a DP is really the dependency tracking, thus “Dependency” properties.

Here’s an example of that, actually one piece of sample code that shows several examples of dependency tracking:

<StackPanel.Resources>

<Style.Triggers>

</Trigger>

</Style.Triggers>

</Style>

</StackPanel.Resources>

</StackPanel>

The properties of this TextBlock have quite a few dependencies:

· TextBlock.Text is dependent on the Binding, and the Binding is dependent on the DataContext in this case. The DataContext is inheriting down from the StackPanel, so the Text property is therefore also dependent on the shape of the tree; if the TextBlock is removed from the StackPanel, it’s Text property will update.

· TextBlock.FontSize is dependent on the tree as well. Here, you can see it’s inheriting from the StackPanel.

· All of the TextBlock properties depend on TextBlock.Style. For example, here TextBlock.FontWeight is coming from the Style.

· Similarly, TextBlock.Background depends on the Style, but here it’s being set in trigger. So TextBlock.Background in this case also depends on TextBlock.IsMouseOver.

Sometimes, if you write your own DP, you need to help with the dependency tracking. You do this by calling InvalidateProperty when a property needs to be re-calculated, usually because you reference it in a CoerceValueCallback.

For example, here’s a DP Foo and a companion (read-only) DP named FooPlus1. FooPlus1 just has a CoerceValueCallback that calculates “Foo+1”. Foo therefore has a PropertyChangedCallback that invalidates FooPlus1 whenever Foo changes.

// Foo property

public int Foo

{

get { return (int)GetValue(FooProperty); }

set { SetValue(FooProperty, value); }

}

public static readonly DependencyProperty FooProperty =

DependencyProperty.Register("Foo", typeof(int), typeof(Window1),

new PropertyMetadata(FooChangedCallback));

static void FooChangedCallback(DependencyObject d, DependencyPropertyChangedEventArgs args)

{

// Whenever Foo changes, we need to invalidate FooPlus1, so that

// the DependencyProperty system knows to update it (call its

// CoerceValueCallback again).

(d as Window1).InvalidateProperty(Window1.FooPlus1Property);

}

// FooPlus1 Property

public int FooPlus1

{

get { return (int)GetValue(FooPlus1Property); }

}

static readonly DependencyPropertyKey FooPlus1PropertyKey =

DependencyProperty.RegisterReadOnly("FooPlus1", typeof(int), typeof(Window1),

new PropertyMetadata(0, null, CoerceFooPlus1Callback));

static readonly DependencyProperty FooPlus1Property = FooPlus1PropertyKey.DependencyProperty;

static object CoerceFooPlus1Callback(DependencyObject d, object baseValue)

{

return (d as Window1).Foo + 1;

}

ICommand is like a chocolate cake

MikeHillberg — Sat, 21 Mar 2009 01:48:00 GMT

(This has been updated with some information about the origin of a routed command’s route, and of focus scopes.)

ICommand in WPF is a pretty simple thing at its core. But it gets more interesting and complicated as you build up functionality on top of it, and integrate it into the higher layers of the UI. So it’s either like a layer cake, or layers of an onion. But onion is an outside-in metaphor, and layer cake is a bottom-up metaphor, and ICommand is easier to think of bottom up, so I’m declaring ICommand to be a layer cake.

For example, commands provide a mechanism to abstract input (so “navigate back” means “navigate back”, whether it came from the keyboard’s back button or the mouse’s X1 button or anywhere else). And commands provide a mechanism for the View to update the Model in a Model/View separated application. And commands provide a way to search the element tree for a command handler, as well as a way for a command handler to say that it doesn’t want to be executed at the moment.

The mechanism for all those scenarios is all very similar, but the scenarios themselves seem so different that it all can get confusing. So here’s a step-by-step description of how it all fits together …

Start with ICommand

ICommand itself is very straightforward:

public interface ICommand

{

void Execute(object parameter);

bool CanExecute(object parameter);

event EventHandler CanExecuteChanged;

}

Given an instance of an ICommand, you just call Execute, and it does whatever it’s supposed to do. Except you shouldn’t call it if it’s CanExecute is false. If you want to know when CanExecute might be willing to give you a different answer, listen to the CanExecuteChanged event.

For example, here’s a super simple command:

public class HelloWorldCommand : ICommand

{

public void Execute(object parameter)

{

Debug.WriteLine("Hello, world");

}

public bool CanExecute(object parameter)

{

return true;

}

public event EventHandler CanExecuteChanged;

}

If you use that like this:

new HelloWorldCommand().Execute(null);

… you’ll see “Hello, world” in the debug output window.

You can make it more interesting with a parameter and by checking CanExecute. First change the command like this:

public class HelloWorldCommand : ICommand

{

public void Execute(object parameter)

{

Debug.WriteLine(parameter);

}

public bool CanExecute(object parameter)

{

return parameter != null;

}

public event EventHandler CanExecuteChanged;

}

… and call it like this:

var hwc = new HelloWorldCommand();

if (hwc.CanExecute(this))

hwc.Execute(this);

… and in my case I see “CommandCake.Window1” in the debugger output window.

Piece o’ cake.

Button (heart) ICommand

Once you have an ICommand instance handy, you can give it to a Button (on the Button.Command property), and Button knows what to do with it. As the simplest example, you can do this with the previous command:

<Grid>

<Grid.Resources>

<local:HelloWorldCommand x:Key="hwc"/>

</Grid.Resources>

Click

</Button>

</Grid>

But if you do that, you’ll notice that the Button is disabled. That’s because Button knows to call CanExecute, but we haven’t specified a parameter, and recall from above that if you pass null as an argument to CanExecute it returns false. So Button has a CommandParameter property that lets you specify what will be passed to CanExecute and Execute:

<Grid>

<Grid.Resources>

<local:HelloWorldCommand x:Key="hwc"/>

</Grid.Resources>

Click

</Button>

</Grid>

Now the button is enabled, and if you click on it, you’ll see “Hello, world” in the debug output window.

This actually isn’t just a Button feature, it’s actually in the base class ButtonBase. And MenuItem is a ButtonBase. So MenuItem (heart) ICommand too.

Update the Model from the View

Now we’ve got enough for the classic Model/View usage of ICommand. In the Model/View practice, your View is a bunch of elements, which is data-bound to your Model, which has your actual content. The View can modify the model with two-way bindings and with commands.

First, before showing an example of this, let’s make it easier to implement ICommand, by introducing a helper class (a more complete DelegateCommand helper can be found in Prism). This just creates an ICommand instance that takes a delegate which will be called by ICommand.Execute:

public class SimpleDelegateCommand : ICommand

{

Action<object> _executeDelegate;

public SimpleDelegateCommand(Action<object> executeDelegate)

{

_executeDelegate = executeDelegate;

}

public void Execute(object parameter)

{

_executeDelegate(parameter);

}

public bool CanExecute(object parameter) { return true; }

public event EventHandler CanExecuteChanged;

}

Now let’s define a Model of a simple Debug writer:

public class DebugWriter

{

ICommand _indentCommand = new SimpleDelegateCommand( (x) => Debug.Indent() );

ICommand _unindentCommand = new SimpleDelegateCommand( (x) => Debug.Unindent() );

ICommand _writeLineCommand = new SimpleDelegateCommand( (x) => Debug.WriteLine(x) );

public ICommand IndentCommand { get { return _indentCommand; } }

public ICommand UnindentCommand { get { return _unindentCommand; } }

public ICommand WriteLineCommand { get { return _writeLineCommand; } }

public int IndentSize

{

get { return Debug.IndentSize; }

set { Debug.IndentSize = value; }

}

… and use it from a View:

<StackPanel.DataContext>

<local:DebugWriter />

</StackPanel.DataContext>

<Grid>

<Grid.ColumnDefinitions>

</Grid.ColumnDefinitions>

<Grid.RowDefinitions>

</Grid.RowDefinitions>

<TextBlock Margin="3">Indent size:</TextBlock>

<TextBlock Grid.Row="1" Margin="3">Output string:</TextBlock>

</Grid>

<Button Command="{Binding IndentCommand}">Indent</Button>

<Button Command="{Binding UnindentCommand}">Unindent</Button>

<Button CommandParameter="{Binding Text,ElementName=OutputString}"

Command="{Binding WriteLineCommand}">WriteLine</Button>

</StackPanel>

Notice here that the Button bound to the WriteLine command (the third Button) has its CommandParameter bound to a TextBox.Text.

Routed commands: an ICommand.Execute implementation that searches for an execute handler

For the above example I used the SimpleDelegateCommand as my implementation of ICommand, which maps ICommand.Execute to a delegate call.

WPF similarly has a built-in ICommand implementation called RoutedCommand. You don’t give a delegate directly to the RoutedCommand, though. Instead, the RoutedCommand walks up the tree, looking for a delegate. It’s similar to a routed event, in fact it’s implemented as a routed event internally. So you can put your delegate anywhere higher in the tree, in the form of an event handler, using the CommandBinding class, and it will be called by Execute. You specify your delegate with a CommandBinding object.

So I add this to my Window1.xaml.cs:

public static RoutedCommand HelloWorldRoutedCommand = new RoutedCommand();

… and this to my Xaml:

<Window.CommandBindings>

<CommandBinding

Command="{x:Static local:Window1.HelloWorldRoutedCommand}"

Executed="CommandBinding_Executed" />

</Window.CommandBindings>

<Grid>

...

<Button Command="{x:Static local:Window1.HelloWorldRoutedCommand}">Hello, world </Button>

...

</Grid>

… and then when I click the Button, my CommandBinding_Executed method gets called:

private void CommandBinding_Executed(object sender, ExecutedRoutedEventArgs e)

{

if( e.Source is Button )

Debug.WriteLine((e.Source as Button).Content);

else

Debug.WriteLine("Hello, world");

}

… and once again I see “Hello, world” in the debug output.

Note that the event handler of the CommandBinding.Executed event can look at the Source property of the event args to see where the RoutedCommand started. You can also get the command itself, and the CommandParameter from the args.

In this example I put the CommandBinding in the tree ancestry of the Button. Alternatively, you can also register your CommandBinding globally, using the CommandManager.RegisterClassCommandBinding method. That CommandBinding’s CanExecute then gets called no matter where in the tree the routed command’s route is starting.

RoutedCommand also has support for CanExecute and CanExecuteChanged. That’s the most complicated part of routed commands, so I’m saving that for the end.

Mapping input to an ICommand (keyboard accelerators)

Beyond Button and MenuItem, there’s another way to get an ICommand to Execute, this one based on user input. As an example, with the following Xaml, pressing <Control>H on the keyboard executes our HelloWorldCommand, again showing “Hello, world” in the debugger:

<Grid>

<Grid.Resources>

<local:HelloWorldCommand x:Key="hwc"/>

</Grid.Resources>

<Grid.InputBindings>

</Grid.InputBindings>

...

Note that this key binding only takes effect if the keyboard focus is currently somewhere under that Grid, e.g. on a TextBox; otherwise the KeyBinding doesn’t see the <Control>H.

RoutedCommand also has an InputGestures property on it, where you can set the default gestures for a command. So you can get this same behavior for the HelloWorldRoutedCommand we created earlier by defining it like this:

public static RoutedCommand HelloWorldRoutedCommand = new RoutedCommand()

{

InputGestures = { new KeyGesture(Key.H, ModifierKeys.Control) }

};

… and then it will Execute no matter where your keyboard focus is.

Built-in routed commands in WPF

Anyone can create a RoutedCommand. But WPF has a set of them built-in. These are all defined as static fields in the ApplicationCommands, EditingCommands, MediaCommands, and NavigationCommands classes. E.g. NavigationCommands has the BrowseBack command, ApplicationCommands has cut/copy/paste, EditingCommands has ToggleBold, MoveRightByWord, etc. The Windows WM_APPCOMMAND commands get converted into these built-in routed commands automatically by the WPF input system.

So, for example, this markup:

<Window.CommandBindings>

<CommandBinding Command="{x:Static NavigationCommands.BrowseBack}"

Executed="BrowseBackExecuted" />

</Window.CommandBindings>

… will cause the BrowseBackExecuted method to be called when the NavigationCommands.BrowseBack command is executed, for example if you click the mouse X1 button (this is the button that makes a web browser navigate back).

From whence the command routes

If you call RoutedCommand’s ICommand.Execute, the route will start from the element that currently has keyboard focus. But RoutedCommand itself has a special overload of Execute that lets you pick where the route starts:

public class RoutedCommand

{

...

public void Execute( Object parameter, IInputElement target);

...

}

And in fact, RoutedCommand’s implementation of ICommand.Execute just calls this Execute, looking roughly like this:

void ICommand.Execute(object parameter)

{

this.Execute(parameter, Keyboard.FocusedElement );

}

Button (and MenuItem) actually understands RoutedCommand in particular, in addition to ICommand in general. So if Button.Command is a RoutedCommand, Button by default calls this RoutedCommand.Execute method, passing itself as the target. You can override this behavior, though, with the Button.CommandTarget property. For example, here is a Button that sends the Cut command to a TextBox:

<Button Command="{x:Static ApplicationCommands.Cut}"

CommandTarget="{Binding ElementName=TextBox1}">Click</Button>

This gets more complicated if you’re implementing a toolbar. Say you have a toolbar with cut/copy/paste buttons. You want that toolbar to work against whatever the currently focused text box is, so you don’t want to have to keep setting CommandTarget. E.g., in this:

<Button Command="{x:Static ApplicationCommands.Paste}">Paste</Button>

</ToolBar>

</StackPanel>

… the Cut/Copy/Paste should route to whichever TextBox has focus.

It doesn’t look like this should work, but it actually does, and here’s why … ToolBar is a “focus scope”. Focus scopes is a whole other post, but the important thing here is what happens with a routed command that’s executing and looking for a CommandBinding. As the execute request bubbles up to the ToolBar, it sees that it’s leaving a focus scope. At that point, rather than just continuing to walk up the visual tree, it goes next to the focused element in that focus scope. In this example, that means that when you click on the Cut button, the search for a handler starts at the Button, then the ToolBar, then the currently-focused TextBox, which is what we want.

Menu is also a focus scope, so what works for ToolBar works for Menu as well.

CanExecute and CanExecuteChanged for routed commands

Just like RoutedCommand allows you to define a command that walks up the tree, looking for someone to handle Execute, you also want to find someone to handle CanExecute. So RoutedCommand’s CanExecute implementation does that, and you can listen for it on CommandBinding, as you’d expect, e.g.:

<CommandBinding

Command="{x:Static local:Window1.HelloWorldRoutedCommand}"

CanExecute="CommandBinding_CanExecute"

Executed="CommandBinding_Executed" />

But here’s the trick: RoutedCommand similarly needs to raise CanExecuteChanged. But how does it know when to raise that event, when it doesn’t know what you’re going to do in CommandBinding_CanExecute?

The solution in WPF is a global event named CommandManager.RequerySuggested. This event is fired whenever the state of the routed command world might have changed. In fact, the implementation of ICommand.CanExecuteChanged in RoutedCommand is just a forwarder:

public event EventHandler CanExecuteChanged

{

add { CommandManager.RequerySuggested += value; }

remove { CommandManager.RequerySuggested -= value; }

}

Next problem: When should the RequerySuggested event fire? You make that happen by calling CommandManager.InvalidateRequerySuggested. But usually you don’t have to call it, it’s called automatically in several places, mostly during keyboard/mouse input.

That all creates a couple of interesting implications.

First of all, if you’re using routed commands, you’ve got some work taking place on every keystroke. On the one hand, even for a fast typist (I clocked in the other day at 88 words/minute on the high-difficulty test!), user input is very infrequent in CPU timeframes. On the other hand, it still takes time to find those CanExecute handlers, and if those handlers do anything non-trivial, and you have a lot of them, it can add up. We’ve seen that be a problem in some larger applications. You can mitigate that by reducing use of routed commands (just use ICommand instead), and by keeping the CanExecute implementations fast.

The second interesting implication is that CommandManager.RequerySuggested is a static (global) event. Usually such events can lead to leaks, because they hold the event handler delegate forever. But RequerySuggested instead only keeps weak references to its handler delegates. But now you’ve got a new problem; now the delegate can be garbage collected. You probably don’t have to worry about that, because most applications don’t listen to RequerySuggested; it’s really the Button doing this on your behalf when you set Button.Command. But Button (and MenuItem) deal with this problem by keeping their own strong reference on that delegate, so that it doesn’t get collected.

In summary

So the key points to remember here:

· ICommand is a simple definition with Execute, CanExecute, and CanExecuteChanged.

· You can point a Button or MenuItem at any ICommand with the Command property. The Button/MouseItem will then Execute that command if you click it, will disable itself if CanExecute is false, and will automatically listen for CanExecuteChanged.

· Routed commands are an ICommand implementation that searches the tree (usually starting with the focused element) for a CommandBinding that provides Execute/CanExecute handlers.

· You can also invoke an ICommand from input, e.g. using a KeyBinding.

· WPF pre-defines a set of routed commands in ApplicationCommands, EditingCommands, NavigationCommands, and MediaCommands.

· Be aware that routed commands can impact perf if you use a lot of them and/or your CanExecute handlers do non-trivial work.

Of logical and visual trees in WPF

MikeHillberg — Sat, 24 May 2008 02:46:00 GMT

This post is about the “logical tree” in WPF, and how it differs from the visual tree. For the most part you don’t need to understand this. But if you want to understand some of the nit-like details of property inheritance, {DynamicResource} references, and ElementName bindings, this may be interesting.

A long time ago, I was trying to arrange all my files in a directory hierarchy (on DOS). I had a directory for different project files, a directory for design documents, etc. Then I hit the classic problem that reminded me of the 3 drawer metal filing cabinet – where do you put a project design document? So I was delighted when Windows95 came out and had shortcut files. A shortcut (similar to symbolic links) is a file that points to another file. (One way to create a shortcut in Windows is to drag a file from one folder to another, using the right mouse button.) So now I could put my project design document in my project directory, then create a shortcut to it in my design directory. My document was in both directories. It was cross-categorized. My row had two key fields. I was happy probably to a fault.

I flashed back to this early in WPF, with a hierarchy of another sort. In this case, the first hierarchy is the visual tree. The visual tree makes great sense to some developers, not as much to others. So we created a cross-categorization called the logical tree to help things to be more … logical. The rest of this post compares the two, and explains the motivation for their existence.

The visual tree always there

The visual tree in WPF is the core of all things rendering. An element doesn’t show up on the screen until it’s in a rendered visual tree. The visual tree is made up, not surprisingly, of Visual objects; Visual is an ancestor class for e.g. controls – like Button and ListBox – and panels – like Grid, StackPanel, and Canvas.

For example, in:

<Grid>

<Button>Click</Button>

</Grid>

… the Grid is the visual parent of the Button, plain as day.

The visual tree affects all things visual, including input. For example, setting the opacity to 50% on a visual parent makes all its children 50% as well (if you also set the child’s opacity to 50%, it is a cumulative 75% transparent). Similarly, setting a transform on the parent, transforms the child as well. Hit-testing goes through the visual tree. Disabling the parent (setting IsEnabled to false) disables visual descendents, etc.

Now look at another example, change the button’s content to a StackPanel:

<Grid>

<TextBlock>Clack</TextBlock>

</StackPanel>

</Button>

</Grid>

… and again the Button’s visual parent is the Grid. But the StackPanel’s visual parent isn’t the Button; it’s a ContentPresenter. Plain as night.

The reason for this is that the Button has a template that describes how the Button really is rendered; that template defines the visual tree under the Button. To make that more explicit, here’s an example of the above that actually shows the template, and therefore what the visual tree will be:

<TextBlock>Clack</TextBlock>

</StackPanel>

<Button.Template>

</ControlTemplate>

</Button.Template>

</Button>

The visual tree in this case, from Button on down, is Button : ContentPresenter : StackPanel : Image/TextBlock.

Here’s another interesting example, this time of elements embedded in text flow:

Hello <Rectangle Width='10' Height='10' Fill='Red' />

</Paragraph>

</FlowDocument>

</RichTextBox>

In this case, you would expect the Rectangle’s “parent” to be the Paragraph. But Paragraph, like Bold and Italic, isn’t a visual. So the Rectangle’s visual parent is actually the RichTextBox.

Enter the logical tree

So we set out to make expectations come true – the StackPanel’s “parent” above should be the Button, and the Rectangle’s should be the Paragraph. To do that, we created some supplementary helper references, like my shortcut files. We gave elements the option to have a second parent, in addition to the visual parent, called the logical parent.

The StackPanel’s logical parent above is the Button, and the Rectangle’s logical parent is the Paragraph. Since that is the “parent” we thought that most developers & designers would interact with, we gave it the better name in the APIs; the logical parent is simply the Parent property on elements, whereas to get to the visual parent you have to call VisualTreeHelper.GetParent static method.

Often, an element’s logical parent is the same as its visual parent. This is the case with elements in a Panel, such as a Grid; the Panel.Children property is a UIElementCollection type, and UIElementCollection has a feature that all items get the Panel as both the logical parent and the visual parent. Other times, such as for the content of a Button (or any ContentControl), the two parents are different.

When does the logical tree matter?

Before going into more detail, let’s talk about where the logical tree is used. The logical parent is relevant for several tree-based features:

· The Parent property

As I just said above, the FrameworkElement.Parent property returns the logical parent. So StackPanel.Parent above returns the Button, and Rectangle.Parent returns the Paragraph.

· Property inheritance

Inheritable properties, such as FontFamily and DataContext, come from an element’s logical parent (or logical ancestor). The exception is that if an element has a visual parent but not a logical parent, the visual parent will be used.

· {DynamicResource} references

If a property has a {DynamicResource} set on it, it will search the .Resources of logical ancestors. Just like property inheritance, though, if there’s only a visual parent, that link is followed instead.

· Name

When looking up a name, such as in {Binding ElementName=Foo}, the search walks up the ancestry looking for a name scope, again just as it does for inheritable properties.

· Routed events

When an event is routing up the tree, such as the MouseLeftButtonDownEvent, the event goes up both the visual parent and the logical parent, if they’re different.

Let’s look at another example, taking an earlier example and adding an inheritable FontWeight property:

<TextBlock>Clack</TextBlock>

</StackPanel>

<Button.Template>

</ControlTemplate>

</Button.Template>

</Button>

Is the FontWeight on the TextBlock bold (inherited from the Button) or normal (inherited from the ContentPresenter)? The StackPanel’s visual parent is the ContentPresenter, and its logical parent is the Button. So in searching for an inheritable property we walk up from the TextBlock to the StackPanel, from there to the Button, and find the property value. So the TextBlock is bold.

Logical tree mechanics

An element doesn’t actually pick its logical parent; instead, a parent “adopts” children. For example, when you set a property value to the ContentControl.Content property, ContentControl takes that value as its logical child. To adopt a new logical child, an element simply calls AddLogicalChild. Similarly, to remove a logical child, an element calls RemoveLogicalChild. Note that you can’t adopt a child that already has a logical parent.

There is also actually an API to walk the logical tree – LogicalTreeHelper.GetParent and LogicalTreeHelper.GetChildren.

Logical tree in WPF controls

WPF controls already do the work to make the logical tree operate correctly. And actually it’s more general than that – Panel, ItemsControl, ContentControl, and Decorator, which are the most common base classes, all do the work to make the logical tree operate already. For example, if you create a custom Button that subclasses ContentControl, your Content property will pick up your button as the logical parent without you doing anything.

Here’s most of the elements in WPF that support the logical tree. Recall that the logical parent is established by the parent, and should be in response to getting/losing property values. Consequently this table lists the classes that have special support, and under which property they implement that support.

Class	Property(ies)
*System.Windows.Controls*
AdornedElementPlaceholder	Child property
ContentControl	Content
Decorator	Child
Grid	Children (inherited from Panel), Columns, Rows
HeaderedContentControl	Content (inherited from ContentControl), Header
HeaderedItemsControl	Items (inherited from ItemsControl), Header
InkCanvas	Children
ItemsControl	Items
Page	Content
Panel	Children
RichTextBox	Document
TextBlock	Text
TextBox	Text
ToolBarTray	ToolBars
ViewBox	Child
*System.Windows.Controls.Primitives*
BulletDecorator	Bullet and Child
DocumentViewerBase	Document
Popup	Child
*System.Windows.Documents*
FixedDocument	Pages
FixedPage	Children
FlowDocument	Blocks
FlowDocumentReader	Document
FlowDocumentScrollViewer	Document
PageContent	Child
Table	RowGroups, Columns
Span	Inlines

Edge cases

There’s a few additional special cases for special circumstances. For example, a ContentControl won’t adopt its Content value as its logical child if the ContentControl is part of a ControlTemplate, and if that new value already has a logical parent. That’s to avoid the scenario of a template part trying to steal the logical child of the outer (“templated parent”) control. That’s getting more detailed, and deserves some more words and a picture. I’ll add that detail soon to complete this story …

In conclusion …

The main take-away from this is that the logical tree supplements the visual tree, to enable things like the Parent property and like property inheritance to behave more intuitively. It’s interesting to go deep and understand the details and the mechanism, but the bottom line is that you rarely need to understand it; base element classes like ContentControl, ItemsControl, Decorator, and Panel already do the work, so you don’t have to.

Model-see, Model-do, and the Poo is Optional

MikeHillberg — Thu, 22 May 2008 01:05:00 GMT

Like a lot of people, I’ve developed software professionally for a lot of different environments: PC systems and embedded systems; high- and low-level languages; kernel mode, user mode, real mode, and protected mode; system services; domain controllers; bootstrappers; image processors; a debugger; a compiler; a search engine; small systems and really big systems; file systems; COM; real-time and internet time. I’ve never quite developed professionally for a mainframe, but I’ve worked on clients for mainframe services, and I sat next to a guy that wrote the services (I also sat next to a guy once who would only use a Commodore 64).

But I’ve been spending the last bunch of years helping to create WPF and Silverlight. So in a model/view world, I look at a lot of things from the View point of view. And from that point of view, you come to realize that all computer applications are really just data visualization applications. There’s certainly other software – services, device drivers, pi calculators (I’m still waiting for that one to respond) – but end-user applications are all about data viz.

Except that’s not quite the right, because you don’t just visualize data; you manipulate it too. E.g. Netflix.com lets me both see and modify my queue. And the word “data” isn’t great either, because it makes you think just of the bits stored in a database. So that got me to all applications being some form of “model visualization and manipulation”.

That doesn’t roll of the tongue either though. So now I just consider all applications to be a case of “model see model do”. Which makes me a code monkey.

Models, Views, and Poo

As for models and views, in my current View point of view, there’s always a view, and there’s optionally some amount (and maybe a large amount) of model. The view visualizes the model, and the end-user interacts with that visualization, which propagates back as changes to the model.

A lot of simple apps just need a view – a bunch of UI controls created in Xaml, with event handlers hooked up to some code-behind logic. But I usually end up splitting up my application logic into some model objects and a view object, with the controls in the view bound to model properties.

For more complex applications, you could have a more complicated view. But then you can’t change the look of your application easily, and views are more difficult to test. The solution to that is more sophisticated models. I like the Model/View/ViewModel approach (MVVM), which is similar to the Model/View/Presenter (MVP) pattern.

But I think it’s really useful to be able to pick the right number of layers and sophistication behind my view as is appropriate for the application; it’s all just some form of model in the end. Dr. WPF and Josh Smith talk about this too. Dr. WPF put a name on this agnosticism towards the particular model – Model/View/Poo. I like it. (There’s a joke in there somewhere about code monkeys and poo.)

Another thing I find interesting about the layers of models is that we continue to work to narrow the gap between the model and the view, by making the model more view-friendly:

· For example, tools generate classes with IEditableObject implementations, which enables view controls to perform cancelable updates to the model objects.

· For example, Linq makes it easier to convert data sources into objects, or to re-shape existing objects into objects more appropriate for the view.

Similarly, we’re making the view more model-friendly:

· For example, it’s easy to bind to any model object, or to lists of objects, or to find visualizations for model objects, etc.

· For example, the CollectionView class provides built-in support for the classic problem of synchronizing two parts of the view, such as the master list and the details pane.

Updates to the Model, from the View, in Xaml

Along the general lines of the “model do” side of things, it’s common to hook events in the view and write code to update the model, or to define commands in the model that are invoked by e.g. buttons in the view. As an experiment, I played with one way of somewhat marrying the two approaches – allow the view to phrase a model method in the form of a command.

The example is a view that’s bound to a File object; the view shows the file name, but as TextBox so that you can change the name. When you click the “Rename” button, it fires a command which calls the Rename method on the File object with the new name from the TextBox.

I.e., here’s the File object, which just has a Name property and a Rename method:

public class File : INotifyPropertyChanged

{

string _name;

public string Name

{

get { return _name; }

set

{

_name = value;

if (PropertyChanged != null)

PropertyChanged(this, new PropertyChangedEventArgs("Name"));

}

public void Rename(string newName)

{

// Perform the file rename here

}

public event PropertyChangedEventHandler PropertyChanged;

}

… here’s some sample data getting hooked up as the DataContext:

public Window1()

{

InitializeComponent();

DataContext = new File() { Name = "TestName" };

}

… and here’s the view, which has a TextBox and a Button, a command on the Button that calls the Rename method, and the argument to the Rename coming from the TextBox:

<Button.Command>

<mc:MethodCommand MethodName="Rename">

<mc:MethodArgument Value="{Binding Text, ElementName=_renameTextBox}" />

</mc:MethodCommand>

</Button.Command>

</Button>

</StackPanel>

The key here is that when the Button is clicked, the MethodCommand is invoked. That MethodCommand calls the Rename method on the File object, passing in the current value of the TextBox as the newName parameter. The File object is picked up by the MethodCommand by inheriting the DataContext.

The rest of this post is the MethodCommand implementation. The reason I made the MethodCommand class and the Arguments property of type Freezable was so that the bindings would be fully functional (so that the DataContext would inherit, and so that ElementName bindings could work).

(I haven’t tested this on Commodore 64 yet.)

using System;

using System.Collections.Generic;

using System.Linq;

using System.Text;

using System.Windows.Input;

using System.Windows;

using System.Reflection;

using System.Collections;

using System.Windows.Data;

using System.ComponentModel;

using System.Windows.Markup;

namespace MethodCommandNS

{

[ContentProperty("Arguments")]

public class MethodCommand

: Freezable, // Enable ElementName and DataContext bindings

ICommand,

INotifyPropertyChanged

{

// The name of the method to call on Invoke

public string MethodName { get; set; }

// When this is set, exceptions during invoke are caught, and the exception

// is set as the Exception property

[DefaultValue(true)]

public bool CatchExceptions { get; set; }

// If there is an exception during a command invoke, and CatchExceptions

// is set, this will have the exception object.

public Exception Exception

{

get { return _exception; }

private set

{

_exception = value;

FirePropertyChanged("Exception");

}

Exception _exception;

// This holds the arguments to be passed to the method.

// This is Freezable so that the DataContext and ElementName bindings

// can work correctly.

public FreezableCollection<MethodArgument> Arguments

{

get { return (FreezableCollection<MethodArgument>)GetValue(ArgumentsProperty); }

}

public static readonly DependencyProperty ArgumentsProperty =

DependencyProperty.Register("Arguments", typeof(FreezableCollection<MethodArgument>), typeof(MethodCommand), null);

// This is a private DP that's used to get the inherited DataContext

// (see it used in the MethodCommand constructor).

private static readonly DependencyProperty ElementDataContextProperty =

DependencyProperty.Register("ElementDataContext", typeof(object), typeof(MethodCommand), null);

// The Target property specifies the object on which to invoke the method.

// If this is null, invoke the method on the DataContext

public object Target

{

get { return (object)GetValue(TargetProperty); }

set { SetValue(TargetProperty, value); }

}

public static readonly DependencyProperty TargetProperty =

DependencyProperty.Register("Target", typeof(object), typeof(MethodCommand), null);

// Constructor

public MethodCommand()

{

// The Arguments property is read-only and never null

SetValue(ArgumentsProperty, new FreezableCollection<MethodArgument>());

// Set a default Binding onto the private ElementDataContextProperty.

// A default binding just binds to the inherited DataContext. This is how

// MethodCommand typically gets the object on which to invoke the method.

BindingOperations.SetBinding(

this,

ElementDataContextProperty,

new Binding());

// By default, catch exceptions that are raised by the method.

CatchExceptions = true;

}

// Fire the PropertyChanged event when the Exception property changes.

public event PropertyChangedEventHandler PropertyChanged;

void FirePropertyChanged(string propertyName)

{

if (PropertyChanged != null)

{

PropertyChanged(this, new PropertyChangedEventArgs(propertyName));

}

// We need to implement this method because we're a Freezzable subtype.

protected override Freezable CreateInstanceCore()

{

throw new NotImplementedException();

}

// Implement the CanExecute members of ICommand

public event EventHandler CanExecuteChanged;

public bool CanExecute(object parameter)

{

// We'll always be enabled to be invokes.

return true;

}

// ICommand.Execute implementation. This version calls ExecuteImpl, which does the

// the actual call. But this method wraps that call in a try/finally, depending on

// the value of CatchExceptions.

public void Execute(object parameter)

{

// Clear out any exception of a former invocation.

Exception = null;

if (CatchExceptions)

{

// Invoke the method in a try/finally

try

{

ExecuteImpl(parameter);

}

catch (Exception e)

{

// Any exceptions will likely come back as a

// TargetInvocationException, but the original exception

// is more interesting.

if (e is TargetInvocationException)

{

if (e.InnerException != null)

Exception = e.InnerException;

else

Exception = e;

}

else

Exception = e;

}

// Otherwise, CatchExceptions isn't set, so just forward the call

else

{

ExecuteImpl(parameter);

}

// ExecuteImpl is where we actually invoke the method.

void ExecuteImpl(object parameter)

{

// See if the Target property is set

object target = Target;

if (target == null)

{

// If not, look for an inherited DataContext

target = GetValue(ElementDataContextProperty);

}

// We must have a target, either from Target or DataContext

if (target == null)

{

throw new InvalidOperationException("MethodCommand target not found (must set either Target or DataContext)");

}

// Get the method to be called. Note that this doesn't support

// overloaded methods, but it could be updated to do so.

MethodInfo methodInfo = target.GetType().GetMethod(MethodName);

if (methodInfo == null)

{

throw new InvalidOperationException("Method '" + MethodName + "' couldn't be found on type '" + target.GetType().Name + "'");

}

// Copy the Arguments to an array

object[] arguments = new object[Arguments.Count];

for (int i = 0; i < Arguments.Count; i++)

arguments[i] = Arguments[i].Value;

// Invoke the method

methodInfo.Invoke(target, arguments);

}

// The MethodArgument class plugs into MethodCommand.Arguments

public class MethodArgument

: Freezable // Enable ElementName and DataContext bindings

{

public MethodArgument() { }

// The value of a method argument

public object Value

{

get { return (object)GetValue(ValueProperty); }

set { SetValue(ValueProperty, value); }

}

public static readonly DependencyProperty ValueProperty =

DependencyProperty.Register("Value", typeof(object), typeof(MethodArgument), null);

// We need to implement this method since we are a subtype of Freezable. But since

// we don't need to support cloning, we won't implement it.

protected override Freezable CreateInstanceCore()

{

throw new NotImplementedException();

}

A look at stretchy elements

MikeHillberg — Fri, 06 Jul 2007 03:31:00 GMT

There are several elements in Wpf that have a "Stretch" property. The basic idea of these properties is to allow you to specify how an element adapts itself to a layout container, such as a Grid. For example, if you have a 100x200 pixel image, and it's being positioned in a 150x300 pixel cell in a Grid, should the image be centered and leave some blank space? Or stretched to fit? And if stretched, should aspect ratio be preserved?

I'll use Image, Viewbox, and Shape (particularly Rectangle and Ellipse) as examples.

Background

First, the basic setup for these examples. Here is a Grid with 9 cells (a 3 by 3 Grid). The center cell (the Border named Content) is where we'll put things that need to be stretched.

<Grid.ColumnDefinitions>

</Grid.ColumnDefinitions>

<Grid.RowDefinitions>

</Grid.RowDefinitions>

</Border>

</Grid>

It looks like this so far (the white box in the middle is the 'Content' Border):

Second, why do we need to stretch at all? The answer is that not every element knows how to size itself to its parent's layout. For example, a Button does know how to size it self; putting a button inside Content gives us:

<Button>Click</Button>

</Border>

and looks like:

That is, the button sized itself to fit the 'layout slot' provided by the container (the center cell of the Grid). (Specifically, the Button doesn't size itself, but the root of the Button's template is a Border, which does size itself.)

Other elements, such as Image, however, need help to determine how or if they fit into their layout slot. Thus the Image.Stretch property.

Stretching an Image

If we set an image into our content, likely its natural size won't be exactly the same as the layout slot provided by the parent. How the image stretches is specified by the Stretch property, which is an enumerator also named Stretch, and has 4 values:

None: The element preserves its "natural size", it's not scaled in any way.
Fill: The element is stretched as necessary to fit the layout slot.
Uniform: The element is stretched to exactly fill either the height or the width of the layout slot, but the "shape" or "aspect ratio" of the element is not altered, and none of the element is clipped.
UniformToFill: The element is stretched so that it completely fills both the height and the width of the layout slot, again the aspect ratio is not altered, and the element is clipped as necessary.

For Image, the default value of Stretch is 'Uniform', so here's an example of that first:

</Border>

Figure: 'Uniform' stretch on an image

Here, the image was scaled to fit the layout slot, but it preserves the aspect ratio of the picture. That avoids distortion of the image, but doesn't fill the entire slot either, resulting in the white bands on the left/right of the image in this case.

To prevent any scaling of the image, set the Stretch to 'None' and you get:

Figure: 'None' stretch on an image

Here we see the image in its natural size, which is bigger than the space allotted to the image by the Grid. As a result, we're only seeing part of the image. (In this case, the part we're seeing is the upper left corner, but you can control that by setting VerticalAlignment and/or HorizontalAlignment on the image.)

To ensure the image exactly fills the layout slot, set Stretch to 'Fill':

Figure: 'Fill' stretch on an image

But notice that this comes at the expense of distortion.

Finally, setting stretch to 'UniformToFill' does a combination of scaling an clipping:

Figure: 'UniformToFill' stretch of an image

In this case, the image is scaled until it's big enough to fit the width of the layout slot, which meant that some of the height had to be clipped.

Stretching any element

You can actually stretch any element tree using the Viewbox decorator. For example, start by replacing the image in our Content with a Viewbox, and start with Stretch set to 'None' so that it has no effect (like Image, the default value for Viewbox.Stretch is 'Uniform'):

<Button>Click</Button>

</Viewbox>

</Border>

Figure: 'None' stretch on a Viewbox

The only difference between this and the same Button example earlier without the Viewbox is that the Viewbox tells the button to be the size it wants to be, rather than growing itself to fit the larger layout slot in the Grid. That is, the Button here takes on it's "natural size".

Next, to see the effect of stretch, change Stretch to 'Uniform' (the default value) and get:

Figure: 'Uniform' stretch on a Viewbox

Here, just like the image example above, the button is stretched until it fills either the height or the width of the layout slot (the height in this example), but the aspect ration is preserved, leaving un-rendered bands on the left/right.

If filling the space is more important than the aspect ration, then you can use 'Fill' again:

Figure: 'Fill' stretch on a Viewbox

And similarly, 'UniformToFill' fills the whole layout slot and preserves the aspect ratio, but clips one of the dimensions:

Figure: 'UniformToFill' stretch on a Viewbox

Stretching shapes

Shapes are mostly similar to Image and Viewbox. Rectangle and Ellipse shapes require an understand of their natural size to make sense of, which is covered later in a separate section. For other shapes, such as Path, the behavior is pretty much the same as Image/Viewbox/etc, but there are a few differences which I'll describe here.

Start with this Path as our 'Content':

<Path.Data>

<PathGeometry.Figures>

<PathFigure.Segments>

</PathSegmentCollection>

</PathFigure.Segments>

</PathFigure>

</PathFigureCollection>

</PathGeometry.Figures>

</PathGeometry>

</Path.Data>

</Path>

One way that Shape.Stretch is different from other type's Stretch properties is that it defaults to 'None' rather than 'Uniform. So, with the stretch set to 'None' we get the Path in its natural size, which is 150x200 in this case:

Figure: 'None' stretch on a path

Now try 'Uniform', where as usual we preserve aspect ration and fill one of the dimensions, causing white bands on the left/right in this example:

Figure: 'Uniform' stretch on a path

Other than the default value of Stretch being 'None', that's all the same as the Stretch examples above for Image & Viewbox. One thing that shapes do differently than other types is that not all of the pixels are scaled; if you look closely at the last picture, the overall path was scaled to be larger, but the stroke was not, it is still 10 pixels wide.

The other difference in Shape's Stretch behavior is in an un-constrained layout, it takes up the same space as it does under 'Fill'. To use some pictures as examples, here's the above Path in a StackPanel, with a Gray rectangle above and below it in the stack, and with the width constrained enough to make the Stretch of 'Uniform' interesting:

... which looks like:

Figure: Path in a StackPanel with over-constrained in width, with Uniform stretch

Since the stretch is Uniform, the Path is scaled down to fit the layout slot while preserving aspect ratio. But notice that there are white bands on the top and bottom. That accounts for the space that the Path would take up under a 'Fill' stretch.

To make that more clear, here's the same Path, next to a Path with a stretch of 'Fill'.

Figure: Same Path in a StackPanel, with 'Uniform' and 'Fill' stretches

Notice that the Path takes up just as much space in the StackPanel in either case.

In contrast, Image and Viewbox only size themselves as necessary, such as in this Image example (still in a StackPanel, and with a Stretch of 'Uniform'):

Figure: An Image in a StackPanel with 'Uniform' stretch

Effect of Width and Height (and other layout properties) on stretching

In the examples so far, the width and height of the layout slot was determined by the root Grid (whose size, in turn, is determined by the Window it lives in). If you specify layout properties such as Width/Height, MaxWidth/MaxHeight, Margin, etc., you might alter the layout slot.

For example, take the image again where we had UniformToFill:

... which looks like:

Figure: 'UniformToFill' stretch on an image (again)

Now, force the Width to be 100:

... and we get:

Figure: 'UniformToFill' stretch on the same image with Width=100

In the first case (where Width isn't specified), the layout slot for the image is 500 pixels wide by 250 high in this example. In that case, by the time the image is scaled down enough to get down to 500 wide, the height hasn't shrunk to 250, causing the height to be clipped. In the second case, setting the Width to 100 reduced the layout slot to 100x250. Now, by the time the image is scaled down enough to meet the height of 250, the width is still much more than 100, causing the width to get clipped.

Rectangle and Ellipse

Rectangle and Ellipse are different from other Path types, because they don't have a natural width and height. That's significant, because all of the stretching behavior depends on that. For example, 'None' stretching means just use the natural width/height, 'Uniform' stretching means preserve the natural width/height.

For example, in the Path example above, the natural size of the Path is determined by the PathGeometry. In a Line, the natural size is determined by the start and end points.

Of course, the Rectangle and Ellipse elements do have properties named "Width" and "Height", but recall that these are layout properties that all elements have (along with other layout properties such as Margin).

As a result, the natural size of any Rectangle or Ellipse is 0x0. Let's see what that does under the different stretches ...

Rectangle with 'Fill' stretch

First, for the examples, change the 'Content' Border to contain a Rectangle:

<Rectangle.Fill>

</LinearGradientBrush>

</Rectangle.Fill>

</Rectangle>

</Border>

... which looks like:

Figure: Rectangle with no Width/Height and default stretch ('Fill')

Notice that the Rectangle has no Width or Height specified. Also note that the default value of the Stretch property on a Rectangle (and Ellipse) is 'Fill', which differs from Image, Viewbox, MediaElement, and Shape, which all default Stretch to 'Uniform'. As a result, the rectangle simply fills the layout slot.

Now specify a Width, say 200, and you get:

Figure: Rectangle with Width and 'Fill' stretch

Here the width of the layout slot is constrained by setting the Width property, but the height is determined by the parent layout. Again, that's all the same as the earlier Image/Viewbox 'Fill' examples.

Rectangle with 'Uniform' stretch

Where Rectangle starts to get interesting is in uniformity. For a Rectangle/Ellipse, "uniform" means "make it a square/circle". So, set our Rectangle with a Width and 'Uniform' stretch (but still no Height):

...

... and we get:

Figure: Rectangle with Width and 'Uniform' stretch

Here we have the Width constrained to be within 200, and the height constrained (by the layout slot) to be within 250. Since the stretch is 'Uniform', the width and height are calculated to be min(200,250)=200, and we get a square that is skinnier and shorter than the layout slot offered by the Grid.

An interesting thing to note here is the positioning of the square; it's centered horizontally but not vertically. The horizontal centering is coming from the Border (recall the parent of this Rectangle is a Border named 'Content'). And the Border actually thinks that it's centering the Rectangle vertically as well; the final height of the rendered Rectangle in this example is reported to be 250 pixels, though it actually only renders 200.

Let's make it more interesting and specify a height of 100:

...

... this gives us:

Figure: Rectangle with Width and Height and 'Uniform' stretch

Here, since this Rectangle is constrained to be a square by the 'Uniform' stretch, and since the Height (100) is more constrained than the Width (200), we get a 100x100 square.

Again, here the positioning of the Rectangle within the 'Content' Border results from the Rectangle having a final size of 200x100, but with the 'Uniform' stretch it only renders 100x100.

Rectangle with 'None' and 'UniformToFill' stretch

So far we've looked at Rectangle with 'Fill' and 'Uniform'. A stretch of 'None' means use the natural size of the object. Since the natural size of a Rectangle or Ellipse is 0x0, setting the stretch to 'None' gives you a size of 0x0.

So the only thing left to look at is UniformToFill. For Rectangle and Ellipse, 'UniformToFill' produces a square/circle, just as is the case with 'Uniform'. Like the other stretch behaviors (e.g. Image and Viewbox above), 'UniformToFill' clips as necessary to fill the layout slot without altering the aspect ratio.

For example, the following shows an Ellipse with no Width or Height specified, and the Stretch set to 'Fill' and then 'UniformToFill':

Figure: Ellipse with no Width/Height and stretch of 'Fill' then 'UniformToFill'

The first picture shows the 'Fill' case, where the Ellipse simply scales to the height and width of the layout slot. In the second picture, the UniformToFill causes the Ellipse to be round, fill the 500x250 pixel layout slot (which is determined by the Grid), and preserve aspect ratio. What this means is that the Ellipse ends up being a 500x500 circle, and the bottom half of it gets clipped.

To sum it up ...

Stretching is about filling your layout slot:

Your layout slot is a function of your parent element, Width/Height, MinWidth/MinHeight, Margin, etc. (The usual layout system features.)
'None' means use your natural size
'Fill' means to scale to the slots width and height, at the expense of shape distortion.
'Uniform' means fill the slot in one dimension, but not the other, in order to preserve aspect ratio.
'UniformToFill' means fill the slot in both dimensions, clipping as necessary, to again preserve aspect ratio.
The default value for Stretch is usually 'Uniform'

When stretching Shape types:

The default value of Stretch is usually 'None'
In unconstrained layouts, such as a StackPanel, the Shape takes up the amount of space that it would under 'Fill' stretch.

Rectangle and Ellipse have some custom handling of stretching:

The default value of Stretch is 'Fill'
'Uniform' means constrain the rectangle/ellipse to be a square/circle
'None' is interpreted as a size of 0x0.

Namespaces in Xaml

MikeHillberg — Wed, 16 May 2007 19:51:00 GMT

If you’re really into Xml conformance, and you’ve really wondered how Xaml uses Xml namespaces, read on; I can cover the most relevant details in 1160 words or less …

Namespaces on tags

(I’m using the term “tag” here instead of the more correct term “element”, so that I don’t get confused with WPF element objects.)

In the W3C Namespaces for XML recommendation, it’s valid for a tag not to be in any namespace; to have no “namespace name”. In Xaml, it’s not. Or rather it’s mostly not; it’s OK if the XML is hiding in a CData section, or in an XData section such as:

<Page

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

xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml" >

<Page.DataContext>

<x:XData>

</BookList>

</x:XData>

</XmlDataProvider>

</Page.DataContext>

<ListBox.ItemTemplate>

</DataTemplate>

</ListBox.ItemTemplate>

</ListBox>

</Page>

... But generally tags must be in a namespace. That because, when Xaml is mapping tags to types, it needs to identify and locate the exact Type. There’s two ways this mapping is done. The really obvious way is for the namespace name URI to use the “clr-namespace” scheme. In this case, the CLR namespace and assembly of the type are specified in the Xaml, such as in the following mappings to the mscorlib.dll assembly for the System.String and System.Collections.ArrayList types:

<Page

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

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

xmlns:sys="clr-namespace:System;assembly=mscorlib"

xmlns:collections="clr-namespace:System.Collections;assembly=mscorlib" >

<Page.DataContext>

<collections:ArrayList>

<sys:String>Hello</sys:String>

<sys:String>World</sys:String>

</collections:ArrayList>

</Page.DataContext>

</Page>

The other way to map tags to types is to match up the namespace name with an assembly that has a corresponding [XmlnsDefinition] assembly attribute. For example, in another post, I put the XmlnsDefinition attribute in my code like this:

[assembly: System.Windows.Markup.XmlnsDefinition(

"http://blogs.msdn.com/mikehillberg/archive/2006/09/27/XamlInspiredMarkup.aspx",

"EmployeeDatabase")]

namespace EmployeeDatabase

{

public class Employee

{

private AddressInformation _contactInformation;

public AddressInformation ContactInformation

{

get { return _contactInformation; }

set { _contactInformation = value; }

}

...

… and then I referenced that type by using the matching namespace name in my markup:

<Employee Name="Rob" Title="President"

xmlns="http://blogs.msdn.com/mikehillberg/archive/2006/09/27/XamlInspiredMarkup.aspx">

<Employee.ContactInformation>

</Employee.ContactInformation>

...

Namespaces on other type references

More generally than just tags, anywhere in Xaml where a string refers to a type, it’s interpreted in the same way. Specifically, any value that references a Type is treated as a QName. A QName is a name that may or may not have a namespace prefix on it. If a QName doesn’t have a prefix, it’s usually interpreted to have the default namespace name. (If an attribute name doesn’t have a prefix it’s not in the default namespace, but more on that later.)

For example, in the following markup, the x:Static markup extension refers to a Class.Property value, so it interprets ‘SystemColors’ (the Class) to be in the default namespace:

<Page

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

xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml" >

<Button Background='{x:Static SystemColors.ControlBrush}'>Click</Button>

</Page>

Or, using a non-default namespace, you can have the equivalent:

<wpf:Page

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

xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml" >

<wpf:Button Background='{x:Static wpf:SystemColors.ControlBrush}'>Click</wpf:Button>

</wpf:Page>

Unprefixed attribute names

Attributes are a bit more interesting and non-obvious than tags or other QNames.

Whereas for tags, an unprefixed tag name is interpreted to be in the default namespace, unprefixed attributes are by definition not in any namespace. The first time I encountered that was when I was watching some XML get parsed by XmlReader. When an unprefixed attribute went by, the NamespaceURI property of the reader was null. I thought it was a bug. But it actually makes sense if you think about this example:

</RandomThings>

Here you have two unprefixed attributes named “State”, but they have different semantics, and more importantly they have distinct sets of valid values: one has to be either liquid, solid, or gas; the other has to be CA, WA, NY, MI, FL, OH, etc. So while the Molecule and Address tags both have the same namespace name (“http://blogs.msdn.com/mikehillberg/NamespacesInXaml”), it wouldn’t make sense to consider the two State attributes to be in the same namespace. And that’s why in the XML namespaces recommendation the State attributes have no namespace name; “interpretation of unprefixed attributes is determined by the element on which they appear”.

And when you think about Xaml being used to map XML to types and properties, that makes even more sense. That’s because you encounter the same rules in a class definition; two different classes can have properties with the same name that have different semantics and types. (A “Molecule” class and an “Address” class could both have un-related “State” properties.)

Thus in this example there’s no namespace prefix on the Background attribute, but we know it references the Button.Background property:

<wpf:Page xmlns:wpf="http://schemas.microsoft.com/winfx/2006/xaml/presentation">

<wpf:Button Background='Red'>Click</wpf:Button>

</wpf:Page>

That’s a “standard” property, though. “Attached” properties are more interesting. For example, in the following, Canvas.Top is an attached property; it’s defined by Canvas, not by Button, despite being set on the Button tag:

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

xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml" >

<Button Canvas.Top='100'>Click</Button>

</Canvas>

</Page>

Since ‘Canvas’ is a reference to a type, it's expanded name uses the default namespace when no prefix is specified. Therefore in this case it has the default namespace name (“http://schemas.microsoft.com/winfx/2006/xaml/presentation”). Or, to make everything explicit again:

<wpf:Page xmlns:wpf="http://schemas.microsoft.com/winfx/2006/xaml/presentation"

xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml" >

<wpf:Canvas>

<wpf:Button wpf:Canvas.Top='100' >Click</wpf:Button>

</wpf:Canvas>

</wpf:Page>

Prefixed attribute names

If you do put a prefix on an attribute for a standard property, and it maps to the same namespace name, then it behaves functionally equivalent to the attribute without the prefix. For example, this markup:

<wpf:Page xmlns:wpf="http://schemas.microsoft.com/winfx/2006/xaml/presentation">

<wpf:Button Background='Red'>Click</wpf:Button>

</wpf:Page>

… is different only in syntax (not function) from this markup, where the Background attribute now has a prefix:

<wpf:Page xmlns:wpf="http://schemas.microsoft.com/winfx/2006/xaml/presentation">

<wpf:Button wpf:Background='Red'>Click</wpf:Button>

</wpf:Page>

You can even give the attribute a different prefix, as long as it has the same namespace name (the URI):

<wpf:Page

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

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

<wpf:Button wpf2:Background='Red'>Click</wpf:Button>

</wpf:Page>

… But if the namespace names are different, you’ll get an error:

<wpf:Page

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

xmlns:wpf2="SomethingElse" >

<wpf:Button wpf2:Background='Red'>Click</wpf:Button>

</wpf:Page>

For attached properties, as noted above, the class part of an attached property attribute name is interpreted as a QName, and so the prefix is used to determine the namespace name. The namespace name of the tag is irrelevant.

Built-in Xaml attributes

Finally, in Xaml there are a few built-in attributes: Key, Name, and Uid. For example, Key is used to provide the key for a dictionary item, such as the ‘myBrush’ here (Page.Resources is a dictionary):

<Page

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

xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml" >

<Page.Resources>

</Page.Resources>

</Page>

These attributes are global and always must have a prefix. For example, if you modify that example so that ‘x:’ is now the default namespace name, the example becomes invalid:

<wpf:Page

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

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

<wpf:Page.Resources>

<wpf:SolidColorBrush Key='myBrush'>Red</wpf:SolidColorBrush>

</wpf:Page.Resources>

<wpf:Rectangle Width='100' Height='100' Fill='{wpf:StaticResource myBrush}' />

</wpf:Page>

… This is invalid because Key is an unprefixed attribute, so it’s interpreted to be a standard property on SolidColorBrush, rather than being interpreted as in the default namespace (and there is no SolidColorBrush.Key property).

One last thing

One last place where Xaml uses XML namespaces is in the Markup Compatibility feature. But this post is already long enough. See Rob’s blog or MSDN for interesting reading.

Expandos in xaml

MikeHillberg — Tue, 15 May 2007 03:36:00 GMT

This post has a couple of suggestions on ways to accomplish expandos in Xaml. First some background …

On an HTML page you can define your own new “expando” properties on the fly, such as in this example:

<HTML>

</BODY>

</HTML>

Here I invented a new property named ‘testing’. I can both set that property and get it (the two parts in yellow above).

That’s a good feature when you want it. It’s a frustrating feature when you don’t. For example, in the following markup, I misspelled the “bgcolor” attribute. I’d like to be told that this is invalid, but instead it’s assumed to simply be an expando property.

<HTML>

<P>Hello</P>

</BODY>

</HTML>

It’s for this reason that the Xaml language is strongly-typed. E.g. the following is a compile/load error (the “BGround” should be “Background”):

<TextBlock BGround='Red'>Hello</TextBlock>

But then if you do want an expando, how do you do it?

One way is to actually define the properties you want to use, as attached properties. For example, this markup uses the ‘MyProperties.Testing’ attached property to set a property onto an unsuspecting TextBlock:

<Window x:Class="WPFApplication1.Window1"

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

xmlns:local="clr-namespace:MyNamespace" >

<TextBlock local:MyProperties.Testing='1, 2, 3' >Hello</TextBlock>

</Window>

.. where the code for MyProperties looks like this:

namespace MyNamespace

{

public static class MyProperties

{

public static string GetTesting(FrameworkElement obj)

{

return (string)obj.GetValue(TestingProperty);

}

public static void SetTesting(FrameworkElement obj, string value)

{

obj.SetValue(TestingProperty, value);

}

// Using a DependencyProperty as the backing store for Testing. This enables animation, styling, binding, etc...

public static readonly DependencyProperty TestingProperty =

DependencyProperty.RegisterAttached("Testing", typeof(string), typeof(MyProperties) );

}

If you don’t want to write any code, you can do it all in markup, though it takes more markup than the HTML case.

First of all, recognize that expandos are really just a property bag of key/value pairs. So in the first HTML example above the P element has a dictionary item that maps the key “testing” to the value ”1,2,3”. In WPF you can get a real dictionary using the built-in Hashtable class. (You can’t use the Dictionary<K,T> class, because Generics aren’t supported in Xaml.) There’s also a Tag property on all elements to hold your random data. Put those two together and you can do something like the following:

<Page

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

xmlns:x='http://schemas.microsoft.com/winfx/2006/xaml'

xmlns:col='clr-namespace:System.Collections;assembly=mscorlib.dll'

xmlns:sys='clr-namespace:System;assembly=mscorlib'

Name='Page1' >

<Page.Tag>

<col:Hashtable>

<sys:String x:Key='testing'>1, 2, 3</sys:String>

<sys:String x:Key='anotherOne'>foo</sys:String>

<sys:String x:Key='yetAnotherOne'>bar</sys:String>

</col:Hashtable>

</Page.Tag>

<!-- This TextBlock.Text Binding queries a property out

of the dictionary -->

</Page>

Update: Another common use of expando properties is to “comment out” an attribute, since XML doesn’t provide a built-in means to do so. I was just reading an old post on Chuck’s blog, and he shows there a way to do this in Xaml by using the markup compatibility feature.

Where does a Binding find its data?

MikeHillberg — Mon, 14 May 2007 20:04:00 GMT

If you’ve look at much WPF Xaml you’ve probably seen bindings like this:

… which binds the Text property of the TextBlock to the Name property of some data object.

The question that begets is: where does the data come from? The rest of this post looks at the answer.

Properties on Binding

The Binding class has a few properties that provide ways to let you set the source of the data onto the Binding, depending on what works best for your situation. Binding looks like this:

public class Binding : BindingBase

{

...

public object Source { get; set; }

public string ElementName { get; set; }

public RelativeSource RelativeSource { get; set; }

...

}

The Source Property

The most straightforward way to set the source of the Binding is to use the Source property. One of the more common ways to do that is to reference the data out of a resource dictionary:

<Grid>

<Grid.Resources>

</Grid.Resources>

</Grid>

(This example creates a ListBox with 3 entries in it, labeled “1”, “2”, and “3”.)

You can be even more explicit by setting the Source directly, specifying the Binding in full Xml syntax (rather than the above markup extension syntax):

<Grid>

<ListBox.ItemsSource>

<Binding.Source>

</Binding.Source>

</Binding>

</ListBox.ItemsSource>

</ListBox>

</Grid>

You can also set the Binding.Source by referencing a static member:

namespace MyNamespace

{

class MyClass

{

public static List<int> MyData;

static MyClass()

{

MyData = new List<int>();

MyData.Add(1);

MyData.Add(2);

MyData.Add(3);

}

…

<Page

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

xmlns:x='http://schemas.microsoft.com/winfx/2006/xaml'

xmlns:my="clr-namespace:MyNamespace" >

</Page>

The ElementName Property

Aside from the Binding.Source property, you can also reference your data by name, using Binding.ElementName, such as:

</StackPanel>

(This example causes the button label to be whatever you type into the text box.)

The RelativeSource Property

The RelativeSource property provides a way to tell the Binding to look around where it’s used to find its source. For example, the ‘Self’ RelativeSource binds to the object on which the Binding is placed, such as in the following (which creates a TextBlock that says “Hi”):

As another example, the following binds the TextBlock.Text property to the Grid in its ancestry (again displaying “Hi” in this case):

<TextBlock

Text='{Binding Tag, RelativeSource={RelativeSource FindAncestor, AncestorType=Grid}}' />

</Border>

</Grid>

The other two modes of a RelativeSource are TemplatedParent and PreviousData.

Explicit DataContext Property

A common way the Binding can get its source is via a DataContext property set on an element (on the element itself, not on the Binding). For (a rather boring) example, this creates a Button that says “Click”:

<Button.DataContext>

<sys:String>Click</sys:String>

</Button.DataContext>

</Button>

This gets more interesting and typical if you set the DataContext somewhere else, usually on the root of the page/window. That works because the DataContext property inherits. The following example shows that by setting the DataContext onto the root. In this case, it is set to be an XmlDataProvider which is querying a Yahoo web service for the weather in Barrow, Alaska. Since the DataContext inherits, Bindings throughout the page have access to it automatically. Note also in this case that since we’re binding to XML, the Bindings are using XPath syntax.

<Page

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

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

<Page.DataContext>

<XmlDataProvider

Source="http://xml.weather.yahoo.com/forecastrss?p=99723"

XPath="/rss/channel"/>

</Page.DataContext>

<Border BorderBrush="Black"

BorderThickness="1" Width="370" Height="170" CornerRadius="6">

<Image Margin="15,15,0,0"

Stretch="None"

HorizontalAlignment="Left"

Source="{Binding XPath=image/url}" />

<!-- Text to say e.g. "Yahoo! Weather - Bellevue, WA", with a hyperlink to a

detailed weather page -->

</Hyperlink>

</TextBlock>

<TextBlock FontWeight="Bold" Margin="15,15,0,0"

Text="{Binding XPath=item[1]/title}"/>

<TextBlock.Text>

<Binding.XPath>

item[1]/*[local-name()="condition" and

namespace-uri()="http://xml.weather.yahoo.com/ns/rss/1.0"]/@text

</Binding.XPath>

</Binding>

</TextBlock.Text>

</TextBlock>,

<TextBlock.Text>

<Binding.XPath>

item[1]/*[local-name()="condition" and

namespace-uri()="http://xml.weather.yahoo.com/ns/rss/1.0"]/@temp

</Binding.XPath>

</Binding>

</TextBlock.Text>

</TextBlock>°

<TextBlock.Text>

<Binding.XPath>

*[local-name()="units" and

namespace-uri()="http://xml.weather.yahoo.com/ns/rss/1.0"]/@temperature

</Binding.XPath>

</Binding>

</TextBlock.Text>

</TextBlock>

Sunrise:

<TextBlock.Text>

<Binding.XPath>

*[local-name()="astronomy" and

namespace-uri()="http://xml.weather.yahoo.com/ns/rss/1.0"]/@sunrise

</Binding.XPath>

</Binding>

</TextBlock.Text>

</TextBlock>, sunset:

<TextBlock.Text>

<Binding.XPath>

*[local-name()="astronomy" and

namespace-uri()="http://xml.weather.yahoo.com/ns/rss/1.0"]/@sunset

</Binding.XPath>

</Binding>

</TextBlock.Text>

</TextBlock>

</StackPanel>

</Border>

</Page>

… Sunrise at midnight, sunset at noon:

Implicit DataContext

Finally, there are a couple of places where the DataContext gets set automatically for you. That usually happens with ContentControl (e.g. Button) and ItemsControl (e.g. ListBox).

Here’s a ContentControl example. In this markup we have a DataTemplate set up in a ResourceDictionary so that it will be used for any ContentControl that has a String as its content. So it’s automatically picked up in the subsequent Button. In that DataTemplate, we have a binding to the data item, which in this case is the ContentControl.Content. Therefore what we get here is a Button that says “Click” in bold italic.

<Page

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

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

xmlns:sys="clr-namespace:System;assembly=mscorlib" >

<Page.Resources>

<!-- The Text property is bound to the Content property of

whatever ContentControl with which this DataTemplate is used -->

</DataTemplate>

</Page.Resources>

<Button>Click</Button>

</Page>

And here’s an ItemsControl example. In this markup, we have a ListBox bound to an integer collection again (using the inherited DataContext as the source), but this time we have an item template, which is a template to use when displaying the items in the ListBox. And within that item template, the DataContext is again automatically set to be the item

<Page

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

xmlns:x=http://schemas.microsoft.com/winfx/2006/xaml >

<Page.DataContext>

</Page.DataContext>

<ListBox.ItemTemplate>

<DataTemplate.Triggers>

<!-- Within the DataTemplate, the DataContext is set to be the data item.

So this DataTrigger.Binding property's DataContext is going to be

the item (1, 2, or 3) -->

</DataTrigger>

</DataTemplate.Triggers>

</Border>

</DataTemplate>

</ListBox.ItemTemplate>

</ListBox>

</Page>