Intersoft ClientUI Documentation

XPSDocumentViewer is a specialized implementation of UXDocumentViewer that designed to work with Microsoft XPS document. XPSDocumentViewer includes sophisticated parsing and layout rendering implementation that fully conform to the XML Paper Specification. For more information about XML Paper Specification (XPS), please visit MSDN Library - XPS Document.

With XPSDocumentViewer, you can quickly add rich document viewing capability to your Silverlight and WPF applications without requiring server-side extensions or other third-party plug-ins. Key features include pixel-perfect document rendering, search and highlight matching words, text selection, copy to clipboard, navigate to page, background loading and printing support.

Using XPSDocumentViewer

XPSDocumentViewer shares many common features with UXDocumentViewer such as rich navigation support, zoom presets, text selection, search, localization and printing. To learn about these shared features in details, please refer to UXDocumentViewer Overview.

In addition, XPSDocumentViewer provides a number of advanced features to work with XPS document such as background loading feature which is intended to handle large XPS document and outlines navigation.

There are a number of ways to load an XPS document in XPSDocumentViewer. You can set the Source property of the control to the URI of the document, or set the Document property to an XPSDocument object which is ideal for programmatic loading. The most common and the recommended way to load an XPS document is by setting the Source property which can be declared directly in the XAML. You can also bind the Source property for dynamic loading of an XPS document.

XPSDocumentViewer supports two loading strategies such as discussed below.

When loading from a web server, XPSDocumentViewer automatically displays a busy visual hint indicating the current download progress. You can localize the textual content which is discussed later in this section.

The following example shows how to configure the XPSDocumentViewer to load an XPS document from web server.

Copy Code
<Intersoft:XPSDocumentViewer Source="Assets/Documents/ClientUI_DevForceIntegration.xps" /> 

Configuring Open Document Feature

Regardless of the loading strategies discussed above, XPSDocumentViewer allows users to open an XPS document from the local computer at runtime. To open a local XPS document, users click on the Open command button and select a document from the Open File dialog box such as shown in the following screenshot.

While this feature is useful in most cases, you may find it not desirable in certain scenarios. You can disable the feature by setting the CanUserOpenDocument property to false.

Understanding XPSDocumentViewer Elements

XPSDocumentViewer facilitates users with the capability to open, search, and navigate an XPS document. To achieve these capabilities, UXDocumentViewer comes with rich user interface elements that consisted of UXResizablePaneUXNavigationPaneUXVirtualizingListBox, UXTreeViewUXSearchBox, UXToolBar and UXStatusBar.

The following figure illustrates the rich user interface elements of  XPSDocumentViewer in details.

XPSDocumentViewer Layout and Elements

The top illustration shows the control's elements with the navigation pane expanded, while the bottom illustration shows the control's elements with the navigation pane minimized.

Although the XPSDocumentViewer already provides predefined UI elements to allow rich user interaction, you are free to customize any of the elements to suit your application's preferences – thanks to the loosely-coupled architeture design that made the customization possible. You can customize the styles and appearance of the elements entirely by editing the control template using designer tools such as Expression Blend. To learn more about the commands used in the predefined UI elements, see the XPSDocumentViewer Commands section later in this topic.

Customizing Navigation Mode

XPSDocumentViewer supports two kind of navigation mode: Thumbnails and Outlines. Thumbnails navigation render a list of thumbnails representing the document's pages. This navigation mode is always available which is also the default navigation mode in XPSDocumentViewer.

Outlines navigation mode is only available when the XPS document has a valid table of content that conforms to the XPS specification. The outline entries of the XPS document will be presented in a tree view which uses the UXTreeView control for high-performance tree navigation.

The following example shows how to configure XPSDocumentViewer to use Outlines navigation mode.

Copy Code
<Intersoft:XPSDocumentViewer NavigationMode="Outlines" />

Configuring Loading Mode

XPSDocumentViewer is set to use load-on-demand mode by default, which means that only pages visible in the document will be loaded and rendered. The rest of pages will be loaded when they become visible in the view due to user interactions, for instances, through page scrolling or outline navigation. Depending on your scenario, you may wish to load all pages in XPSDocumentViewer initially which can be achieved by setting the LoadingMode property value to All.

