Installation & Compatibility
|
JTextPrinter 1.0
Installation & Compatibility |
|
WILDCREST ASSOCIATES |
Installation
Download the JTextPrinter zip file and unzip. This will create a JTextPrinter folder containing both code and documentation.
To access the documentation, use your favorite browser to view the file JTextPrinterREADME.html.
JTextPrinter comes in two versions, one for Swing 1.0 which uses com.sun.java.swing.* packaging and one for Swing 1.1 (including Swing 1.1.1) which uses javax.swing.* packaging. In the main JTextPrinter folder you will find two subfolders, VersionForSwing10 and VersionForSwing11, containing these two versions, respectively. Use the appropriate version depending on which version of Swing you are using. Each version has the following contents:
JTextPrinter is a Swing-compatible component. This means you also need to have swingall.jar (or equivalent) installed somewhere in your classpath. See the Sun Java memo on testing whether you have Swing installed and how to install it if necessary and installation information available in the Swing Connection area at the Sun Java site. Sun specifies that Swing requires JDK 1.1.2 or later, with JDK 1.1.5 or later preferred. Because of bugs in the JDK 1.2 support for JDK 1.1-style printing of JTextPane, JTextPrinter will not work with the current version of JDK 1.2.
To use JTextPrinter as a JavaBean, copy JTextPrinter.jar into the jar
folder appropriate for your visual application builder:
for the JavaSoft BDK BeanBox,
copy JTextPrinter.jar into the folder <directory-containing-bdk>\bdk\jars
for the IBM WebRunner BeanTester,
copy JTextPrinter.jar into the folder <directory-containing-webrunnerk>\webrunner\BeanTools\beantester\beans
for Symantec Visual Cafe:
can place JTextPrinter.jar anywhere, then use "Insert: Component to Library..."
command, then right click on JTextPrinter in the Component Library view
and add to desired palette
for Borland JBuilder: can
place JTextPrinter.jar anywhere, then right click on component palette,
select "Properties", then use "Add from Archive"
The JTextPrinter.class file in com\wildcrest is identical to the corresponding
class file in the JTextPrinter.jar archive.
Compatibility
JTextPrinter 1.0 was developed on Windows 95 under JDK 1.1.7A using
Swing 1.0.3 for the com.sun.java.swing.* version and using Swing 1.1, Swing
1.1.1 beta1, and Swing 1.1.1 beta2 for the javax.swing.* version.
Compatibility has been tested on different platforms as follows:
| Windows:
Works successfully on:
Swing 1.0.3 under JDK 1.1.7B on Windows NT
with HP LaserJet 5siMX and 5M printers (TXT, SSD, RTF)
Works but has problems on:
Does not work on:
|
| Macintosh:
Testing is underway on:
|
| Solaris:
Works successfully on:
|
Known Problems and Issues
Users should be aware of the following known problems and issues concerning Java printing using JTextPrinter:
Limits to RTF and HTML support
JTextPrinter is built upon the Swing JTextPane print and paint methods, and unfortunately JTextPane has significant problems with the RTF and HTML formats in the different versions of Swing. JTextPane only supports a limited subset of the RTF and HTML formats. Depending on what version of Swing you are using, you will discover that many features (such as images, tables, frames, special characters, font selection, ruler settings, indentation, scaling etc.) of your RTF or HTML document may display incorrectly or be omitted, and certain documents may not read in at all. The JTextPane printing methods have further problems. There are features of RTF and HTML documents that JTextPane can display but can't print or prints incorrectly, and there are documents that will only print part way or won't print at all.
In practice, only very basic RTF and HTML documents will display and print correctly.
Many of these shortcomings in Swing support for RTF and HTML are documented on the Sun Java Bug Parade web site. Some additional printing-related issues that have been identified for printing RTF and HTML documents are:
Issues with JTextPane text layout
JTextPrinter relies on the Java JTextPane component for its printing functionality, including layout of text and graphics. Any anomalies displayed using a given version of Swing for JTextPane will carry over to printing the JTextPane component and additionally JTextPane printing can introduce anomalies of its own. The following problems have been noted:
Printing transparent GIFs under Windows NT
Under Windows NT, GIF images with transparent backgrounds print incorrectly
with black instead of transparent backgrounds due to a known Java bug (#4175560),
despite the fact that they display correctly. Under Windows 95 and
Solaris, transparent GIFs display and print correctly. There are
two workarounds for this: 1) make your GIFs with white non-transparent
backgrounds or 2) make your GIFs with white backgrounds, specify white
as your transparent color, and change non-transparent white pixels in your
icon to near-white so they aren't transparent when displayed.
Intermittent problems with very simple programs
Very simple printing programs that instantiate a JTextPane, print, and
exit in rapid succession can intermittantly exhibit two problems on some
platforms: 1) text from headers, footers, and/or the body missing and displayed
as a partial line above the header, or 2) NullPointerException on exit.
Both these problems appear to be due to race conditions, where the program
prints and/or exits before the Swing UI thread is ready. These behaviors
have not been observed in typical programs such as JTextPrinterSimpleTest
and JTextPrinterTestApplication, in which printing and exit are invoked
by user actions such as a button or menu selection.
Document serialization and Swing versions
Sun does not provide serialization of documents that is compatible across
Swing releases prior to the JDK 1.2 release. This means that the
documents JTextPrinterTestApplication saves in .SSD format under one version
of Swing will only read back into the same release of Swing. The
SSD test documents provided with this distribution come in Swing 1.0, Swing
1.1, and Swing 1.1.1 versions, and you must use the appropriate version
depending upon the Swing release you have installed (Swing 1.1.1 beta 1
and beta 2 share the same serialization format).
Printing from applications and applets
Printing is primarily a Java application technology. In particular, Java applet security restrictions disallow untrusted applet code from initiating a print job. As a result, JTextPrinter will not generally work from untrusted applets, though different browsers and appletviewers may relax this condition.
Trusted (signed) applets can be made to print, though in practice this
depends on the specific browser or appletviewer. There's a useful memo
on how to create signed applets that can print available at: http://www.adelaide.net.au/~bmodra/PrintJob.html.
Print dialog options
JDK 1.1 is not able to print without having the user respond to a standard system print dialog (this restriction has being removed in JDK 1.2 and has been suggested for JDK 1.1).
Under Windows the following choices can be made by the user in the standard
print dialog and work correctly under JTextPrinter:
a) Number of copies
b) Pages printed in reverse order
c) Pages printed collated
d) Print to file
e) Portrait vs landscape (except this feature had
a bug in Windows JDK 1.1.4 and earlier)
However, none of the above settings are reported as printer preferences in calls to toolkit.getPrintJob(), so they cannot be detected or controlled programmatically.
The "print page range" field in the standard Windows print dialog is
not supported by Java. JTextPrinter includes a page range feature
to provide this capability.
Setting margins
Java printing has undergone many modifications and bug fixes from the
early JDK 1.1.x release through the JDK 1.2, particular on Windows.
Many of these involved changes to page dimensions and resolution.
JTextPrinter includes code that will automatically configure the default
values for top, bottom, left, and right margins in JTextPrinter under Windows
(JDK's 1.1.4 and later) and Solaris/SunOS and Macintosh. These
default values appear to work well for most printers, JDK's, and OS's.
Nonetheless, adding a fraction of an inch to the margins may prove useful
depending upon the printers you actually have. Or, you may find that
for your printer(s) the margins can be reduced and you can print even closer
to the printable edge. You may wish to experiment with JTextPrinter
margin settings to achieve optimal results for your system(s) and printer(s).
Please report any difficulties with JTextPrinter on your configurations
by email to products@wildcrest.com. Be sure to include what Java
release, OS, and development environment or bean tools you are using.
Efforts will be made to fix problems in JTextPrinter, but certain problems
may not be possible to detect and/or correct.