The Document Model

Advanced Features > The Generic Printing Framework > The Printing Framework > The Document Model

The Document Model

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.

Figure 3.3 shows the relationship between the main classes in the document model:

Figure 3.3 Print Document Model

Printable Document

The IlvPrintableDocument 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 document you will see how to associate an IlvFlow object with a document.

Note

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

Page

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. For more information on printable objects, see Printable Object.

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.

Printable Object

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. Here is the definition of the print() method:

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

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

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

Table 3.1 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 ILOG JViews packages provide additional subclasses of IlvPrintableObject. For example, ILOG JViews Gantt provides the subclass IlvPrintableTimeScale to print its time scale. For more information, see the ILOG JViews Gantt documentation.

Headers and Footers

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 as other printable objects. The header and footer are common to all pages of a document, and thus are set on the instance of the IlvDocumentclass.

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 and a footer are defined by three text sections. Each section can have a specified font. Here is an example of a header:

Figure 3.4 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 Figure 3.4 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.

Here is the list of keys that you can use:

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 Figure 3.4, do the following:

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.

IlvFlow Object: Creating a Document with Styled Text

A document can be filled using two exclusive 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 this case you will 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 by using:

public IlvFlow IlvPrintableDocument.getFlow()

Once the flow is created you can specify its content by 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 in a flow. Some ILOG JViews packages provide classes that implement this interface, so that you can add an ILOG JViews Charts component in a flow of text.

You can also control the paragraphs and the pages of the flow by 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.

PREVIOUS NEXT