JTextPrinter 1.0 User Manual

WILDCREST ASSOCIATES

Using JTextPrinter as a JavaBean

When you bring up the property sheet for JTextPrinter (right), you will be able to see and edit all the page setup values supported by JTextPrinter.  The properties may be set as desired, with values as defined in the JTextPrinter Javadoc documentation.

You can make the JTextPrinter bean print by using your visual programming environment to perform event wiring from an actionPerformed event such as a button push to the JTextPrinter "print" event target method.  JTextPrinter also exposes all the regular inherited component methods such as show, hide, enable, disable, etc.

All the JTextPrinter properties are bound properties.  You may use your visual programming environment to do property-to-property binding in either direction between JTextPrinter and your other beans.  None of the JTextPrinter properties are constrained properties.  This frees you from having to place try...catch blocks around set calls in regular programming.

JTextPrinter is fully serializable.  After customizing any of its properties,  a JTextPrinter instance can be saved along with any other beans to which they may be wired.  When reloaded, the JTextPrinter bean will come back with its customized values.  No JTextPrinter properties are declared transient.
 

Using JTextPrinter as a class

JTextPrinter may also be used programmatically as a simple class. JTextPrinter is distributed in the package com.wildcrest. A com folder with a wildcrest subfolder containing JTextPrinter.class should be placed somewhere in your classpath (see Installation instructions).

You may find it useful to begin your program with:
    import com.wildcrest.JTextPrinter;
or you may make calls to JTextPrinter with the full package name:
    com.wildcrest.JTextPrinter();

JTextPrinter is instantiated with a zero-argument constructor:
    JTextPrinter printer = new JTextPrinter()

Or, you set the desired JTextPane to be printed using:
    printer.setMainDocument(jtextpane)
and follow with a call to the zero argument print method:
    printer.print()

The following is a simple but complete Java program that prints using JTextPrinter:

import javax.swing.*;        // use com.sun.java.swing.* for Swing 1.0
import javax.swing.text.*;   // use com.sun.java.swing.text.* for Swing 1.0
import com.wildcrest.JTextPrinter;

class JTextPrinterSimplestTest {
    static public void main(String args[]){
        JFrame frame = new JFrame("JTextPrinter test");
        frame.setSize(300,200);
        frame.setVisible(true);

        JTextPane pane = new JTextPane();
        frame.getContentPane().add(pane);
        pane.replaceSelection("This is a string that will be printed");

        JTextPrinter printer = new JTextPrinter();
        printer.print(pane);

        System.exit(0);
    }
}

Most of the methods of JTextPrinter are set and get methods for controlling its property values. The defaults for all these values are shown in the property list editor in the "Using JTextPrinter as a JavaBean" section above.  The full list of JTextPrinter methods, what they do, and their default values are given in the JTextPrinter Javadoc documentation.
 

Using advanced features of JTextPrinter

This section describes a number of the special  features of JTextPrinter and how to use them.

Multiple column printing with optional title section
The JTextPrinter method setNumberOfColumns lets you set the number of columns with which the main document will be printed.  The method setGapBetweenColumns will let you control the distance between the columns.  Optionally, you can print a single column title section before the main document.  To do this, you can either use the two argument print method:
        jtextprinter.print(titleSection, mainDocument);
or you can separately set the title section, main section, and then print:
        jtextprinter.setTitleSection(jtextpane1);
        jtextprinter.setMainDocument(jtextpane2);
        jtextprinter.print();
The title section can be used for titles and abstracts, tables of contents, cover pages, etc.  It can itself span multiple pages.

Headers and footers, boxes and lines
JTextPrinter lets you separately set the left, center, and right headers and footers.  Any of these can be empty.  Any of these can also contain page numbering and date and time formatting (see Javadoc descriptions in the header and footer methods).  You can also have the header by itself, surrounded by a box, or underlined,  You can likewise have the footer by itself, surrounded by a box, or overlined.  You can only specify a single font for both the header and footer.  If you wish to have no header and/or no footer, you can set the left, center, and right sections to be empty and set the gapBelowHeader and/or gapAboveFooter to 0.

JTextPane WYSIWYG support
JTextPrinter normally reflows (line wraps) your document to fill the printed page.  However, JTextPrinter can be controlled to print your JTextPane with exactly the same flow as the JTextPane appears on the screen.  For this purpose JTextPrinter has a setMaximumColumnWidth method.  If you set the JTextPrinter maximumColumnWidth to the same width as the JTextPane, assuming that this number of pixels is less than or equal to the number of pixels available on the printed page, you will get a WYSIWYG representation of your JTextPane in your printed output.  The following code will do this:
        jtextprinter.setMaximumColumnWidth(jtextpane.getSize().width);
If you setMaximumColumnWidth to any negative value, it is equivalent to using the largest possible integer value and means JTextPrinter will use the width of the printed page to determine its wrapping width.

Default, platform-specific margins
As users of our plain text TextPrinter AWT component know, there have been substantial changes in the treatment of physical and logical margins during the successive releases of the JDK on different platforms.  TextPrinter included sample code that set the margins appropriately for many of these combinations.  This code is now included in JTextPrinter itself and is used to set the default top, bottom, left, and right margins appropriately for JDK 1.1.4, 1.1.5, 1.1.6, 1.1.7 and 1.2 on Windows, plus Macintosh and Solaris.  Some experimentation may still be necessary given differences among printers, but these values appear to be generally useful on a wide variety of platforms.

Print monitor job name
JTextPrinter lets you control the name that will appear in the print monitor (printing status window) on your platform using the method setPrintJobName.  Prior to JDK 1.1.7, Java did not support this feature, so if you use an earlier platform, you will always get a default name in the print monitor for all print jobs.

Page breaks
JTextPrinter supports hard page breaks.  Simply insert a form feed character "\f" into your document at the point you wish to force a page break in your output.

Page ranges
JTextPrinter will print a subset of your total set of pages.  Use the setPageRange method to indicate the pages you wish to print.  The format of the page range argument is the same as the syntax used in Microsoft Word, Excel, etc.  The argument to setPageRange is a string of values separated by commas, where values can be individual pages, or page numbers separated by a hyphen.  Pages start with page number 1.  Pages come out in their numerical order regardless of the order in which you list them in the page range.  Spaces in a page range are ignored.  Examples of page ranges are:
        1
        1-999
        1,2,5
        1-4, 6, 8-10
        12, 8, 6-4, 9 (prints 4, 5, 6, 8 , 9, 12 in that order)
Setting the page range to an empty string ("") means print all pages, and this is the default value.