Share via

Annotations in XPS

  • Article

No doubt you've seen that in version 0.8 of the XML Paper Specification, we pulled support for annotations for V1. This was not an easy decision to make. We've been asked about this a number of times, so we wanted to talk a little about what led to our decision and a little about alternatives that exist in the Windows Presentation Foundation (WPF).

Much of our design efforts on XPS have centered around enabling the core scenarios of creating a high-quality and open "electronic paper" format, creating a trustworthy and integrated document solution, improving the graphics fidelity for viewing and printing documents, and creating a platform for innovation around XPS. Andy Simonds, the GPM of the Windows Digital Documents team, talks about these XPS 5 Points of Light in his blog; it's worth a read.

Throughout the development cycle of XPS, we felt that each feature we added to the specification needed to be grounded in an actual implementation of the feature, which we have included in WinFX and Windows Vista. This is how we demonstrate that the specification is both complete and reasonable to implement. Implicit in this goal is the need for the markup to be as specific to the needs of XPS as possible. This was sometimes a competing goal with our effort to make XPS markup equivalent to a subset of XAML, but we made the right compromises to meet this goal.

An annotations feature is something that fits naturally into an integrated solution, which is why we worked hard to get it defined in the specification for so long. Ultimately, however, we had two basic problems. The first is that of time and resources. To meet our goal of integrating XPS Documents fully for printing, we had to finish V1 in time for Windows Vista. We needed to focus our resources on really polishing the features we do have to make sure they are of high quality. The second is that we were pursuing an annotations model defined as a subset of the WinFX Annotations Framework, much like our approach with XAML. Ultimately, we could not close on a design that met our goals with this approach for V1 that did not also introduce a significant amount of new code to get working in XPS Viewer. This is what motivated the decision to pull Annotations from v0.8 of the XML Paper Specification.

The fact that we pulled annotations from the specification does not mean you can not deliver an annotations solution to your customers built on WPF. Using the DocumentViewer control, it is possible to build an XPS Documents viewer that supports adding annotations and storing those annotations inside the XPS Document. If the recipient of the XPS Document uses your custom viewer, they can see these annotations in place, or if they use the XPS Viewer that comes in WinFX, they'll see the original, un-annotated content.

The DocumentViewer control is a control like any other in the WPF, such as a list box or button. The XPS Viewer that is included in WinFX is a WPF application. In actuality, the XPS Viewer application that you see in WinFX is a wrapper for the DocumentViewer control plus UI for various features.

This design makes it quite easy for a WPF developer to take the DocumentViewer control, wrap it in the specific UI and functionality they want (including, for example, annotations), and voila, you have a custom viewing application. Package this up as a web browser application and you can host this in Internet Explorer, just like the XPS Viewer.

For one sample solution using the Annotations Framework from WinFX, you can check out the new sample code in the Windows SDK for the February CTP. Install the SDK and you'll find the full sample project for how to integrate annotations with the DocumentViewer control, and store the annotations directly in the XPS Document. You can open this XPS Document safely with the XPS Viewer, or you can open it in the sample application and see the annotations you have added. This is located in the content tree under WinFX Development | Samples | Windows Presentation Foundation Samples | Technology Samples | Controls | Control Library | DocumentViewer.

Another approach is to store annotations in your XPS Document in the same format as Office "12" comments, using some of the same techniques described in the previous sample. The new Office "12" file formats are based on the same Open Packaging Conventions as XPS Documents. Note that the Office "12" file formats are currently going through a standardization process with ECMA, as described in Brian Jones' blog.

Regardless, with either approach you should consider a plan for porting your custom annotations solution to any annotations feature we plan to add to the XPS Specification in V2 or beyond. We feel that it's an important feature, but it wasn't important enough to distract us from making XPS Documents the publishing platform for V1.

Happy coding!

Comments