The printing framework

The generic printing framework is designed and implemented to meet the printing needs of Rogue Wave® JViews packages but you can also use it to make other printing applications. Based on the Model-View-Controller (MVC) architecture, the printing framework consists of the following features:

The Document Model classes

The framework provides a set of classes that you can use to create a printable document. You can use the built-in document class and page class to easily create the document you want to print.

Printing user interface components

The printing framework provides user interface components, such as preview frame and toolbar, that allow you to preview the document you have created. It also provides customizable dialog boxes for setting page properties such as paper size, orientation, header and footers.

The PrintingController class

The printing controller is a high-level class that manages the document to print and the preview frame. You can use it to invoke the Print dialog box, or the Page Setup dialog box, to preview the document, and to send the document to the selected printer.

The process for printing multiple pages is as follows:

1. Create and fill an IlvPrintableDocument object by using the document model classes.

2. Create an IlvPrintingController object for the IlvPrintableDocument object you created. Then you can call its methods to preview and print the IlvPrintableDocument.

The Document Model classes

The document model provides a structure for defining a multipage document to be printed. The document model allows you to concentrate your efforts on creating your printable document without worrying about how the document is previewed and printed. The printing framework previews and prints the document for you.

Print document model shows the relationship between the main classes in the document model.

Print document model

The PrintableDocument class

The IlvPrintableDocument class is the top-level class of the document model. It is designed as a page holder to which you can add pages defined by the IlvPage class.

There are two ways to fill a document:

Simply create pages ( IlvPage class) and add them to the document using the addPage and removePage methods.

Associate an IlvFlow object with the document.

The IlvFlow object allows you to add styled text to a document; if you decide to use an IlvFlow object, it will create and manage the pages of the document for you depending on the text, the alignments, and the styling properties that you specify in the IlvFlow object.

Later in this topic you will see how to associate an IlvFlow object with a document.

NOTE Some Rogue Wave® JViews packages provide subclasses of the IlvPrintableDocument class that manage the pages for you. For example, Rogue Wave JViews Gantt provides a subclass that can automatically create its pages to display a chart in multiple pages. For more information see the Rogue Wave JViews Gantt documentation.

The Page class

An IlvPage object represents a physical page to be printed. It must be added to a printable document so that the page can be printed by a printer, or previewed by the preview framework. The IlvPage is implemented as a collection of printable objects. It has the addPrintableObject and removePrintableObject methods, which you can use to manage the printable objects in a page.

Once a page is added to a printable document, you can get the index of the page in that document by calling the getPageIndex method. The index of the page is determined by the order in which it is added. The getDocument method allows you to know the owner of the printable page.

To know the page format of the page, you can call the getPageFormat method. By default, this method returns the page format of the document.

The Printable class

The Printable objects are the basic elements in the printable document model. They represent concrete objects such as label, line, and rectangle printed on a page. Therefore, printable objects must be added to pages so that they can be previewed and printed.

A printable object class must implement the java.awt.print.Printable interface. In other words, you have to write the print() method of this interface if you want to implement a new printable object. See Java print package and printing API and the JDK™ documentation for more information on this interface.

The definition of the print() method is as follows:

public int print(Graphics graphics, PageFormat pageFormat, int pageIndex)

throws PrinterException

To print, you need to call the methods of the specified Graphics object. You are responsible for setting the correct clip and transformation to position the printing results as wanted.

Some commonly used printable objects are provided as built-in classes in the package.

Classes for common printable objects
Class	Purpose
IlvPrintableLine	To print a line.
IlvPrintableRectangle	To print a rectangle.
IlvPrintableLabel	To print a label.
IlvPrintableTable	To print a portion of the JTable.
IlvPrintableTableHeader	To print a portion of the JTableHeader.

NOTE Some Rogue Wave® JViews packages provide additional subclasses of IlvPrintableObject. For example, Rogue Wave JViews Gantt provides the subclass IlvPrintableTimeScale to print its time scale. For more information, see the Rogue Wave JViews Gantt documentation.

The header and footer classes

To manage page headers and footers, the printing framework also contains two additional subclasses of IlvPrintableObject: IlvHeader and IlvFooter. Although these two classes are subclasses of the IlvPrintableObject, you do not add them to the page like other printable objects. The header and footer are common to all pages of a document, and thus are set on the instance of the IlvDocument class.

Here are the methods of the class IlvPrintableDocument to set a header or a footer:

public void setFooter(IlvFooter footer)

public IlvFooter getFooter()

public void setHeader(IlvHeader header)

public IlvHeader getHeader()

