|
J2ComponentPrinter |
|
J2ComponentPrinter supports four
pagination modes, which can be idependently specified in the horizontal
and vertical directions. The four pagination
modes supported by J2ComponentPrinter are:
getMaximumPaginationGap()
percent (default 20%) of the full page width and/or height.getMaximumPaginationGap()
determines when to
start on a new page. getMaximumPaginationGap()
determines when to start on a new page.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.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.
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();
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:
import java.awt.*;
import javax.swing.*;
import com.wildcrest.j2printerworks.*;
class J2ComponentPrinterSimplestTest {
static public void main(String args[]){
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>"
+ "placed inside a <u>J2ComponentPrinter</u> and<br>"
+ "printed using <b>J2PrinterWorks</b></html>");
label.setPreferredSize(new Dimension(250,75);
JFrame frame = new
JFrame("J2ComponentPrinter
test");
frame.getContentPane().add(label);
frame.pack();
frame.setVisible(true);
J2Printer printer =
new
J2Printer();
printer.setSeparatePrintThread(false);
J2ComponentPrinter
componentPrinter = new J2ComponentPrinter(label);
printer.addPageable(componentPrinter);
printer.print();
System.exit(0);
}
}
Most of the methods of J2ComponentPrinter are set and get methods
for
controlling
its property values. The full list of J2ComponentPrinter methods, what
they
do,
and their default values are given in the J2ComponentPrinter
Javadoc documentation .
Whether J2ComponentPrinter is used as a Pageable or a Flowable, you can control whether the J2ComponentPrinter operates in shrink-to-fit,, tile, break-on-components, or break-on-color mode, whether it is left, right, or center justified horizontally on a page, top, bottom, or center justified within the remaining space on a page, whether to use a white background when printing the JPanel, and whether to draw an outside line around the JPanel.
Horizontal and vertical pagination modes
J2ComponentPrinter has four modes for controlling the horizontal and vertical pagination of the JPanel to be printed, SHRINK_TO_FIT, TILE, BREAK_ON_COMPONENTS, and BREAK_ON_COLOR described above in the section J2ComponentPrinter Pagination. To control the pagination mode of J2ComponentPrinter, use the following methods:
setHorizontalPageRule (int horizontalPageRule)
Sets the
horizontal page
rule for mapping each Component into the printed page.
setVerticalPageRule
(int verticalPageRule)
Sets the
vertical page
rule for mapping each Component into the printed page.
Horizontal and vertical alignment
J2ComponentPrinter will print your Component either left, center, or right justified horizontally on the page between the left and right margins. The default value for horizontal alignment is CENTER.
Similarly, J2ComponentPrinter will print your Component either top, center, or bottom justified vertically on the page between the gap below the header and gap above the footer. The default value for vertical alignment is TOP.
setHorizontalAlignment (int horizontalAlignment)
Sets the
horizontal alignment (LEFT, CENTER, RIGHT) for printing the Component
on
the page.
setVerticalAlignment (int verticalAlignment)
Sets the
vertical
alignment (TOP, CENTER, BOTTOM) for printing the Component on the page.
White background
By default, J2ComponentPrinter will print your Component with the Component background color, which might be the background color of the window in which it is displayed. You can specify whether whether the Component when printed should have a white background using the method:
setWhiteBackground (boolean whiteBackground)
Sets whether to
print the Component with a white background.
Outside line
J2ComponentPrinter lets you control whether to draw a line surrounding the Component and what color this line should be using the following methods:
setOutsideLines (boolean showOutsideLines)
Sets whether to
print outside border lines around Component.
setOutsideLineColor (java.awt.Color outsideLineColor)
Sets Color of
outside border lines.
When J2ComponentPrinter is used as a Pageable, it can have its own ("local") headers & footers (left, center, and right), margins (left, right, top, and bottom), and orientation (portrait & landscape). Headers and footers can be specified as a String or a JLabel, can be different on the first page vs. the rest of the pages of the Pageable, and can include date, time, and page numbering. The methods are the same as the parallel set of methods described in the J2Printer section under "Pageable properties".
If "local" values are not specified for this J2ComponentPrinter instance, the "global" (overall, default) values set using the parallel J2Printer methods will be used. You can force the J2Printer "global" values to be used by calling the J2ComponentPrinter method(s) with the argument J2Printer.GLOBAL.
The Pageable properties of J2ComponentPrinter will be ignored when
the
J2ComponentPrinter is used as a Flowable. This is because in this
case the Pageable
is
the containing J2FlowPrinter, so page properties such as headers,
footers,
margins, and orientation will be controlled by the J2FlowPrinter
Pageable,
not the J2ComponentPrinter used as a Flowable. Note, however,
that
scaling does work for J2ComponentPrinter used as either a Pageable or a
Flowable, that is, the J2ComponentPrinter can appear at its own scale
within an overall J2FlowPrinter sequence.
Fit-to-page scaling
In addition to regular percentage scaling accomplished using the setScale method, J2ComponentPrinter also supports fit-to-page scaling when J2ComponentPrinter is used as a Pageable using the following method:
setMaximumPages (int pagesWide, int pagesHigh)
Set the maximum
number of vertical and/or horizontal pages for printing the
J2ComponentPrinter (will minify to fit).
The setMaximumPages
method causes your J2PanelPrinter to be scaled down until it fits
within pagesWide pages horizontally and pagesHigh
pages vertically. This method cannot be used to magnify and
instead will only minify your JPanel (hence the name setMaximumPages).
The method works by starting at a scale of 1.0 and reducing the scale
in increments of 0.005 (half a percent) until your J2PanelPrinter fits
within the prescribed limits. There is
only one scaling factor, which is used both horizontally and
vertically, so no distortions are introduced. If either pagesWide
or
pagesHigh is set to 0 or less, this is taken as a signal that
the
scaling in that dimension is unconstrained, that is, the J2PanelPrinter
can
use as many pages as it needs.
The setMaximumPages method causes the rescaling to be calculated and set only at the time it is called and does NOT remember or maintain the page limits you specify, i.e., it is not a state property. Thus, if you change any printing parameters including your document content, headers, footers, margins, paper size, orientation, etc., you must call setMaximumPages again.
IMPORTANT: Instead of using setMaximumPages(1,0) or setMaximumPages(1,1) to rescale your Component to one page wide and/or high, you are strongly encouraged to use SHRINK_TO_FIT pagination mode for the horizontal and/or vertical directions. SHRINK_TO_FIT mode has the major benefit of being a direct calculation and therefore much faster than the iterative setMaximumPages. In addition, SHRINK_TO_FIT is a state that is maintained in the presence of table and/or page size changes and once it is set up it does not need to be reinvoked. In general, you should use setMaximumPages only if the desired number of horizontal and/or vertical pages is greater than 1.The percentage and fit-to-page scaling features interact. You
can
call setMaximumPages(pagesWide, pagesHigh) to specify a
number of
pages and then use the method getScale() to find out the
resulting
scaling factor. Or you can call setScale(factor) to
scale
to a desired percentage and then use getNumberOfPages() to
find
out the number of resulting pages. The getNumberOfPages()
method works for both magnification and minification (thus you could
use it to implement your own fit-to-page feature for magnification,
which you might call setMinimumPages(pagesWide, pagesHigh)).
J2ComponentPrinter WYSIWYG support
J2ComponentPrinter inherently performs WYSIWYG printing since it
images
your
Component instance directly using the Java print and paint
methods.
This
means you will print all of your JPanel's specified fonts, relative
sizes,
layout, colors, etc. The general rule is: whatever your Component
displays is what
J2ComponentPrinter will print.
Non-GUI JPanel printing
It is not necessary that the Component you print be in a JFrame
visible
on
the screen. You may be printing from a server application and
have no
display. Or you may have a Component displayed but wish to print
from a
different non-GUI copy of the Component. The latter situation can
arise when you want to set the printing Component properties different
from your on-screen Component display, such as to force different
background, size, layout, or fonts as appropriate for a printed
page. In such cases, you can use code like:
Component component2 = (Component) (J2Printer.clone(component1));
component2.setSize(component2.getPreferredSize()); // size
required
This code assumes your Component is serializable, since this is how
we
implement the clone method. If necessary, you can implement
writeObject and readObject methods for your Component in order to make
it
serializable.
Java Borders
You can use the Java Swing Borders classes
to add various kinds of borders to your Component, and these will be
printed by J2ComponentPrinter . Borders work when using
J2ComponentPrinter as either
a Pageable or a Flowable. You can use both the Java Borders
feature
and the J2ComponentPrinter method setOutsideLines(true) at
the
same
time (the Java Border will be inside the outside line). Some
examples
of Java Borders are:
component.setBorder(new
LineBorder(Color.green,20));
component.setBorder(new EmptyBorder(10,10,10,10));
component.setBorder(new CompoundBorder(new
LineBorder(Color.green,20),new
EmptyBorder(10,10,10,10)));
Using J2ComponentPrinter as a JavaBean
The J2PrinterWorks components are designed to work as a JavaBeans components in visual builder environments. However, J2PrinterWorks uses APIs unique to the Java 2 system, and not all visual development environments currently work and build visually with Java 2-based components. In particular, WebGain/Symantec Visual Cafe has to be specially configured to allow you to import the J2PrinterWorks components into its component library and exhibits other problems when using it visually. In contrast, Borland JBuilder and IBM VisualAge for Java can read and use J2PrinterWorks.jar as either a set of JavaBeans components or programmatically as classes. See Installation & Compatibility for further details. Since the J2PrinterWorks components are not GUI components per se, the need to work with them visually isn't great, so that using them programmatically isn't much of a limitation.
If J2PrinterWorks.jar is properly installed, you will see the J2PrinterWorks components, including J2Printer and J2ComponentPrinter, in the component palette of your visual programming environment. Click on the J2Printer bean and drop it on your work area and likewise drag the J2ComponentPrinter bean and drop it on your work area. You will see icons representing instances of these beans. These will not be displayed at run-time.
When you bring up the property sheet for either component, you will be able to see and edit their properties. The properties may be set as desired, with values as defined in the Javadoc documentation .
You can make the J2Printer bean print by using your visual programming environment to perform event wiring from an actionPerformed event such as a button push to the J2Printer "print" event target method. You can use this to print the instance of J2ComponentPrinter , using the setComponent method or the J2ComponentPrinter constructor itself to specify your Component or subclass thereof (e.g. JComponent, JPanel, JLabel, etc.).
All the J2PrinterWorks properties are bound properties. You may use your visual programming environment to do property-to-property binding in either direction between the J2PrinterWorks components and your other beans. None of the J2PrinterWorks properties are constrained properties. This frees you from having to place try...catch blocks around your "set" calls in regular programming.
J2PrinterWorks components are fully serializable. After customizing any properties, instances can be saved along with any other beans to which they may be wired. When reloaded, the instances will come back with their customized values. No J2PrinterWorks properties are declared transient.