DOCUMENTS

WPF includes three different kinds of documents: flow documents, fixed documents, and XPS (XML Paper Specification) 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 and give brief examples.

Flow Documents

Flow documents are designed to display as much data as possible in the best way 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 WPF FlowDocument control 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, respectively.

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. It can also contain shapes such as Polygon, Ellipse, and Path.

A fifth content element, BlockUIElement, can hold user interface controls such a Button, Label, and TextBox. A BlockUIElement can hold only one child, but if that child is a container such as a Grid or StackPanel, then the child can contain other controls.

WMF provides three types of objects for displaying FlowDocuments: FlowDocumentReader, FlowDocumentPageViewer, 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.

Example program UseFlowDocumentReader, shown in Figure 11-9 and available for download on the book’s website, shows a FlowDocumentReader object displaying a document in book reading mode. The program’s View menu lets you change the viewing mode.

FIGURE 11-9: This FlowDocumentReader is using book reading mode.

This program 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 toolbar, 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 FlowDocumentReader does in its single page and scrolling modes, respectively. (The big difference is that FlowDocumentReader can display documents in several modes while the others use only one. If you want to offer the reader several options, use FlowDocumentReader. If you want to restrict the view available, use one of the other kinds of viewers.)

Example programs UseFlowDocumentPageViewer and UseFlowDocumentScrollViewer, which are both available for download on the book’s website, demonstrate these controls.

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, then a FixedDocument is similar to an Adobe Acrobat PDF 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.

A program can use a DocumentViewer to display 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.

Example program UseFixedDocument, which is available for download on the book’s website, displays a FixedDocument inside a DocumentViewer.

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 hold container controls that contain 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 WPF document objects, XPS documents are quite complex, and there isn’t room to do them justice here. See Microsoft’s online help (http://msdn2.microsoft.com/system.windows.xps and http://www.microsoft.com/whdc/xps/xpsspec.mspx are good places to start) and search the web for more detailed information and examples.