Introduction

This article shows how to create text annotations over an image, in a WPF application. The technique involves rendering a custom control in the adorner layer of an Image element, allowing for in-place editing of annotations. The classes used in the demo application can be easily and freely used in other applications to achieve the same functionality.

Background

When you read the newspaper and scribble a thought on the page, you are creating an annotation. The term "annotation" refers to a note which describes or explains part of another document. The Windows Presentation Foundation has built-in support for document annotations, as described here. It does not, however, provide out-of-the-box support for annotating images.

A while back I wrote a blog post about how to annotate an Image element which happens to reside in a Viewbox. This article takes that idea and generalizes it so that any Image can be annotated, not just one contained within a Viewbox. Another improvement seen in this article's demo application is that the annotations are created "in-place", as opposed to typing the annotation text in a TextBox somewhere else in the user interface.

The demo app

This article is accompanied by a demo application, available for download at the top of this page. The demo app allows you to create annotations on two images. It contains explanatory text about how to create, modify, and delete annotations.

Here is a screenshot of the demo application, after a few annotations have been created:

Notice the location of the various annotations, relative to entities in the picture. After the Window is made smaller, you will see that the annotations remain "pinned" to those entities:

Even though the dimensions of the Image element have changed, the annotations remain in the same meaningful locations over the picture. This is an important aspect of image annotations, because the location of an annotation is just as meaningful as its text.

The demo app lets the user delete annotations in several ways. If an annotation loses input focus and has no text, it is automatically deleted. Also, aside from the glaringly obvious 'Delete Annotations' button seen above, you can also delete an annotation by right-clicking on it, to pull up a context menu. For example:

Limitations

The demo app is not a "complete" solution. It does not provide any means of persisting annotations across runs of the application. I did not write annotation persistence code because there are so many different ways that this functionality might be used, that writing my own implementation seemed like a shot in the dark. I did, however, try to write the classes in such a way that it will be straightforward to implement saving and loading of annotations.

The demo app also does not provide any fancy UI features like drag-drop of annotations. That might be a useful feature, but I wanted to keep this simple. Drag-drop in WPF is pretty well documented on the Web, so if you need to add that feature you should be able to find some good reference material out there.

How it works

There are four main participants involved, as seen below:

The ImageAnnotationControl is what you actually see on the screen which displays, and allows you to edit, annotations. ImageAnnotationControl is a ContentControl which exposes one interesting public dependency property, called IsInEditMode. When that property is true, a DataTemplate is applied to the ContentTemplate property which renders the annotation text in a TextBox. When IsInEditMode is false, the annotation text is rendered in a TextBlock. The complete XAML for ImageAnnotationControl is seen below:

<ContentControlx:Class="ImageAnnotationDemo.ImageAnnotationControl"xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"xmlns:local="clr-namespace:ImageAnnotationDemo"x:Name="mainControl"><ContentControl.Resources><!--<span class="code-comment"> The template used to create a TextBox
for the user to edit an annotation. --></span><DataTemplatex:Key="EditModeTemplate"><TextBoxKeyDown="OnTextBoxKeyDown"Loaded="OnTextBoxLoaded"LostFocus="OnTextBoxLostFocus"Style="{DynamicResource STYLE_AnnotationEditor}"Text="{Binding
ElementName=mainControl,
Path=Content,
UpdateSourceTrigger=PropertyChanged}"/></DataTemplate><!--<span class="code-comment"> The template used to create a TextBlock
for the user to read an annotation. --></span><DataTemplatex:Key="DisplayModeTemplate"><Border><TextBlockMouseLeftButtonDown="OnTextBlockMouseLeftButtonDown"Style="{DynamicResource STYLE_Annotation}"Text="{Binding ElementName=mainControl, Path=Content}"><TextBlock.ContextMenu><ContextMenu><MenuItemHeader="Delete"Click="OnDeleteAnnotation"><MenuItem.Icon><ImageSource="delete.ico"/></MenuItem.Icon></MenuItem></ContextMenu></TextBlock.ContextMenu></TextBlock></Border></DataTemplate><StyleTargetType="{x:Type local:ImageAnnotationControl}"><Style.Triggers><!--<span class="code-comment"> Applies the 'edit mode' template
to the Content property. --></span><TriggerProperty="IsInEditMode"Value="True"><SetterProperty="ContentTemplate"Value="{StaticResource EditModeTemplate}"/></Trigger><!--<span class="code-comment"> Applies the 'display mode' template
to the Content property. --></span><TriggerProperty="IsInEditMode"Value="False"><SetterProperty="ContentTemplate"Value="{StaticResource DisplayModeTemplate}"/></Trigger></Style.Triggers></Style></ContentControl.Resources></ContentControl>

ImageAnnotationAdorner is an adorner which is responsible for hosting an instance of ImageAnnotationControl. It is added to the adorner layer of the Image being annotated. ImageAnnotationAdorner is created and positioned by the ImageAnnotation class. That class has no visual representation, but simply serves as a handle to an annotation for the consumer (i.e. the demo app's main Window).

When an ImageAnnotation is created, it installs an adorner in the annotated Image's adorner layer, as seen below:

The Window in the demo app asks ImageAnnotation to create instances of itself when the user clicks on an Image. In addition to informing the annotation where it should exist over the Image, it also specifies two Styles for the ImageAnnotationControl, as seen below:

Those two Style objects allow the annotation consumer to specify how annotations should be rendered, both when in edit mode and display mode. The demo app's Styles, which exist in the main Window's resources, are seen below:

<!--<span class="code-comment"> This is the Style applied to the TextBlock within
an ImageAnnotationControl. --></span><Stylex:Key="AnnotationStyle"TargetType="TextBlock"><SetterProperty="Background"Value="#AAFFFFFF"/><SetterProperty="FontWeight"Value="Bold"/><Style.Triggers><TriggerProperty="IsMouseOver"Value="True"><SetterProperty="Background"Value="#CCFFFFFF"/></Trigger></Style.Triggers></Style><!--<span class="code-comment"> This is the Style applied to the TextBox within
an ImageAnnotationControl. --></span><Stylex:Key="AnnotationEditorStyle"TargetType="TextBox"><SetterProperty="Background"Value="#FFFFFFFF"/><SetterProperty="BorderThickness"Value="0"/><SetterProperty="FontWeight"Value="Bold"/><SetterProperty="Padding"Value="-2,0,-1,0"/></Style>

Very useful code sample, but I have the following challenge : When I allow for zooming into the image, the image itself sticks to its boudaries since I use ClipToBounds="True". My problem is that the annotations are still visible outside the boundaries...

I downloaded the ZIP file, extracted it, opened the SLN file, let the Visual Studio Conversion Wizard run, and the application ran properly for me. I'm using VS2008 SP1. If those steps don't work for you, I suppose you'll have to create a new WPF project, and then add in the files manually.

I don't know since I have never tried to do it before, but I can venture a guess. You will need to use RenderTargetBitmap to draw the Image element and associated annotation adorners to disk. First I'd try just rendering the Image to the RTB and hope it draws the annotations too. If it does, you're done. If it does not, then you will need to figure out a way to loop over the annotation adorner controls and render them after you've rendered the Image element.

:josh:My WPF Blog[^]Without a strive for perfection I would be terribly bored.