The first step after instantiating the PrintDocument class is to call the Print method. The Print method takes in a parameter specifying the name of your document. This document name is what shows up in the operating system print spooler. The name should be descriptive, containing the title of your report or document. If your application plans to print many of these, you may want to add an identifier such as the patient's name in the case of a medical report, or perhaps some criteria used to generate the report. Listing 19.1 shows how to use the Print method.

Example 19.1. Using the Print method and specifying a document name

This example doesn't do anything meaningful yet—it doesn't print anything. We'll use this as the base for the rest of the examples centered around PrintDocument. Specifically, the placeholders for the TextBlock and the event wire-up will be filled out in later examples.

As written, the code is fairly simple. It sets up the required PrintDocument class instance and calls the Print method. The Print method is asynchronous: it immediately returns once you call it. But it raises all of its events back on the calling thread, so the UI thread can still be blocked.

Note that in untrusted applications, the Print method must be called from a user-initiated event, such as a button click event. Trusted out-of-browser applications (see chapter 5) eliminate this restriction. Once you wire up the PrintPage event (coming up shortly), you'll see that the print spool entry document name will contain the value passed into the Print method. Figure 19.2 shows the Windows 7 print spooler with a Silverlight print document spooled.

Figure 19.2. The Windows 7 print spooler showing the Silverlight document titled "Admittance form for Brown, Pete," created in listing 19.1.

The PrintDocument supports multipage printing. While printing, you'll find it useful to get the current number of pages that have been printed, in order to report the print status to your user. The PrintedPageCount property provides us with this information.

The PrintedPageCount property contains the number of pages sent to the print driver. This doesn't necessarily correspond to the number of pages physically printed, as printers are typically much slower than the PC they're attached to. But it's useful as a general way of reporting status to the user.

PrintedPageCount is a read-only dependency property, so you can bind to that in XAML. Continuing from our example in listing 19.1, we can modify the code and XAML as shown in listing 19.2 to support this. Add the TextBlock in the XAML to the spot reserved with the comment.

Example 19.2. Showing the number of pages printed

Now, when you print a multipage document, the status text will display the number of pages that have been printed so far. This is similar to what you see when you print a document in Microsoft Word, where a status dialog appears with a number showing the progress.

In addition to the PrintedPageCount property, two other events can be used for status reporting, as well as for startup and shutdown code: BeginPrint and EndPrint.

The BeginPrint and EndPrint events are raised at the beginning and end of the print job, respectively. Specifically, BeginPrint is raised before the first call to the Print-Page event, but after the printer dialog is shown, and EndPrint is raised after the last call to EndPrint completes or if the user cancels printing in-progress.

If the user cancels printing from the printer selection dialog, neither BeginPrint nor EndPrint will be raised. Similarly, if Silverlight can't print due to issues with paper format or memory allocation, BeginPrint may not be called.

Continuing our example, the following code shows how to wire up the two events. We won't do anything with BeginPrint in this example, but we'll show a message box when completed using the EndPrint event handler. The event handlers should be inserted into the listing 19.1 code, in the PrintForm method, where the event wire-up comment is located:

_document.BeginPrint += (s, e) =>
    {
    };
_document.EndPrint += (s, e) =>
  {
    MessageBox.Show("Print job completed.");
  };

The BeginPrint and EndPrint methods may be used for status reporting or for doing document build-up and tear-down. Unlike the PrintPage event, their event arguments don't contain any actionable information. It's not essential to wire them up, but you'll find that a complete printing solution typically requires one or both of them.

One event that's not optional is the PrintPage event.

The PageMargins property is a standard Thickness property like those used for margins throughout the rest of Silverlight. It reports the size of the margins set in the printer configuration dialogs in your system.

The PrintableArea property is a Size property that indicates the width and height of the area within the margins. This is the area in which you can lay out your content.

It's important to note that the PageMargins and PrintableArea measurements are all provided at 96 dpi, consistent with screen layout. My printer handles resolutions up to 1200 dpi (normally set to 600 dpi). Despite that, the printable page area comes through at 784 × 1024 and the margins come through at 16,16,16,16. Add 32 (right and left margin) to 784 and divide by 96, and you get 8 1/2 inches. Do the same for the height and you get 11 inches. 8 1/2 × 11 inches is, in the US, the size of a standard sheet of letter-sized paper. The print quality itself is better than that, but still not as good as what you may be used to.

Similarly, if you print using the Microsoft XPS Document print driver (a great test driver), you'll see that it has no enforced margins, and therefore provides a size of 816 × 1056.

