Customizing SinglePageViewer (Part 1)

In this post, we'll take a deeper look into SinglePageViewer.

Like other WPF / Avalon Controls, you can modify the ControlTemplate in order to achieve sophisticated customization of your UI. Robbie has various examples where he's customized the look for common UI controls -- we'll be using the same techniques for SinglePageViewer.

Let's start with the minimal ControlTemplate for SinglePageViewer. I won't bother to show the screenshot here, because it's not very interesting -- we've removed all of the UI, if you view this XAML all you'll see is the "Lorem Ipsum" text. Here's the markup:

<SinglePageViewer xmlns="http://schemas.microsoft.com/winfx/avalon/2005"
                  xmlns:x="http://schemas.microsoft.com/winfx/xaml/2005">

  <SinglePageViewer.Template>
    <ControlTemplate TargetType="{x:Type SinglePageViewer}">
      <AdornerDecorator>
        <DocumentPageView SinglePageViewer.IsMasterPage="True" />
      </AdornerDecorator>
    </ControlTemplate>
  </SinglePageViewer.Template>

  <FlowDocument>
    <Paragraph>Lorem ipsum</Paragraph>
  </FlowDocument>
</SinglePageViewer>

This isn't as self-explanatory as my previous samples, so I'll go into more detail here. Here's the breakdown tag-by-tag:

• <SinglePageViewer.Template>: This is the property element syntax for setting the Template property on the SinglePageViewer. (This is the same technique you'd use in order to customize other controls, such as Button)

• <ControlTemplate TargetType="{x:Type SinglePageViewer}">: This line instantiates the ControlTemplate we're creating, and indicates that the template is targeting a SinglePageViewer through one of the built-in markup extensions. Much like the previous line, this is common across other controls.

• <AdornerDecorator>: This element is required if you want to enable selection and the built-in keyboard shortcuts (selection is drawn in the adorner layer). It's actually optional, but I recommend always using it so your application's keyboard shortcuts are consistent with other applications.

• <DocumentPageView SinglePageViewer.IsMasterPage="True" PageNumber="0" />: The DocumentPageView object is used by the SinglePageViewer to display a page of the document. If you wanted to create a border around the page, you'd do so by surrounding the DocumentPageView with a Border element.The two properties declared are used in order to disambiguate in the cases where we're displaying more than one page. Although you can display more than one page in SinglePageViewer, as the name of the class indicates, it's not really optimized for that scenario. However, it derives from the very general (and very flexible) DocumentViewerBase which does provide generic support for displaying multiple pages.Since we're only displaying one page at a time, we always use the same property settings. Feel free to skip over the rest of this paragraph if you don't care about the details. The IsMasterPage attached property tells the SinglePageViewer that the page being displayed by this DocumentPageView is the primary (aka "Master") page -- it is the one that controls the sizing of each page and the one used when navigating to a portion of the document (i.e. if you click a link to the third page, this determines which DocumentPageView is used to show that third page). Finally, the PageNumber property indicates the offset applied from SinglePageViewer's MasterPageNumber property (if you had two pages, you would want one to have an offset of 0, and the other 1 -- so you're not displaying the same page twice).

Don't worry if you still don't understand 100% of the markup -- you'll typically copy it from an example (or use a tool like Sparkle to create it).

So now you've seen the a minimal ControlTemplate for SinglePageViewer. In the next installment, we'll see how to add an actual interface for this element in order to make it usable.