Enabling Background Loading

Designed for performance, XPSDocumentViewer is capable to handle large XPS document without performance bottleneck, thanks to the innovative background loading feature. Background loading allows pages to be preloaded in the background during application's idle time. This means that the background loading will pause the process when it detects user's activities such as mouse movement or key press. 

The idle latency can be customized through the IdleLatency property which is set to 3 seconds by default. You can disable this feature by setting the EnableBackgroundLoading property value to false.

The following example shows how to enable background loading and customize the idle latency time.

Copy Code
<Intersoft:XPSDocumentViewer EnableBackgroundLoading="True" IdleLatency="5"/>

Localizing XPSDocumentViewer

XPSDocumentViewer provides full localization support for the textual content used in the user interface elements. The following table lists the localizable string resources.

OpenText Open...
PrintText Print
CopyText Copy (Also used in context menu.)
ActualSizeText Show Actual Size
FitHeightText Fit Page to Height
FitWidthText Fit Page to Width
FullScreenText Toggle Full Screen
ShowNavigationPaneText Show/Hide Navigation Pane
SearchWatermarkText Find
PreviousSearchText Previous Match
NextSearchText Next Match
Navigation Pane
NavigationHeaderText Navigation Pane
ThumbnailsText Thumbnails
OutlinesText Outlines
Status Bar
PreviousPageText Previous Page
NextPageText Next Page
ChangeZoomLevelText Change Zoom Level
ZoomInText Zoom In (Also used in context menu.)
ZoomOutText Zoom Out (Also used in context menu.)
ContextMenu_PrintText Print...
DocumentViewers Status
LoadedStatusText Loaded {0} of {1} pages.
LoadingDocumentText Loading document {0} {1}...
LoadingStatusText Loading {0} of {1} pages.
LoadingText Loading page {0}.
OpeningDocumentText Opening document...
ReadyText Ready.
SearchingText Searching page {0}
PrintingDocumentText Printing document...

XPSDocumentViewer Toolbar

XPSDocumentViewer provides comprehensive commands for rich viewing experiences. Many of the essential commands are presented as command buttons in the toolbar and status bar section of the control. The complete elements can be seen in the section above.

The following table lists the commands presented in the toolbar section of the XPSDocumentViewer control.

Opening Document
OpenDocument Open a File dialog box to select the XPS file to view.
Page Navigation
PageBox Displays the current page shown in the content section and the total page count of the document. You can enter a page number to directly jump to the specific page.
PreviousPage Scroll to the previous page in the document.
NextPage Scroll to the next page in the document.
ToggelNavigation Show or hide the navigation section.
ShowThumbnails Sets the navigation mode to Thumbnails.
ShowNavigations Sets the navigation mode to Outlines, if applicable.
Page Zooming
ActualSize Sets the zoom mode to show the actual size of the document.
FitWidth Sets the zoom mode to fit the width of the document.
FitHeight Sets the zoom mode to fit the height of the document.
Magnify the document size by a preset ratio.
SearchBox TextBox to fill in the search criteria.
FullScreen Toggle the XPSDocumentViewer control to fill the screen.
Print Print the document using print file dialog.
Copy Copy the highlighted text.

XPSDocumentViewer Commands

XPSDocumentViewer is built around the commanding semantics which allows the document interaction to be executed through declarative definition in the XAML markup. The commanding semantics is also an ideal approach for MVVM pattern development.

In addition to the commands in UXDocumentViewerXPSDocumentViewer also includes predefined commands to interact with the XPS document which are described in the following table.

Commands Description
OpenDocumentCommand Represents the command to open a XPS document using a file dialog.
ShowThumbnailsCommand Represents the command to set the navigation mode to Thumbnails.
ShowOutlinesCommand Represents the command to set the navigation mode to Outlines, if applicable.
GoToEntryCommand Represents the command to scroll to the element that contains the link referenced in the command parameter.
See Also