If the content you have won't fit on a single page, Silverlight will clip it to the dimensions specified in PrintableArea. In those cases, you may want to handle manually clipping and saving the remaining elements for the next page. To indicate additional pages, use the HasMorePages property.

Printed documents may consist of more than one page. But without precalculating all the page content (not a bad idea, but not required), you won't know the number of pages until you're done printing. Similarly, you don't necessarily know if a page is the last page until you try to fit all the content into the printable area and see what fits.

For those reasons, the PrintPage event includes the boolean HasMorePages property. Simply assign true to this property to indicate that the current page isn't the last page to be printed. This will cause Silverlight to raise another PrintPage event upon the completion of the current one. When you have no more pages to print, set Has-MorePages to false (the default value) to end printing. The following code expands upon listing 19.1 to do a simple check against a hard-coded number of pages. The -1 is because the PrintedPageCount is incremented after the PrintPage event returns:

int numberOfPages = 5;

_document.PrintPage += (s, e) =>
  {
    Debug.WriteLine("Printing page");

    e.PageVisual = LayoutRoot;
    e.HasMorePages =
        _document.PrintedPageCount < numberOfPages - 1;
};

Note also that we're effectively doing a print-screen in this example, by passing the LayoutRoot in as the PageVisual to be printed. We'll discuss PageVisual in detail in a moment.

You can also allow the user to cancel printing by setting HasMorePages to false when he hits a cancel button. Doing so will terminate printing after the current page. To do that, you'll need to set a flag in your class and have your code in the print method check for this flag. Additionally, if you know the user has hit cancel before you set the PageVisual, you can both skip setting the PageVisual and set HasMorePages to false to avoid printing the current page and any subsequent pages.

The PageVisual property is the property you use to assign the root element of your page. Think of your root element like LayoutRoot on a typical Silverlight page. This will usually be a panel of some sort, but any UIElement will work.

Before assigning the element to the PageVisual property, you need to ensure that it has all of its children in place. When PageVisual is set, it's then measured and laid out. Since it's not part of the proper Silverlight visual tree, adding elements to the visual doesn't cause an automatic measure and layout pass (see chapter 6 for more information on measuring and layout). You can either manually force a measure and layout, or simply populate the visual completely prior to assigning it to the PageVisual property.

Figure 19.3. The result of assigning the page visual prior to adding child elements to a part of the visual. Layout doesn't happen automatically, so all the elements are stacked on top of each other.

Figure 19.3 shows the result of adding child elements after assigning the PageVisual.

When assigning the PageVisual, keep in mind that any content outside the rectangle defined by the PrintableArea will be clipped. If you need to fit more content on the page, you can apply a scale transform (see chapter 6) to shrink the content down by a ratio that will fit it all on-page.

We'll cover more on setting the PageVisual when we look at some specific printing use cases in sections 19.2 and 19.3.

Once the PageVisual is set and the PrintPage event returns, Silverlight prepares the page for printing by first calling Measure and Arrange (the layout pass described in chapter 6), and rasterizing it to a single bitmap representing the page.

Continuing in the web project, it's time to create the service. The first step is to create a folder named Services and into it add a new Silverlight Enabled WCF Service. Figure 19.6 shows the Add New Item dialog with the correct template selected and named.

Figure 19.6. Adding a Silverlight-enabled WCF Service to the web project

For this demo, we're only interested in read-only data, so we're going to create a basic service method that returns data from the Adventure Works entity model. We won't support create, update, or delete options. If you're interested in options for that functionality, read chapter 17 on WCF RIA Services.

We'll implement the service methods soon. Before we can do that, we need to create the EmployeeReportItem class.

The EmployeeReportItem class represents a single row of data for our report. We could simply send down the complete entities from the model, but that would be wasteful and perhaps even confusing. Instead, we'll create a denormalized entity that contains properties from both the Employee and the Contact classes.

In the Services folder of the web project, create a new class named EmployeeReportItem. Listing 19.7 shows the implementation of this class.

public class EmployeeReportItem
{
    public int EmployeeID { get; set; }
    public string FirstName { get; set; }
    public string LastName { get; set; }
    public string Title { get; set; }
    public string EmailAddress { get; set; }
    public string Phone { get; set; }
    public DateTime HireDate { get; set; }
}

Note that since we're using .NET 4 on the server, we don't need to include DataContract and DataMember attributes in the class. WCF will serialize all public members by default.

Once the EmployeeReportItem class is in place, we can use it from our service.