The IlvHeader and IlvFooter classes are very similar. A header or footer is defined by three text sections. Each section can have a specified font.

Here is an example of a header:

Example of a header

Each of the three text sections of a header or footer can contain the text that you specify in the constructor of the object. For the header shown in Example of a header it would be:

new IlvHeader("7/12/02", "Printing demo", "Page 1");

Since the header and footer are defined on the document, you should not specify the page number as in the previous example. The IlvHeader and IlvFooter classes provide a certain number of keys that will be translated to values from the document, when the document is printed.

The list of keys that you can use is as follows:

static String AuthorKey - The key for the author.

static String DateKey - The key for the date.

static String FileKey - The key for the file name.

static String PageKey - The key for the page number.

static String PagesKey - The key for the number of pages in the document.

static String TimeKey - The key for the printing time

To create the header in Example of a header, use the following new statement:

new IlvHeader(IlvHeader.DateKey, "Printing demo", "Page " + IlvHeader.PageKey)

NOTE 	The printing framework provides a page dialog box that also allows you to change the header and footer of a document.

The IlvFlow class for creating a document with styled text

A document can be filled in one of two ways: either you decide to create pages, fill them with IlvPrintableObject instances, and add them to a document, or you create a document that contains styled text. In the second case you use the IlvFlow class.

The IlvFlow class represents a flow of text with styling attributes that constitutes the content of the document to be printed. A document can have only one IlvFlow object, which is created using:

public IlvFlow IlvPrintableDocument.getFlow()

Once the flow is created you can specify its content using the following methods:

void add(String text)

Adds the specified text to the current paragraph.

void add(Image image, int alignment)

Adds the image to the current line of text using the specified alignment on the line.

void add(IlvFlowObject object, int alignment)

Adds the object in the current line of text using the specified alignment on the line.

The IlvFlowObject interface allows you to add virtually any kind of drawing to a flow. Some Rogue Wave® JViews packages provide classes that implement this interface, so that you can add a Rogue Wave JViews Charts component to a flow of text.

You can also control the paragraphs and the pages of the flow using the following methods:

void newLine()

Starts a new paragraph in the flow of text.

void newPage()

Starts a new page in the flow of text.

Each text added in the flow can be styled using the following method:

void setTextStyle(IlvFlow.TextStyle style)

By calling this method, you change the current text style that will be used for the next text added to the flow. The TextStyle object allows you to change the colors (background and foreground color) of the text, the font used, and also the paragraph alignment.

Printing user interface components

The print package provides user interface components for previewing a document and for setting document properties such as the page format, the headers, or the footers.

Print Preview components

When you want to preview a document to print, the following classes are involved.

IlvPrintPreviewPanel - A Swing panel that displays the document to preview.

IlvPrintPreviewDialog - A Swing dialog that contains an IlvPrintPreviewPanel.

Here is an image showing an IlvPrintPreviewDialog containing an IlvPrintPreviewPanel :

Print Preview in Continuous Mode

The Print Preview user interface components can work in two main modes. Print Preview in Continuous Mode shows a Print Preview panel in continuous mode.

In this mode, the preview component displays several pages at once, and you can scroll the pages using the scroll bar. In this mode, you can also change the zoom level using the zoom level combination box.

The second mode is the single page mode. In this mode, you can see only one page at a time, but you can still use the scroll bar to move from page to page.

Print Preview in Single Page Mode

The single page mode also allows you to zoom the page. Using the zoom button (or clicking the view), you can switch from a zoom mode where the page fits the component to the mode where the page is at real size.

In most cases, you do not need to create instances and manage these components by yourself. The high-level class IlvPrintingController allows you to perform most of the printing actions and settings.

Page Setup component

The class IlvDocumentSetupDialog is a dialog box that allows you to edit various parameters of your document such as the page format, the header and the footer.

This dialog box is composed of a JTabbedPane with two tabs: one to edit the page format, and one to edit the header and footer.

Page Setup

This component can be customized for your particular needs. You may add a new tab by using the addTab(java.lang.String, java.awt.Component) method, if you need to edit additional parameters for a specialized class of document.

In most cases, you do not need to create instances and manage the IlvDocumentSetupDialog by yourself. The high-level class IlvPrintingController allows you to perform most of the printing actions and settings.

The PrintingController class

After you create your IlvPrintableDocument, you will have to create an instance of IlvPrintingController, a high-level class that manages the document to print and the preview frame. Then you can perform various actions on the document to be printed:

Call the printDialog method to invoke a dialog box to select a printer, or to specify other printer-related information.

