Custom annotations framework (WPF)

Posted on: February 26, 2008

Recently I was asked to share some insight on how I built my custom annotations framework for an application I’m working on. I was asked this on a forum thread by since the reply ended up rather long I decided to cross-post this to the blog as well.

The point of this custom annotations framework was to allow for other visual ques than the standard Highlights and annotations visuals offered by the framework that ships with .NET 3.0/3.5, and also to host threaded discussions inside the annotations themselves. The reasons why this could not be implemented with the standard framework were numerous. Here are some of them:

  • The Highlights that can be added within the framework ar of type SolidColorBrush, and they always take the form of Marker Highlights.
  • The annotations are anchored in the document using DocumentSequenceTextPointers, an internal, sealed class that cannot be used with IAnchorInfo objects.
  • The contents of a the Annotations are limited to Text and Ink.


Well, the annotations framework(AF) really isn’t that complicated, what messes things up is ‘injecting’ things into the Fixed Document at runtime. Thus, the only sensible sollution (and this is how the AF works) is to keep the annotations as seperate entities that carry hooks into the document and get projected ontop of it when displayed.

For my scenario, since I also needed custom highlights and graphic ques as to where the Annotations were anchored inside the documents, my implementation ended up like this:

  • A custom control derived from the DocumentViewer. This control reacts to interaction events fired by mouse and stylus devices to insert visual elements such as highlights and icons into the visual tree of the rendered fixed document. The control also contains logic for loading, displaying and saving these elements as package parts into the XPS package that contains the document loaded in the control.
  • A custom ‘highlight’ class/visual that ‘knows’ its content (the document content to which it was added) and holds one or more custom ‘Annotations’. It also knows its location within the document and is interactive through mouse and stylus events.
  • A custom ‘Annotations’ class/visual that consists of a visual interactive element (control) and the content added to it as either Ink or Text.


When these custom annotations are saved into the XPS package, they are transformed into an xml tree, where each node holds the location of the anchor visual, its type and whatever annotations have been added to it.

As you see, in order to expand the possible content that can be added to my custom annotations I also changed the way the annotations data get saved into the XPS package. I could have translated the format of my annotations to be compatible with at least parts of the annotations framework that ships with .NET 3.5, but since this was not needed, and since this framework depends on (DocumentSequence)TextPointers that really arent necessary in a FixedDocument scenario, I decided not to.

Basically, when the XPS document get translated into a FixedPage object all the elements of the document gets transformed into visual elements such as Glyphs, Paths and and so on. These elements then live inside a Panel such as a Canvas that gets rendered in the DocumentViewer. This allows us to manipulate these visual elements, as well as injecting new ones, at runtime. (Allthough this is not entirely stable and sometimes carries a performance impact.)

However, you should be warned that the element tree/structure of the FixedPage varies depending on whether the document was created by Saving As XPS in Word, Print to XPS in Word, or programmatically by some custom application. Thus, in order to work with the visual tree of the FixedPage you need to support several different tree’s.

Really I think the Annotations Framework (and to some extent the DocumentViewer Control) should be considered samples or reference implementations of what you could accomplish with Fixed Documents such as XPS in WPF. Learn from these implementations and use them to illustrate what can be done, but seriously consider building your own framework to support your specific scenario.

Using WPF it really isn’t that difficult…


2 Responses to "Custom annotations framework (WPF)"


we would like to do something similar, do you have some code samples?


Not really anything that can be shared taken out of context, but you can check out the source from the project that I was working on while writing this post at the link below. The code that you want to look at is in the following file:


The source is at:


Good Luck! (Implementing something like the above really isn’t a big deal, I’m sure you’ll figure it out!)

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s


This blog has no clear focus. It has a focus though, it's just not very clear at the moment...

Dev Env.

Visual Studio 2008 Prof / NUnit / Gallio / csUnit / STools (ExactMagic) / doxygen / dxCore / TypeMock / TestDriven.net / SequenceViz / CLRProfiler / Snoop / Reflector / Mole / FxCop / Subversion / TortoiseSVN / SlikSVN / CruiseControl.net / msbuild / nant

Blog Stats

  • 81,593 hits