|
J2ListPrinter |
|
J2ListPrinter is a Java 2 component for printing multi-page JList documents. J2ListPrinter converts any JList or JList subclass into a Java Pageable, suitable for printing by the J2Printer class (or any Java PrinterJob). It also implements Flowable for any JList, so that it may be used with J2FlowPrinter as part of a series of Flowables printed back-to-back.
J2ListPrinter
Pagination
A J2ListPrinter instance will
print a JList as a Pageable. J2ListPrinter paginates JList instances
across multiple pages vertically, breaking the JList on row (tree node)
boundaries. A JList that is too wide horizontally will be rescaled to
fit the page width. The JList can be left, right, or center justified
horizontally, and top, bottom, or center justified vertically. You can
also specify whether to draw an
outside line around the JList. The JDK 1.4/1.5 layout orientations
HORIZONTAL_WRAP
and VERTICAL_WRAP are also supported, permitting the printing of
multiple column JList instances.
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.
J2ListPrinter can instantiated with a zero-argument constructor:
J2ListPrinter listPrinter = new
J2ListPrinter();
J2ListPrinter listPrinter = new J2ListPrinter(yourJList);
The following is a simple but complete Java program (J2ListPrinterSimplestTest.java ) that displays and prints a JList using J2ListPrinter:
import java.awt.*;
import javax.swing.*;
import com.wildcrest.j2printerworks.*;
class J2ListPrinterSimplestTest {
static public void main(String args[]) {
String[] data;
int num = 100;
data = new String[num];
for (int i=0; i<num; i++) {
data[i] =
"This is JList item number " + (i+1);
}
JList list = new JList(data);
// can test these under JDK 1.4 or
later
//list.setLayoutOrientation(JList.HORIZONTAL_WRAP);
//list.setLayoutOrientation(JList.VERTICAL_WRAP);
list.setVisibleRowCount(35);
JFrame frame = new
JFrame("J2ListPrinter test");
frame.getContentPane().add(list);
frame.pack();
frame.setVisible(true);
J2ListPrinter treePrinter = new
J2ListPrinter(list);
J2Printer printer = new
J2Printer();
printer.setSeparatePrintThread(false);
printer.addPageable(treePrinter);
printer.setPrintPreviewScale(1.0);
printer.printer.print();
System.exit(0);
}
}
Most of the methods of J2ListPrinter are set and get methods for
controlling
its property values. The full list of J2ListPrinter methods, what they
do,
and their default values are given in the
J2ListPrinter Javadoc documentation .
Whether J2ListPrinter is used as a Pageable or a Flowable, you can
control
whether it is left, right, or center justified horizontally on a page,
top,
bottom, or center justified within the remaining space on a page, and
whether to draw an
outside
line around the JList.
Horizontal and vertical alignment
J2ListPrinter will print your JList 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, J2ListPrinter will print your JList 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 JList on
the page.
setVerticalAlignment (int verticalAlignment)
Sets the
vertical
alignment (TOP, CENTER, BOTTOM) for printing the JList on the page.
Outside line
J2ListPrinter lets you control whether to draw a line surrounding the JList and what color this line should be using the following methods:
setOutsideLines (boolean showOutsideLines)
Sets whether to
print outside border lines around JList.
setOutsideLineColor (java.awt.Color outsideLineColor)
Sets Color of
outside border lines.
When J2ListPrinter 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 J2ListPrinter 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 J2ListPrinter method(s) with the argument J2Printer.GLOBAL.
The Pageable properties of J2ListPrinter will be ignored when the
J2ListPrinter
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 J2ListPrinter used as a Flowable. Note, however, that scaling
does work for J2ListPrinter used as either
a Pageable or a Flowable, that is, the J2ListPrinter 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, J2ListPrinter also supports fit-to-page scaling when J2ListPrinter is used as a Pageable using the following method:
setMaximumPages (int pagesHigh)
Set the maximum
number of vertical pages for printing this J2ListPrinter (will minify
to fit).
The setMaximumPages method causes your J2ListPrinter to be scaled down until it fits within pagesHigh pages vertically. This method cannot be used to magnify and instead will only minify your J2ListPrinter (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 J2ListPrinter fits within the prescribed limits. If pagesHigh is set to 0 or less, this is taken as a signal that the scaling is unconstrained, that is, the J2ListPrinter can use as many pages as it needs.
NOTE: This method causes the rescaling to take place at the time it is called and does NOT remember or maintain the page limits you specify. Thus, if you change any printing parameters including your document content, headers, footers, margins, paper size, orientation, etc., you must call setMaximumPages again.
The percentage and fit-to-page scaling features interact. You
can
call setMaximumPages(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(pagesHigh) ).
J2ListPrinter WYSIWYG support
J2ListPrinter inherently performs WYSIWYG printing since it images
your
JList instance directly using the Java print and paint methods.
This
means you will print all of your JList's specified fonts,
colors,
etc. If you subclass JList and provide your own custom cell
renderers,
these also will be displayed and printed. The general rule is:
whatever
your JList can display, J2ListPrinter will print.
Non-GUI JList printing
It is not necessary that the JList 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 JList displayed but wish to print from a different non-GUI copy of the JList. The latter situation can arise when you want to set the printing JList properties different from your on-screen JList display, such as to force different colors or fonts as appropriate for a printed page. In such cases, you can use code like:
JList list2 = new JList();
list2.setModel(list1.getModel());
list2.setSize(list2.getPreferredSize()); // size required
Java Borders
You can use the Java Swing Borders classes
to add various kinds of borders to your JList, and these will be
printed by
J2ListPrinter. Borders work when using J2ListPrinter as either a
Pageable or a Flowable. You can use both the Java Borders feature
and the J2ListPrinter method setOutsideLines(true) at the
same time (the Java Border will
be inside the outside line). Some examples of Java Borders are:
jList1.setBorder(new LineBorder(Color.green,20));
jList1.setBorder(new EmptyBorder(10,10,10,10));
jList1.setBorder(new CompoundBorder(new
LineBorder(Color.green,20),new
EmptyBorder(10,10,10,10)));
Using J2ListPrinter 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 J2ListPrinter, 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 J2ListPrinter 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 J2ListPrinter, using the setList method or the J2ListPrinter constructor itself to specify your JList.
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.