XmlTreeView – A Custom Painted TreeView

By , August 28, 2009

[January 2, 2012 Update: A number of changes have been made to the NDFD web service since I originally posted this article. Both the URL and the methods exposed by the service have changed. The text below and downloads have been updated to reflect these changes.]

Last time I described how to build a WCF client for the NDFD web service. The gist was we needed to create a custom TextMessageEncoder that could handle the ISO-8859-1 encoding used by the service. With that done, it’s time to start thinking about how to use all the data to which we now have access. My goal over the next week or so is to convert the NDFD client into its own local WCF service, hosted in a Windows service, to add the ability to get current weather conditions, and finally to build a couple of desktop clients (a desktop Gadget and an ActiveX control) that use the service.

But before I jump into that, I’m going to take a small detour and talk about custom painting a TreeView. This is motivated by the fact that the NDFD Xml data is a bit hard to visually parse when displayed as raw Xml, so I thought I’d simplify my debugging a bit by pushing the data into a custom painted TreeView.

There are a couple approaches to custom painting in a managed TreeView. The simplest (OwnerDraw) is to set the TreeView.DrawMode property like this:

this.DrawMode = TreeViewDrawMode.OwnerDrawText;

or

this.DrawMode = TreeViewDrawMode.OwnerDrawAll;

Then you override OnDrawNode and do your painting. The big benefit with this approach is that the TreeView does most of the heavy lifting – it determines when a TreeNode needs redrawn as well as the bounding rectangle – all you need to do is draw the contents of a node when requested.

The problem with this approach is that as soon as your node content gets a bit complex, you start down a slippery slope of increasing complexity as you add hit test code for selection highlighting etc. And if your drawing code gets the least bit complex, you will start to notice redrawing flicker as you resize windows containing your custom painted TreeView. (It’s unfortunate, but the built-in double buffering does not work for OwnerDrawText or OwnerDrawAll. You can get some improvement in the flicker by overriding WndProc and eating all the WM_ERASEBKGND messages, but it doesn’t really fix the problem.) So, except for the simplest situations, I usually end up using the second approach which is to do all the painting myself (UserPaint). It’s a little complex the first time, but most of the complexity is boilerplate code that you can reuse (the attached code is a pretty good starting point).

You enable user painting by setting several of the ControlStyles bits for your TreeView like this:

this.SetStyle(ControlStyles.UserPaint, true);
this.SetStyle(ControlStyles.AllPaintingInWmPaint, true);
this.SetStyle(ControlStyles.OptimizedDoubleBuffer, true);

Now only OnPaint and OnPaintBackground get called (OnDrawNode is out of the loop), and this is where the fun begins.

For starters, you’ll want to override both OnPaint and OnPaintBackground. For OnPaintBackground, I find it’s usually most efficient to do nothing more than insure the base class OnPaintBackground isn’t called:

protected override void OnPaintBackground(PaintEventArgs pevent)
{
	// We can do a better job of predicting where nodes will paint the background
	// and what area is left, so just disable background painting.
	//base.OnPaintBackground(pevent);
}

This means in OnPaint, we need to paint not only the TreeNodes but the empty area where there are no TreeNodes as well. So OnPaint looks something like this:

protected override void OnPaint(PaintEventArgs e)
{
	// If we have nodes, then we have to draw them - and that means everything
	// about the node.
	if (this.Nodes.Count > 0)
	{
		// If we have nodes then there has to be a Nodes[0]. Use it to get the
		// height of one TreeNode - in a TreeView, all nodes are the same height
		// (unless you are using PInvoke to call TVM_SETITEM and set TV_ITEM 
		// iIntegral member for a specific node - which we are not doing!).
		int nodeHeight = this.Nodes[0].Bounds.Height;
 
		int curY = 0;
 
		// Walk down the client area, stepping by the height of one row, looking 
		// for nodes.
		while (curY <= this.ClientRectangle.Height)
		{
			// This probably isn't the most efficient way to do this, but
			// at least we aren't writing our own code to walk the tree...
			TreeNode node = this.GetNodeAt(0, curY);
 
			// If this rect does contain a node, draw the node.
			if (node != null)
			{
				DrawTreeNodeEventArgs args = new DrawTreeNodeEventArgs(
					e.Graphics,
					node,
					e.ClipRectangle,
					GetNodeStates(node)); // manufacture the proper TreeNodeStates
 
				DrawCustomNode(ref args);
			}
 
			// If this rect doesn't contain a node, we need to fill it with the 
			// background color.
			else
				e.Graphics.FillRectangle(
					_backBrush, 
					0, 
					curY, 
					this.ClientRectangle.Width, 
					nodeHeight);
 
			curY += nodeHeight;
		}
	}
 
	// If there are no nodes in the tree, we're going to have to paint the 
	// entire background.
	else
		e.Graphics.FillRectangle(_backBrush, this.ClientRectangle);
 
	// Don't need - in this case we can guarantee no one is listening...
	//base.OnPaint(e);
}

