Documents

WPF includes three different kinds of documents: flow documents, fixed documents, and XPS documents. These different kinds of documents provide support for high-end text and printing capabilities.

For example, fixed documents allow you to generate a document that keeps the same layout whether it is viewed on a monitor, printed at low-resolution, or printed at a very high-resolution. On each device, the document uses the features available on that device to give the best result possible.

Each of these three kinds of documents is quite complex so there isn’t room to do them justice here. However, the following three sections provide an overview of these kinds of documents and give brief examples.

Flow Documents

Flow documents are designed to display as much data as possible in the best method possible, depending on runtime constraints (such as the size of the control displaying the document). If the control grows, the document rearranges its contents to take advantage of the new available space. If the control shrinks, the document again rearranges its contents to fit the available space. The effect sort of mimics the way a web browser behaves, rearranging the objects it displays as it is resized.

The XAML FlowDocument element represents a flow document. The FlowDocument can contain four basic content elements: List, Section, Paragraph, and Table. These have rather obvious purposes: to display data in a list, group data in a section, group data in a paragraph, or display data in a table.

Although the main emphasis of these elements is on text, they can contain other objects. For example, a Paragraph can contain controls such as Button, Label, TextBox, and Grid controls. It can also contain shapes such as Polygon, Ellipses, and Path.

WMF provides three types of objects for displaying FlowDocuments: FlowDocumentReader, Flow?DocumentPageViewer, and FlowDocumentScrollViewer.

The FlowDocumentReader lets the user pick from three different viewing modes: single page, book reading, and scrolling. In single page mode, the reader displays the document one page at a time. The object determines how big to make a page based on its size. If the reader is wide enough, it will display the FlowDocument in two or more columns, although it still considers its surface to hold a single page at a time, even if that page uses several columns.

In book reading mode, the reader displays two pages at a time. The object divides its surface into left and right halves, and fills each with a “page” of data. The reader always displays two pages, no matter how big or small it is.

In scrolling mode, the reader displays all of the document’s contents in a single long page, and it provides a scroll bar to allow the user to scroll down through the document. This is similar to the way web browsers handle a very tall web page.

Figure 26-13 shows a FlowDocumentReader object displaying a document in book reading mode.

Figure 26-13: This FlowDocumentReader is using book reading mode.

Figure 26-13 demonstrates several useful features of FlowDocument objects. The section headers are contained in Paragraph objects that use a Style that defines their font. If you wanted to change the appearance of all of the headers, you would only need to change the Style.

The FlowDocument uses a LinearGradientBrush that shades from black to gray as the text moves left to right. (The effect is more striking on a monitor if you use a colored gradient.)

The document contains a table in its first section, Button and TextBox controls, an Ellipse, and a Grid that holds a Polygon. It uses the Floater element to allow another Grid containing a Polygon and a text caption to float to a position where it will fit nicely in the display. The document also holds a list, one item of which contains a Polygon drawing a triangle.

The bottom of the FlowDocumentReader displays a toolbar. If you click the magnifying glass button on the left, a search text box appears next to it. You can enter text to search for, and the reader will let you scroll back and forth through any matches.

In the middle of the tool bar, the reader displays the current page number and the total number of pages. The three buttons to the right let the user select the single page, book reading, and scrolling views. Finally the slider on the lower right lets the user adjust the document’s scale to zoom in or out.

The FlowDocumentPageViewer and FlowDocumentScrollViewer objects behave as the Flow?DocumentReader does in its single page and scrolling modes, respectively.

Fixed Documents

A FixedDocument represents a document that should always be displayed exactly as it was originally composed. Whereas a FlowDocument rearranges its content to take advantage of its current size, all of the content in a FixedDocument remains where it was originally placed. If a FlowDocument is similar to a web browser, a FixedDocument is similar to an Adobe Acrobat document.

The FixedDocument object contains one or more PageContent objects, each containing a FixedPage object. It is in the FixedPage object that you place your content. You can use the usual assortment of containers to arrange controls and other objects inside the FixedPage object.

Figure 26-14 shows an application that contains a DocumentViewer object that holds a FixedDocument. The DocumentViewer provides tools to let the user print, zoom in and out, size the document to fit the viewer, display the document in one- or two-page modes, and search for text within the document.

Figure 26-14: The DocumentViewer provides the user with control over the page.

In this example, the FixedDocument object contains two PageContent objects. The first holds a StackPanel containing a TextBlock (for the title) and a Border. The Border contains another TextBlock holding the bulk of the page’s text.

The second PageContent object holds a StackPanel containing the page title’s TextBlock and a Grid. The Grid holds two TextBlocks, an Ellipse, and two Paths.

If this document contained more pages, the vertical scroll bar on the right would let the user view the other pages.

XPS Documents

In addition to flow documents and fixed documents, WPF also defines a third kind of document called XML Paper Specification (XPS) documents. XPS is an XML-based open standard used to represent fixed documents.

An XPS document is stored in a file called a package. The package is made up of pieces called parts. Physically, the parts are arranged as files and folders. When you save the document to disk, it is stored as a ZIP-compressed collection of these physical files and folders. If you change the file’s extension from .xps to .zip, you can read the files using any ZIP-enabled viewer. For example, Windows Explorer will let you browse through the ZIP file.

Logically, the document’s parts form a hierarchical representation of the document. (Remember that the document uses an XML format, and XML is hierarchical, so the document is also hierarchical.) The document itself may contain a FixedDocumentSequence object that contains one or more FixedDocument objects. The FixedDocument objects are similar to the ones described in the previous section, so they can contain container controls that hold any number of objects arranged in a hierarchical way.

In addition to the features provided by FixedDocuments, XPS documents also allow you to digitally sign the package. That tells others that you signed it, gives them the time and date that you signed it, and ensures that the document has not been modified since then. A document can contain more than one signature and you can provide different levels of security on different parts of the document. For example, you could prevent others from changing the document’s body, but allow them to add annotations.

Like the other new WPF document objects, XPS documents are quite complex, and there isn’t room to do them justice here. See Microsoft’s online help (msdn2.microsoft.com/en-us/library/system .windows.xps is a good place to start) and search the Web for more detailed information and examples.

Tip 

Note that many of the WPF examples on the Web were written in early betas and no longer work exactly as they were originally posted. You may need to perform some conversions to make them work properly.