Call the setupDialog method to open the Page Setup dialog box, which allows you to change the page format, the header and footers. You can also click the Setup button while you preview the document.

Call the printPreview method to preview your document.

Call the print method of the print controller to print your document. You can also click the print button while you preview the document.

The printing controller also offers methods that you can overwrite, so that you can customize the Setup dialog, or the Print Preview dialog created by the printing controller.

Creating an IlvDocument with printable objects

This is a simple example to explain how to use the printing framework.

To print the simple example:

1. Create an IlvPrintableDocument object.

2. Add pages to the document.

3. Set header and footer to the document.

4. Implement an IlvPrintableObject object.

5. Create and use the printing controller.

6. Use the user interface components to preview the document you created.

The example code is as follows.

Creating a document with printable objects

IlvPrintableDocument document = new IlvPrintableDocument("A test document");

// Sets a header in the document.

document.setHeader(new IlvHeader(null, "Printing Example", IlvHeader.PageKey));

// Creates the first page.

IlvPage page1 = new IlvPage();

// Prints an oval on the first page.

IlvPrintableObject oval = new IlvPrintableObject() {

/**

* Overrides the <code>print</code> method to print an oval.

* It shows how to implement a <code>PrintableObject</code>.

* @param dst The output <code>Graphics</code> object.

* @param format The page format, which is ignored here.

* @param pageIndex The page index, which is ignored here.

public int print(Graphics dst, PageFormat format, int pageIndex)

throws PrinterException {

dst.drawOval(200, 200, 200, 100);

return Printable.PAGE_EXISTS;

}

};

// Adds this new printable to the page.

page1.addPrintableObject(oval);

// Creates the second page.

IlvPage page2 = new IlvPage();

// Prints a rectangle on the second page.

IlvUnit.Rectangle area = new IlvUnit.Rectangle(5, 5, 10, 10, IlvUnit.CM);

IlvPrintableRectangle rectangle = new IlvPrintableRectangle(area);

page2.addPrintableObject(rectangle);

// Adds the pages to the document.

document.addPage(page1);

document.addPage(page2);

// Creates the print manager.

IlvPrintingController controller = new IlvPrintingController(document);

// Previews the document.

controller.setPreviewMode(IlvPrintPreviewPanel.CONTINUOUS_MODE);

controller.printPreview(JOptionPane.getRootFrame());

Here is what you get on the screen:

Document with printable objects

Creating an IlvDocument with a flow of text

This is an example to explain how to use the printing framework with a text flow.

To print the text flow example:

1. Create an IlvPrintableDocument object.

2. Create the IlvFlow object.

3. Add text and image to the IlvFlow object.

4. Set the text style and paragraph alignment.

5. Create and use the printing controller.

6. Use the user interface components to preview the document you created.

The example code is as follows.

Creating a document with a text flow

// Creates the document.

IlvPrintableDocument document

= new IlvPrintableDocument("A Test Document");

// Gets the flow to add text and images.

IlvFlow flow = document.getFlow();

// Sets the style of text and paragraph alignment

// for the title.

IlvFlow.TextStyle style = new IlvFlow.TextStyle();

style.setFont(new Font("Helvetica", Font.BOLD, 20));

style.setAlignment(IlvFlow.TextStyle.CENTER_ALIGNMENT);

flow.setTextStyle(style);

// Adds the title text.

flow.add("The Printing Framework Document Model");

flow.newLine();

// Sets the style of text for the next paragraph.

style.setAlignment(IlvFlow.TextStyle.LEFT_ALIGNMENT);

style.setFont(new Font("Helvetica", Font.PLAIN, 16));

flow.setTextStyle(style);

flow.newLine();

flow.add("The document model provides a structure to define a multiple-page document to be printed. The document model allows you to concentrate your efforts on creating your printable document without worrying about how the document is previewed and printed. The printing framework previews and prints the document for you.");

flow.newLine();

flow.add("The following figure shows the relationship between the main classes in the document model:");

flow.newLine();

try {

// Loads an image to add.

    Image image = IlvUtil.GetImageFromFile(Class.forName("demos.print.PrintExample"), "model.gif");

// Adds the image to the flow.

flow.add(image, IlvFlow.TOP_ALIGNMENT);

} catch (Exception e) {

}

// Creates the print controller.

IlvPrintingController controller = new IlvPrintingController(document);

// Previews the document.

controller.setPreviewMode(IlvPrintPreviewPanel.CONTINUOUS_MODE);

controller.printPreview(JOptionPane.getRootFrame());

Here is what you get on the screen:

Document with text flow