The last step on the server-side of the project is to add the implementation of the GetEmployeeReportData method of the service. This implementation will join the two entities and pull out fields from them to create EmployeeReportItem instances. Those instances will then be returned to the caller, our Silverlight client in this case. Listing 19.8 lists the code required in the service.

Example 19.8. The GetEmployees method of the AdventureWorksService class

The service pulls information from the AdventureWorks database, using LINQ to both limit the number of items returned to a reasonable number (100) as well as merge the entities to create a single EmployeeReportItem for each row of data.

The final required step before we get into the report itself is to add a reference to the WCF service. First build the solution and ensure that there are no errors. Then, right-click the Silverlight project and choose Add Service Reference.

In the dialog, click Discover to find the services in your solution. If successful, you'll see something like figure 19.7.

In the namespace area, enter the name Services. On the Silverlight client, that will be the namespace (under our root namespace) into which the service client proxy and the EmployeeReportItem class will be generated.

Before we move into printing, let's add one last step: testing. This is optional, but I recommend doing it to ensure that all the other bits are working correctly.

In the code-behind for the main page of your project, add the code shown in listing 19.9. Be sure to right-click AdventureWorksServiceClient and choose Resolve (or hit Alt-Shift-F10) to automatically add the correct using statement to the code file. public MainPage()

Figure 19.7. Adding a service reference from our Silverlight project to the WCF Service in the web project

{
  InitializeComponent();

  Loaded += new RoutedEventHandler(MainPage_Loaded);
}

void MainPage_Loaded(object sender, RoutedEventArgs e)
{
  var client = new AdventureWorksServiceClient();

  client.GetEmployeeReportDataCompleted += (s, ea) =>
    {
      if (ea.Result != null)
      {
        foreach (EmployeeReportItem item in ea.Result)
        {
          Debug.WriteLine(item.LastName + ", " + item.FirstName);
        }
      }
    };
  client.GetEmployeeReportDataAsync();
}

When you run the project, take a look at your Output window and see if it displays 100 names. If it does, you're good. If not, debug any error you receive and try again. Once it's working, you're ready to build the report, starting with the line items. Be sure to remove the test code from the project.

The first step is to create, in the Silverlight project, a class named EmployeeReport. Into that class, we'll add code to call the service and load the data. The code to load the data will be similar to the test code in listing 19.9. Listing 19.10 shows the class with a LoadData method and the shell of the Print method.

Example 19.10. The EmployeeReport class

I chose to derive from FrameworkElement for two reasons:

For more on FrameworkElement, see chapter 6.

Listing 19.10 forms the shell of our new report class. Because we'll use it in XAML, in addition to deriving from FrameworkElement, I needed to include a default constructor. It's an empty constructor, but its presence means that it can be instantiated in XAML. Additionally, as we need to support a user-initiated print process, I raise a DataLoaded event when the data is loaded. The UI can then capture that and allow the user to click a button to perform the printing.

Now that the class has been created, we'll add support for the first template: the item template.

The next step is to add a dependency property for the item template used to format items on the report. The DependencyProperty will hold a DataTemplate containing visuals and binding statements for the items rows. Listing 19.11 shows the code you'll need to add to the EmployeeReport class.

public DataTemplate ItemTemplate
{
  get { return (DataTemplate)GetValue(ItemTemplateProperty); }
  set { SetValue(ItemTemplateProperty, value); }
}

public static readonly DependencyProperty ItemTemplateProperty =

DependencyProperty.Register("ItemTemplate",
typeof(DataTemplate), typeof(EmployeeReport),
new PropertyMetadata(null));

We'll have a few more dependency properties to add before we're through. Before we do that, let's crack open the MainPage XAML and add a reference to the EmployeeReport type and flesh out the data template for the item rows.

Listing 19.12 shows the MainPage XAML file with a reference to the local namespace, and an instance of the report with an appropriate yet simple data template. I've also added a Print button (with a click handler in the code-behind) to provide a way to print the report.

