|
J2ComponentPrinter
Overview
J2ComponentPrinter is a Java 2 component for printing the contents of any Java Component or Component subclass. Its general-purpose pagination capabilities make it appropriate for printing larger, multi-page Components, including many third-party Components, as well as Containers of Components, Images, and arbitrary diagrams and figures drawn with regular Java Graphics (or Graphics2D) method calls in a paint method. J2ComponentPrinter can print the Component as a Java Pageable or as a Flowable, so that it may be used with J2FlowPrinter as part of a series of Flowables printed back-to-back.
J2ComponentPrinter Pagination
J2ComponentPrinter supports four pagination modes, which can be idependently specified in the horizontal and vertical directions. The four pagination modes supported by J2ComponentPrinter are:
SHRINK_TO_FIT (the default for horizontal pagination) means shrink the Component to fit within a single page width and/or height.. If printing begins on a partial page, then skip to the next page if the available space is less than getMaximumPaginationGap() percent (default 20%) of the full page width and/or height.
TILE means print the Component across multiple horizontal and/or vertical pages without scaling by breaking the Component as necessary on pixel boundaries (rather than anything to do with the Component content). If beginning on a partial page, the value of getMaximumPaginationGap() determines when to start on a new page.
BREAK_ON_COMPONENTS means if the Compoennt is used as a Container, then examine its contained Components and find the maximum horizontal and/or vertical boundaries where page break(s) can be inserted without slicing through any Components. Only the first level of contained Components is examined, so the contents of any nested Containers will be kept together on the same page (unless larger than a page, in which case it will be sliced (like TILE) as needed on pixel boundaries). If beginning on a partial page, the value of getMaximumPaginationGap() determines when to start on a new page.
BREAK_ON_COLOR (the default for vertical pagination) means analyze the Component and determine the bottomost (for vertical pagination) or rightmost (for horizontal pagination) boundary that fits the remaining space on the page and whose pixel color values most closely match the specified (horizontal or vertical) break color. For example, break on Color.white can be used for paginating JTextPane, JTree, JList, and many third-party Components. Or, break on table.getGridColor() can be used for printing tables such as JTable (though J2TablePrinter also supports BREAK_ON_COLOR and, unlike J2ComponentPrinter, supports features such as column and header replication, subarea printing, and the like). If beginning on a partial page, the value of getMaximumPaginationGap() determines when to start on a new page. NOTE: The image color analsysis underlying BREAK_ON_COLOR mode can be slow for large Components. See the methods setAutomaticRecalculation(boolean) and breakOnColorIncrement(int) for ways to optimize these calculations.
J2CompoentPrinter is similar to J2PanelPrinter in many ways, but is more general and can be used in place of J2PanelPrinter for most purposes. The TILE and BREAK_ON_COMPONENTS modes are the same in J2ComponentPrinter and J2PanelPrinter, except that with J2ComponentPrinter you can invoke these modes independently in the horizontal and vertical directions. Likewise, the SHRINK_TO_FIT mode of J2ComponentPrinter can be invoked independently in the horizontal and vertical directions and also honors the getMaximumPaginationGap() concept, whereas J2PanelPrinter has a special rule governing when to skip to a new page. The BREAK_ON_COLOR mode of J2ComponentPrinter has no counterpart in J2PanelPrinter and makes J2ComponentPrinter capable of paginating a broader range of components effectively.
J2ComponentPrinter will print the Component either left, right, or center justified horizontally or top, bottom, or center justified vertically. You can specify whether to use a white background when printing the Component, and/or whether to draw an outside line around the Component. J2ComponentPrinter prints the Component "WYSIWYG", so that the layout and relative size of the Component and all of its contents will be printed exactly as defined.
Programming
You will find it useful to begin your program with:
import com.wildcrest.j2printerworks.*;
rather than spell out the full package name for all J2PrinterWorks classes.
J2ComponentPrinter can instantiated with a zero-argument constructor:
J2ComponentPrinter component Printer = new J2ComponentPrinter();
This creates a J2ComponentPrinter object and initializes all values to their defaults (see the J2ComponentPrinter Javadoc documentation). To specify the JPanel to be printed by J2ComponentPrinter, you can use the J2ComponentPrinter method setComponent:
componentPrinter.setComponent(yourComponent);
At this point componentPrinter is a Pageable (or Flowable) suitable for printing by J2Printer.
Alternatively, you can use the single-argument J2ComponentPrinter constructor:
J2ComponentPrinter componentPrinter = new J2ComponentPrinter(yourComponent);
In addition, J2ComponentPrinter provides a convenience constructor for handling Images:
J2ComponentPrinter imagePrinter = new J2ComponentPrinter(yourImage);
There is also a corresponding convenience method for specifying an Image:
panelPrinter.setImage(yourImage);
The following is a simple but complete Java program (J2ComponentPrinterSimplestTest.java) that displays and prints a JPanel using J2ComponentPrinter:
»
|
