|
J2PanelPrinter
Overview
J2PanelPrinter is a Java 2 component for printing the contents of any JPanel or JPanel subclass. J2PanelPrinter can also be used for smaller (<1 page) Components, Containers wtth smaller Components, and Images (for larger, multi-page Components, we recommend you use J2ComponentPrinter). For example, the JPanel may be used for printing diagrams and figures drawn with regular Java Graphics (or Graphics2D) method calls, where these appear in the paint method of the JPanel. J2PanelPrinter has special methods and constructors to make it easy to print an individual Component (or JComponent) or an individual Image without placing these inside a JPanel.
J2PanelPrinter can print the JPanel 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. J2PanelPrinter is frequently used for JPanel instances containing small pieces of content that fit within a printed page. These include images, titles, captions, legends, etc. intermixed with other J2PrinterWorks printing components in a J2FlowPrinter container.
J2PanelPrinter Pagination
J2PanelPrinter is often used for printing smaller Components such a JLabels and JPanels containing smaller Components less than one page in size such as Images and Graphics-drawn diagrams. However, J2PanelPrinter can also be used for printing JPanel instances containing larger pieces of content that may span multiple pages, provided they can be paginated effectively using one of the following four pagination modes supported by J2PanelPrinter that control where page breaks will occur:
- SHRINK_TO_FIT (the default) means shrink the JPanel, Component, or Image to fit within remaining space on the current page. But if this causes the JPanel, Component, or Image to be smaller than it would be to shrink-to-fit on the next full page, then skip to the top of the next page and shrink to fit in order to print it there. Scaling is performed by the same amount in both X and Y (the aspect ratio is preserved). The value of getMaximumPaginationGap() is ignored in this mode.
- SHRINK_TO_WIDTH means shrink the JPanel, Component, or Image to fit within the width of the current page, and paginate the scaled result across multiple vertical pages, breaking as necessary on pixel boundaries to print the entire JPanel, Component, or Image. Scaling is performed by the same amount in both X and Y (the aspect ratio is preserved). If beginning on a partial page, then skip to the top of the next page if the available space is less than getMaximumPaginationGap() percent of the full page height (default 20%).
- TILE means print the JPanel, Component, or Image across multiple horizontal and/or vertical pages without scaling by breaking the JPanel, Component, or Image as necessary on pixel boundaries (rather than anything to do with the 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 JPanel is used as a Container, then examine its contained Components and find the maximum horizontal and 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 (JPanel, JTextPane, etc.) 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.
Though J2PanelPrinter can print Java Components such as JTextPane, JTable, JTree, or JList components, typically it only makes sense if these components are small, as J2PanelPrinter can only break on component boundaries or pixel boundaries and will not paginate larger versions of these components on meaningful content (e.g., line, row, column, node, item) boundaries. Instead, you should use J2TablePrinter for JTable pagination on table row/column boundaries, J2TextPrinter for JTextPane pagination on text line boundaries, J2TreePrinter for JTree pagination on tree node boundaries, and J2ListPrinter for JList pagination on list item boundaries. Alternatively, you can use J2ComponentPrinter which can also perform reasonably effective paginatation of these components using BREAK_ON_COLOR mode, breaking on boundaries of a given color such as "white space". Since J2ComponentPrinter also supports SHRINK_TO_FIT, TILE, and BREAK_ON_COMPONENTS pagination modes, it can be used in place of J2PanelPrinter for most all purposes.
J2PanelPrinter will print the JPanel 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 JPanel, and/or whether to draw an outside line around the JPanel. J2PanelPrinter prints the JPanel "WYSIWYG", so that the layout and relative size of the JPanel 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.
J2PanelPrinter can instantiated with a zero-argument constructor:
J2PanelPrinter panelPrinter = new J2panelPrinter();
This creates a J2PanelPrinter object and initializes all values to their defaults (see the J2PanelPrinter Javadoc documentation). To specify the JPanel to be printed by J2PanelPrinter, you can use the J2PanelPrinter method setPanel:
panelPrinter.setPanel(yourJPanel);
At this point panelPrinter is a Pageable suitable for printing by J2Printer.
Alternatively, you can use the single-argument J2PanelPrinter constructor:
J2PanelPrinter panelPrinter = new J2PanelPrinter(yourJPanel);
In addition, J2PanelPrinter provides two convenience constructors for handling the common special cases of single Images and single Components (like JLabel, JTextArea, etc.):
J2PanelPrinter imagePrinter = new J2PanelPrinter(yourImage);
J2PanelPrinter componentPrinter = new J2PanelPrinter(yourComponent);
There are also two corresponding convenience methods for setting these values:
panelPrinter.setImage(yourImage);
panelPrinter.setComponent(yourComponent);
The following is a simple but complete Java program (J2PanelPrinterSimplestTest.java) that displays and prints a JPanel using J2PanelPrinter:
import java.awt.*;
import javax.swing.*;
import com.wildcrest.j2printerworks.*;
class J2PanelPrinterSimplestTest {
static public void main(String args[]){
JPanel panel = new JPanel();
JLabel label = new JLabel();
label.setFont(new Font("Serif",Font.PLAIN,14));
label.setText("<html>This is an example of <i>a JLabel</i><br>"
+ "displayed inside <u>a JPanel</u> and<br>"
+ "printed using <b>J2PrinterWorks</b></html>");
panel.add(label);
panel.setPreferredSize(new Dimension(200,75);
JFrame frame = new JFrame("J2PanelPrinter test");
frame.getContentPane().add(panel);
frame.pack();
frame.setVisible(true);
J2Printer printer = new J2Printer();
printer.setSeparatePrintThread(false);
J2PanelPrinter panelPrinter = new J2PanelPrinter(panel);
printer.addPageable(panelPrinter);
printer.print();
System.exit(0);
}
}
»
|