<local:EmployeeReport x:Name="Report">
  <local:EmployeeReport.ItemTemplate>
    <DataTemplate>
      <Grid>
        <Grid.ColumnDefinitions>
          <ColumnDefinition Width="40" />
          <ColumnDefinition Width="180" />
          <ColumnDefinition Width="180" />
          <ColumnDefinition Width="210" />
          <ColumnDefinition Width="100" />
          <ColumnDefinition Width="70" />
        </Grid.ColumnDefinitions>

        <TextBlock Grid.Column="0"
                   Text="{Binding EmployeeID}" />
        <StackPanel Grid.Column="1" Orientation="Horizontal">
          <TextBlock Text="{Binding LastName}" />
          <TextBlock Text=", " />
          <TextBlock Text="{Binding FirstName}" />
        </StackPanel>

        <TextBlock Grid.Column="2"
                   Text="{Binding Title}" />

        <TextBlock Grid.Column="3"
                   Text="{Binding EmailAddress}" />

        <TextBlock Grid.Column="4"
                   Text="{Binding Phone}" />

        <TextBlock Grid.Column="5"
                   Text="{Binding HireDate, StringFormat='{}{0:d}'}" />
      </Grid>
    </DataTemplate>
  </local:EmployeeReport.ItemTemplate>
</local:EmployeeReport>

The local namespace is mapped to the project the code and markup reside within. The ItemTemplate contains a DataTemplate that has a grid column for each column displayed on the report. Each column contains one or more fields bound to the properties of the EmployeeReportItem class. The EmployeeReport element itself resides in the LayoutRoot grid, left out of the listing for space considerations. Also in the LayoutRoot grid is the button previously mentioned:

<Button x:Name="Print" Content="Print" Width="100" Height="30"
        IsEnabled="False"
        Click="Print_Click"/>

Note that the button isn't enabled by default. We'll enable it once the data is loaded from the service. The code to run the report can't be included in the service return event handler, because (in normal trust applications) it must be run from a user-initiated event.

Listing 19.13 shows the code-behind with the code to load the report data and handle the print report button click.

Example 19.13. Code-behind for MainPage

With the item template in place, and our print button wired up, we'll turn our eyes back to the PrintDocument class and the PrintPage event.

The EmployeeReport class currently has a Print method that does nothing. We'll flesh that out a little more to include the usual trifecta of print event handlers, as shown in listing 19.14.

Example 19.14. The three printing event handlers, wired and ready to go

From this point forward, the majority of the code will go into the PrintPage method. For space considerations, I won't show the other event handlers or the Internal-PrintReport function itself.

When I was in college, they made me learn COBOL. Not just any old COBOL, but COBOL on an unforgiving editor on a VAX/VMS computer. If you've never written in COBOL, give it a try—it'll make you appreciate how little typing you need to get things done in C#. Perhaps my interest in curly-brace languages like C# is actually the result of the trauma I sustained in that class.

Anyway, I digress. One thing that the COBOL class did teach was how to build reports from code. That's one skill that I've been able to use in most technologies since. Up until now, though, I hadn't been able to use that in Silverlight. Luckily, that's about to change.

Normally when you process a bunch of rows of data, you'd use a LINQ statement or a for each loop. Neither approach will work particularly well here, as we need to keep a pointer to our position in the data while allowing Silverlight to raise separate events for each page. Though we could use a simple for next loop and an index that we keep track of externally, this is the type of scenario just built for IEnumerator<T>.

In listing 19.16, you can see the enumerator declared inside the Print method. This will be used to keep track of our current position in the report data. In the BeginPrint event handler, I reset the enumerator. Doing so allows Print to be called multiple times on the same data, without running into an enumerator problem.

The enumerator approach is similar to what you might use in COBOL or in recordset/rowset processing in another language, where there's the concept of a "current" record as opposed to an external loop index.

In listing 19.15, I first create a StackPanel that will be used to hold the rows of data. I then move through each row of data, instantiate the template, and add the resulting element to the panel. Finally, the panel is set as the page visual, ready for Silverlight to print.

Example 19.15. Enumerating and printing each row of data

The code in listing 19.15 includes the majority of the important logic required to print a report. It first creates a StackPanel used to hold the content. It then loops through the line items, creating a template-based element to be the row's contents, and then setting the data context of that element to be the row data itself. It then measures the element, providing it the bounds of the page, and finally adds it to the stack panel. Once all elements have been created, the page visual is set to the stack panel and the "more pages" flag is set to false.

In setting HasMorePages to false and not dealing with page breaks, the code in listing 19.15 blindly prints, ignoring the end of the page. If this were old traditional printing, green-bar fan-fold paper would be flying off the printer faster than we could catch it, with printing on the seams and everywhere else. Silverlight will clip this, of course, so the result will be only a single page that doesn't overrun its boundaries. Figure 19.8 shows the top of the report page for reference, as it appears when using the XPS document print driver.

Figure 19.8. The top portion of the report, shown in the XPS viewer

A short single page is nice, but losing data off the bottom isn't. What we really want is to support multiple pages and wrap contents on to those subsequent pages.