As you can see, our job is to just walk down the client area of the TreeView, one node height at a time, checking to see if there is a node there. (There is a lot of optimizing opportunity here.) If we have a node we draw it; if there isn’t, we draw background. That’s all there is to it – well almost. You probably noticed there are a couple of methods stuck in the middle of OnPaint that we haven’t talked about yet – and these can be a bit of a pickle.

The first problem we need to resolve is addressed by the GetNodeStates method which supplies the TreeNodeStates parameter for the DrawTreeNodeEventArgs constructor. The stock TreeView that you are familiar with has a curious behavior when it comes to highlighting selected TreeNodes. If you click on one node to select it, its background gets painted with SystemBrushes.Highlight and all is good. But if now you click-and-hold on a second node you will notice the first node loses its highlight and the second node is now highlighted – but it gets even more complex. If now (while still holding your mouse button down) you move your mouse a bit (say more than 15 pixels or so) the highlight reverts to the first node. This behavior is made possible by TreeNodeStates.Focused. It turns out that in a TreeView, node highlighting is indicated by Focused rather than Selected, so it’s the coming and going of Focused for the first and second nodes that is prompting the highlighting behavior we just saw. The problem is that we don’t actually have a way to directly test for the Focused state. If you are using OwnerDrawText or OwnerDrawAll you get the Focused state handed to you when your OnDrawNode override is called, but when doing our own drawing in OnPaint, we need to manufacture the Focused state and this is the purpose for GetNodeStates (this is the secret sauce):

private TreeNodeStates GetNodeStates(TreeNode node)
{
	TreeNodeStates states = 0;
 
	// If mouse button is not down, then normal rules apply - if a node is
	// selected, then it also has focus. We set _mouseDownNode in our
	// OnMouseDown override and clear it in our OnMouseUp override.
	if (_mouseDownNode == null)
	{
		if (node.IsSelected)
			states = TreeNodeStates.Selected | TreeNodeStates.Focused;
	}
 
	// But if a mouse button has been clicked on a node, then we need to check
	// to see if that node is currently drop-highlighted.
	else if (node != _mouseDownNode)
	{
		// If this is the currently selected node, but a mouse button has been
		// clicked-and-held on another node and that node is currently showing 
		// the drop-highlight, then we don't show selection highlighting for this
		// node.
 
		if (!IsDropHighlighted(_mouseDownNode) && node.IsSelected)
			states = TreeNodeStates.Selected | TreeNodeStates.Focused;
	}
 
	// Othewise if this is the node that has been clicked-and-held and if
	// this node is currently showing drop-highlighting, then show it. We 
	// still need to check to see if drop-highlighting is being shown for 
	// this node because if the user clicked-and-held on this node, but
	// then started to move the mouse, drop-highlighting is removed by
	// the underlying Win32 tree control.
	else if (node == _mouseDownNode)
	{
		if (IsDropHighlighted(node))
			states = TreeNodeStates.Focused;
	}
 
	return states;
}

The final pieces here are a couple of calls to the underlying Win32 tree control to get the state of the nodes in question from which we can determine if a particular node is drop-highlighted:

private bool IsDropHighlighted(TreeNode node)
{
	const int MASK = NativeMethods.TVIF_STATE | NativeMethods.TVIF_HANDLE;
 
	// TV_ITEM stateMask doesn't seem to matter when reading state - we get
	// all the state bits anyway (Windows7).
	const int STATEMASK = NativeMethods.TVIS_DROPHILITED;
 
	NativeMethods.TV_ITEM lParam = 
		new NativeMethods.TV_ITEM { 
			hItem = node.Handle, 
			mask = MASK, 
			stateMask = STATEMASK };
 
	UnsafeNativeMethods.SendMessage(
		new HandleRef(this, this.Handle), 
		NativeMethods.TVM_GETITEMW, 
		0, 
		ref lParam);
 
	return (lParam.state & NativeMethods.TVIS_DROPHILITED) != 0;
}

(The definitions for the various Win32 methods, structures and constants can be found in the attached sample.)

The second method we haven’t talked about is DrawCustomNode – this is where I actually get around to drawing the TreeNodes. Since my goal for this project was to create a simple view of an XmlDocument, the code just implements the stylized drawing to do that – and this is where you would put your code to draw a BarGraphTreeNode or whatever. In my case, since I am “syntax coloring” Xml, there is quite a bit going on to insure various segments of the colored text line up correctly – but that’s another story.

The attached sample (executable, source) contains a fully working test app using the NDFD web service to get weather forecasts for specific ZIP codes. It pushes the Xml forecast data into our new XmlTreeView. I hope you enjoy.

Leave a Reply

Panorama Theme by Themocracy