The printing framework
Describes the printing framework supplied with the JViews Framework, specifically the Document Model classes, and provides examples of its use.
Describes the features of the
JViews Framework printing framework and the process for printing multiple pages.
Describes the Document Model classes with a class diagram.
Describes the PrintableDocument class.
Describes the Page class.
Describes the Printable class for printable objects.
Describes the header and footer classes.
Describes how to fill a document either with printable objects or by creating a flow object.
Describes the UI components for previewing and setting document properties.
Describes how to use the PrintingController class.
Describes how to print a simple example document.
Describes how to print an example document with text.
Features of 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 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.
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 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:
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.
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
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:
2. Add pages to the document.
3. Set header and footer to the document.
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:
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.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
Copyright © 2018, Rogue Wave Software, Inc. All Rights Reserved.