Introduction
Printing a document programmatically is quite involved. Using the ReportPrinting library presented here, youll be able to print reports of many sections, with very little code.
Figure 1 - Part of a sample report
The reports are comprised of text sections (such as the title "Birthdays", and the other paragraphs), grids of data from a database (more specifically, from a DataView object) and many other primitives. Since the initial version of this document, I've already exteneded the framework to handle images (from .Net Image class), boxes (similar to the CSS box implementation) and more are coming every week.
Two important classes are introduced in this article.
- ReportDocument - a class that inherits from PrintDocument and greatly assists in printing tabular reports consisting of data from a DataTable.
- PrintControl - a control that simplifies the process of guiding the user through the printing process.
The section on the ReportDocument includes many helper classes to define sections, columns, and text styles. The PrintControl section includes a brief description of some of the dialogs used in the printing process.
Report Document Classes
There are several classes introduced into the ReportPrinting namespace. They work together for the printing of the above report (in addition to all the .NET Framework base classes that are used). Here is a quasi-UML diagram that shows the relationship between these classes. An open triangle is generalization (i.e. it points to the super-class in the inheritance chain). The black diamonds are composite (i.e. shows that one class instantiates members of another class). The dashed-lines are dependency (i.e. it uses the class).
(note 18-Sep-03, ReportSectionText is now SectionText, ReportSectionData is now SectionTable)
Figure 2 - UML diagram of classes
ReportDocument
ReportDocument extends from PrintDocument and is customized for printing reports from one or more tables of data. A ReportDocument object is the top-level container for all the sections that make up the report. (This consists of a header, body, and footer.)
The ReportDocument's main job is printing, which occurs when the Print() method is called of the base class. The Print() method iterates through all the ReportSections making up the document, printing each one.
The strategy design pattern is employed for formatting the report. An object implementing IReportMaker may be associated with the ReportDocument. This IReportMaker object is application specific and knows how to create a report based on application state and user settings. This object would be responsible for creating sections, associating DataViews, and applying any required styles through use of the TextStyle class. It will generally use the ReportBuilder class to assist with the complexity of building a report.
ReportSection
ReportSection is an abstract class that represents a printable section of a report. There are several subclasses of ReportSection, including ReportSectionText (which represents a string of text) and ReportSectionData (which represents a printable DataView). There are also container sections (which derive from SectionContainer class, which in turn derives from ReportSection). These containers hold child ReportSection objects (also known as subsections) to be printed. Lets take a quick look at how this might work with an example.
In the sample report shown at the top of this article, there is a paragraph of text followed by a table of data. (There are actually two paragraphs of text, one of which is a heading. Plus there is a page header, but well ignore all that for now.) We would create a ReportSectionText object to print the paragraph of text and a ReportSectionData object to print the table of data. To add both of these ReportSections to the ReportDocument, we must create a container. We would create a LinearSections container to hold these two sections. This container is then made the body of the ReportDocument. When the document is printed, the section container will first print the ReportSectionText, and then below that, it will print the ReportSectionData. Simply simply printing each section below the preceding one will result in the finished report. But there are many other ways to set up these classes.
SectionContainer
This abstract class defines a container of sections. There are two types provided with the framework: LinearSections and LayeredSections.
LinearSections
The LinearSections class is a subclass of SectionContainer, which is a subclass of ReportSection. Therefore, the LinearSections can be thought of as "a printable section of a report." However, it is also a container of one or more sections.
As its name implies, it lays sections out linearly -- that is, in a row or in a column. A property named Direction specifies if this container will layout sections going down the page (typical) or across the page (not as typical).
(see
Layouts for more information about how this class works.)LayeredSections
The LayeredSections class is also a subclass of SectionContainer, which is a subclass of ReportSection. Therefore, the LayeredSections can be thought of as "a printable section of a report." It is also a container of one or more sections.
The child sections of a LayeredSections object are all painted on top of one another (creating layers). The first section added to a LayeredSections object is the bottom layer. Subsequent ReportSection objects added to the LayeredSections object will be shown on top of each other.
(see Layouts for more information about how this class works.)
SectionText
The SectionText prints a string to the page. Two public properties are used to setup this section. Text is used to specify the string to print. TextStyle, described later, sets the font, color, alignment and other properties for the how the text is printed.
It is interesting to note that the string specified for this section can be just one word, or many paragraphs of text.
SectionTable
The SectionTable prints a table of data. It uses a DataView object (from the .Net System.Data namespace) as the source of data. It then uses a series of ReportDataColumns to provide the fomatting details. These ReportDataColumns are similar to the DataGridColumnStyle class. Table wide formatting includes setting Header, Row, and Alternating row TextStyle's, along with setting the width and margins.
ReportDataColumn
The ReportDataColumn provides the necessary information for formatting data for a column of a report. For every column to be presented within a section of data, a new ReportDataColumn object is instantiated and added to the ReportSection. At a minimum, each column describes a source field from the DataSource (that is, a column name from the DataView) and a maximum width on the page.
The ReportDataColumn can be setup with its own unique TextStyle for both header and normal rows. Therefore, each column's data can be formatted differently (e.g. an important column could be bold and red). The TextStyle is also used to set the horizontal alignment (justification).
TextStyle
The TextStyle class allows styles and fonts to be added to text selectively, allowing default styles to be used when not explicitly set. All styles (except for the static TextStyle.Normal) have another style as their "default" style. Until a property is set (like bold, underline, size, font family, etc), a TextStyle object always uses the corresponding value from its default (or parent) style.
For example, a new style can be defined using Normal as its default, but setting bold.
TextStyle paragraphStyle = new TextStyle(TextStyle.Normal); paragraphStyle.Bold = true;
It will have all the same properties as TextStyle.Normal, except it will be bold. A later change to Normal (such as below) will have the effect of increasing the size of both styles (Normal and paragraphStyle).
TextStyle.Normal.Size += 1.0f
ReportBuilder
ReportBuilder assists with the building of a report. This class is the main interface between your code and the ReportPrinting library. In many cases, you will never explicitly create any of the above objects. Instead, the ReportBuilder will create them for you.
To instantiate a ReportBuilder, you must provide the ReportDocument to be built. Then you can call its various Add methods to sequentially add pieces to a report document.
Example:
The following example shows the creation of a report using the ReportBuilder. The following methods would be part of a class that implements IReportMaker (this is from example1 in the sample project).
private DataView GetDataView()
{
DataTable dt = new DataTable("People");
dt.Columns.Add("FirstName", typeof(string));
dt.Columns.Add("LastName", typeof(string));
dt.Columns.Add("Birthdate", typeof(DateTime));
dt.Rows.Add(new Object[] {"Theodore", "Roosevelt", new DateTime(1858, 11, 27)});
dt.Rows.Add(new Object[] {"Winston ", "Churchill", new DateTime(1874, 11, 30)});
dt.Rows.Add(new Object[] {"Pablo", "Picasso", new DateTime(1881, 10, 25)});
dt.Rows.Add(new Object[] {"Charlie", "Chaplin", new DateTime(1889, 4, 16)});
dt.Rows.Add(new Object[] {"Steven", "Spielberg", new DateTime(1946, 12, 18)});
dt.Rows.Add(new Object[] {"Bart", "Simpson", new DateTime(1987, 4, 19)});
return dt.DefaultView;
}
public void MakeDocument(ReportDocument reportDocument)
{
// Clear the document
reportDocument.ClearSections();
// create a data table and a default view from it.
DataView dataView = this.GetDataView();
// create a builder to help with putting the table together.
ReportBuilder builder = new ReportBuilder(reportDocument);
// Add a simple page header and footer that is the same on all pages.
builder.AddPageHeader("Birthdays Report", String.Empty, "page %p");
builder.AddPageFooter(String.Empty, DateTime.Now.ToLongDateString(), String.Empty);
builder.StartLinearLayout(Direction.Vertical);
// Add text sections
builder.AddTextSection("Birthdays", TextStyle.Heading1);
builder.AddTextSection("The following are various birthdays of people who "
+ "are considered important in history.");
// Add a data section, then add columns
builder.AddDataSection(dataView, true);
builder.AddColumn ("LastName", "Last Name", 1.5f, false, false);
builder.AddColumn ("FirstName", "First Name", 1.5f, false, false);
builder.AddColumn ("Birthdate", "Birthdate", 3.0f, false, false);
// Set the format expression to this string.
builder.CurrentColumn.FormatExpression = "{0:D}";
builder.FinishLinearLayout();
}
IReportMaker
IReportMaker is an interface used to implement the strategy design pattern. An object that implements IReportMaker can be added to a ReportDocument. When the document is about to be printed, it automatically calls the single method MakeDocument(). The above example shows an implementation of that method to print a one-page report.
For example, you could have an application that can print either detailed reports or a shorter overview. The logic to make each of these reports would be located in separate classes. Each class would implementing the IReportMaker interface. Your print dialog could have a "Print What" combo box to allow the user to select the type of report, and use the selection in the combo box to associate the correct implementation of IReportMaker with the ReportDocument.
Print Dialogs
The print dialog guides the user through the printing process. Most applications have some options that affect what is printed and how it is printed. Most windows applications customize the standard PrintDialog, adding an additional section at the bottom for various options. There are articles on extending the standard PrintDialog using MFC, but Ive yet to find anything for .NET. If someone creates a .NET control that looks like a standard PrintDialog and could easily be added to new Forms to create a customized PrintDialog or knows of some other way to extend the functionality of the .NET PrintDialog, please let me know.
PrintControl
To make printing easy for my applications, I created this very basic control that can be dropped onto any form. It gives the user options to setup, preview, submit (ok) or cancel. Providing a preview button and a page setup button on a print dialog are not standard in the windows interface, but I wish they were. So this control provides that functionality to your print dialog. Note, you can still provide access via a File menu (File | Print Preview, File | Page Setup).
Figure 3 - PrintControl user control
The control uses the following dialogs associated with printing:
- PrintPreviewDialog
- PageSetupDialog
- PrintDialog
To use the print control, place it on a form. Set the Document property to a valid PrintDocument. (it doesnt have to just be the ReportDocument described earlier). Thats it!
You can customize a few things with the following properties:
- ShowStatusDialog - The progress of the print job is shown in a status dialog. Default is true.
- PrintInBackground - Indicates that printing should be done in the background. Default is true.
- Printing - This event is raised prior to printing. It allows user code to setup for printing. (This is useful for dumping data from the GUI to a helper class, for instance).
Print Dialog with PrintControl
A sample form with a PrintControl is shown below. This dialog allows a user to select tables to print from the Northwind sample database.
Figure 4 - A dialog to prompt user for print settings and give them a chance to preview and setup the page.
Revision History
1-Sep-03 : Original article posted.
18-Sep-03 : Names of some classes changed.
