Side of Software

Print Preview Tutorial

Table of Contents

Introduction

Page Content

Using a Standard Toolbar

Building Custom Toolbars

Working with JPrintPreviewPane

Customizing the Look and Feel

Example

Introduction

Most user-friendly applications have a print preview screen that allows the user to preview pages before printing them. On the print preview screen, users typically can zoom in and out on the pages, change the arrangement of pages, change the page format, and print the pages. Although each application may have a slightly different print preview screen, the basic functionality is the same.

The core Java libraries do not provide high-level support for print preview. As a result, developers either implement their own print preview screens or disregard it entirely. By providing the basic print preview functionality, the Print Preview Library makes it easy to add print preview to an application. The library offers a general-purpose Swing component that previews pages, four layout managers that arrange pages on the screen, and a support class that helps build a print preview toolbar.

Before you start using this library, you should download and include on your classpath the jar file of the Java Look and Feel Graphics Repository. It is available free-of-charge here. Without this resource, your print preview toolbar will not have any icons or cursors.

Page Content

The Print Preview Library does not deal with the page content. Therefore, it is not a report generation tool. The print preview pane relies on a java.awt.Pageable object to render the contents of each page. It is the developer’s responsibility to provide an appropriate Pageable object.

That said, the library does provide a utility class, ComponentPageable, that simplifies the common case of previewing and printing a Swing component. With this class, you can easily convert any component—a JTable, JTree, or JPanel, for instance—into a Pageable object.

  JComponent componentToPreview = ...  // application specific

  Pageable pageable = new ComponentPageable( componentToPreview );

Also, Side of Software offers the Report Library, a separate reporting framework that creates Pageable objects from sophisticated reports.

Once you have your Pageable object, you are ready to make use of the library’s features.

Using a Standard Toolbar

The library offers two "standard" toolbars: Navigation and Zoom. These toolbars, which are commonly found across existing applications, can be created with a single call to a factory method.

The Navigation Toolbar

The navigation toolbar allows the user to print the pages, change the page format, step through the pages one at a time, and close print preview. On a Windows machine, the toolbar may resemble:

To create a print preview pane with an accompanying navigation toolbar, invoke one of the static createNavigationPanel factory methods found in PrintPreviewSupport:

  static JPanel createNavigationPanel(Pageable pageable,

                                      boolean showPrintDialog,

                                      Action closeAction,

                                      boolean largeIcons)

  static JPanel createNavigationPanel(PageableFactory pageableFactory,

                                      boolean showPrintDialog,

                                      Action closeAction,

                                      boolean largeIcons)

The methods differ only in the first parameter. The first method takes the preview pages (pageable) and does not allow the user to change the page format. The second method, on the other hand, takes a PageableFactory that can generate the preview pages on demand, thereby supporting changes in page format. Generally, you should use the second method only if all pages follow the same page format.

The remaining three parameters are treated as follows:

The following code snippet creates a print preview pane with a navigation toolbar.

  // create an object that will render the contents 

  // of each page (application specific)

  Pageable pageable = ... 

  // create an action that will close 

  // print preview (application specific)

  Action closeAction = ...

  // create the print preview panel with

  // a navigation toolbar

  JPanel printPreviewPanel = PrintPreviewSupport.createNavigationPane( 

    pageable, false, closeAction, false );

  // add the panel to your application

  // (application specific)

  JComponent contentPane = ...

  contentPane.add( printPreviewPanel );

The Zoom Toolbar

The zoom toolbar allows the user to print the pages, change the page format, zoom in and out on the pages, change the arrangement of pages, and close print preview. There are four different zoom behaviors:

On a Windows machine, the toolbar for each of these behaviors may look like:

To create a panel with a print preview pane and a navigation toolbar, invoke one of the static createZoomPanel factory methods:

  static JPanel createZoomPanel(Pageable pageable,

                                boolean showPrintDialog,

                                int zoomFlavor,

                                Action closeAction,

                                boolean largeIcons)

  static JPanel createZoomPanel(PageableFactory pageableFactory,

                                boolean showPrintDialog,

                                int zoomFlavor,

                                Action closeAction,

                                boolean largeIcons)

Again, the methods differ only in the first parameter. The second method includes a page setup button on the toolbar. The printFlavor, closeAction, and largeIcons parameters follow the same guidelines as above.

The following code snippet creates a print preview pane with a zoom toolbar.

  // create an object that will render the contents 

  // of each page (application specific)

  Pageable pageable = ... 

  // create an action that will close 

  // print preview (application specific)

  Action closeAction = ...

  // create the print preview panel with

  // a zoom toolbar

  JPanel printPreviewPanel = PrintPreviewSupport.createZoomPane( 

    pageable, false, PrintPreviewSupport.ZOOM_IN_OUT_TOGGLE,

    closeAction, false );

  // add the panel to your application

  // (application specific)

  JComponent contentPane = ...

  contentPane.add( printPreviewPanel );

Building Custom Toolbars

If you prefer not to use the standard toolbars, you can build your own toolbars with the help of an instance of PrintPreviewSupport. PrintPreviewSupport offers many methods to create common toolbar components:

It supports only one instance of each of these components. Thus, it is not possible (through PrintPreviewSupport) to have two print buttons on the toolbar.

For many of the above components, you will find the following methods:

  public <Component> getXxxComponent();

  public Action getXxxAction();

  public String getXxxText();

  public Icon getXxxIcon();

  public String getXxxToolTip();

  public int getXxxMnemonic();

The methods return a component, action, name, icon, tool tip, and mnemonic, respectively, appropriate for the task Xxx. Invoke the method that serves your needs. For example, if you wish to add a previous page button to your toolbar, invoke getPreviousPageButton. If you wish to create your own component yet use the text and description associated with the previous page action, invoke getPreviousPageText and getPreviousPageToolTip.

Custom Toolbar Example

Suppose in your application you want to provide a minimal print preview pane that allows the user to print all pages, select a zoom layout, and display help information. PrintPreviewSupport does not provide a factory method to create such a toolbar; however, it does provide the functionality to print all pages and select a zoom layout. Your application can take advantage of the built-in functionality:

  // create a print preview pane component

  Pageable pageable = ...

  JPrintPreviewPane printPreviewPane = new JPrintPreviewPane( 

    pageable );

  // create the print preview toolbar

  JToolBar toolBar = new JToolBar();

  // enlist some help in creating the toolbar

  PrintPreviewSupport support = new PrintPreviewSupport( 

    printPreviewPane, true );

  // use the built-in print button

  JButton printAllButton = support.getPrintAllButton();

  printAllButton.setText( "" );     // show no text

  printAllButton.setBorder( null ); // show no border

  // use the built-in zoom combobox

  JComboBox zoomCombo = support.getZoomComboBox( false, false );

  // create our own help button (application specific)

  JButton helpButton = ...

  // add these components to the toolbar

  toolBar.add( printAllButton );

  toolBar.addSeparator();

  toolBar.add( zoomCombo );

  toolBar.addSeparator();

  toolBar.add( helpButton );

  // place the print preview pane in a scroll pane

  JScrollPane scrollPane = new JScrollPane( printPreviewPane );

  // add the scroll pane and toolbar to a panel

  JPanel panel = new JPanel( new BorderLayout() );

  panel.add( scrollPane, BorderLayout.CENTER );

  panel.add( toolBar, BorderLayout.PAGE_START );

The above code creates the following toolbar.

Subclassing PrintPreviewSupport

You can subclass PrintPreviewSupport in order to make small changes to the built-in behavior. For example, suppose you are happy with the built-in navigation pane but wish the print button read “Print Dialog...” instead of “Print...” You can create a subclass of PrintPreviewSupport and override getPrintText, as follows:

  class CustomPrintPreviewSupport extends PrintPreviewSupport

  {

    public CustomPrintPreviewSupport( JPrintPreviewPane printPreviewPane, 

                                      boolean largeIcons )

    {

      super( printPreviewPane, largeIcons );

    }

    public String getPrintText()

    {

      return "Print Dialog...";

    }

  }

Working with JPrintPreviewPane

JPrintPreviewPane provides numerous methods to allow you to manipulate it. You can change the page layout, zoom in and out, switch the user mode, and select pages.

Page Layouts

The print preview pane must decide how to arrange the pages. JPrintPreviewPane accomplishes this by installing page components as children and asking the layout manager to arrange the children. This library provides four types of page layout, as described in the following table.

These four page layouts implement java.awt.LayoutManager and are accessed using the methods defined in superclass java.awt.Container:

  public void setLayout( LayoutManager layout );

  public LayoutManager getLayout();

You can listen for changes to the layout manager by registering a property change listener on the key LAYOUT_PROPERTY.

You can customize the arrangement of pages by defining your own java.awt.LayoutManager. If your custom layout scheme dictates how the print preview pane should scroll, then it should implement the interface ScrollableLayoutManager. If your custom layout scheme works by scaling the preview pages, then it should implement the interface ScalingLayoutManager.

Zooming

JPrintPreviewPane actually achieves zooming by changing the layout manager to an appropriate ZoomLayout instance. It provides the following convenience methods:

  public double getScale();

  public boolean zoom( double scale );

  public boolean zoom( double scale, Point point );

  public boolean zoomIn();

  public void zoomIn( int pageIndex );

  public boolean zoomIn( Point point );

  public boolean zoomOut();

  public void zoomOut( int pageIndex );

  public boolean zoomOut( Point point );

When a java.awt.Point argument is provided in one of the above methods, the print preview pane attempts to zoom at the specified point. The zoomed view tries to put at its center the same relative position of the page at that point. When a page index is provided, the print preview pane zooms at the center of the specified page. When neither a point nor a page index is provided, the component zooms at the point on a page nearest the center of the visible region.

When there is a change in zoom, JPrintPreviewPane sends a PropertyChangeEvent for the key SCALE_PROPERTY.

To determine how far the pane should zoom, it asks an instance of ZoomFunction, which is defined as follows:

  public interface ZoomFunction

  {

    public double zoomIn(double scale);

    public double zoomOut(double scale);

  }

Given the current scale, these methods return the next scale for zooming either in or out. By returning the same value as the parameter, ZoomFunction essentially disallows the zoom. The default behavior allows zooming out to 1% and unlimited zooming in. Each step (in or out) is 25% of the current zoom factor.

You can customize the amount of zooming the print preview pane provides by installing a custom implementation of ZoomFunction and invoking

  public void setZoomFunction( ZoomFunction zoomFunction );

The custom implementation may either implement ZoomFunction directly or be a customized instance of DefaultZoomFunction.

Modes

JPrintPreviewPane can be in exactly one of four user modes:

The following methods set and retrieve the mode:

  public int getMode();

  public void setMode(int mode);

You can listen for changes to the mode by registering a property change listener on the key MODE_PROPERTY.

Page Selection

When JPrintPreviewPane is in selection mode, one or more pages can be selected. Each JPrintPreviewPane instance has an underlying selection model. The following methods deal with page selection:

  public ListSelectionModel getPageSelectionModel();

  public boolean isPageSelected( int pageIndex );

  public void setPageSelectionModel( ListSelectionModel selectionModel );

  public boolean getPageSelectionAllowed();

  public int getSelectedPageIndex();

  public void setPageSelectionAllowed( boolean pageSelectionAllowed );

You can listen for changes to the selection by registering a ListSelectionListener with the selection model.

Page Numbering

When page numbering is turned on, the print preview pane displays a page number for each page. You can turn page numbering on and off with

  public void setPageNumbersAreShown( boolean pageNumbersAreShown );

The page number is rendered using an instance of PageNumberRenderer. By default, it is rendered as a numeral centered beneath the page. You can change the way page numbers are rendered with

  public void setPageNumberRenderer( PageNumberRenderer pageNumberRenderer );

Page number renderers must implement a method that returns a component ready to render the page number:

  public interface PageNumberRenderer

  {

    public Component getPageNumberRendererComponent( 

      JPrintPreviewPane printPreviewPane, 

      int pageNumber, 

      boolean isSelected, 

      boolean pageHasFocus );

  }

The library provides one implementation of PageNumberRenderer: DefaultPageNumberRenderer. This implementation uses a shared JLabel component to render the page numbers. Developers can subclass DefaultPageNumberRenderer to customize the look of the label. In anticipation of customization, DefaultPageNumberRenderer invokes two protected methods when initializing the label: pageNumberToString and prepareLabel. If you wish to change the displayed text, override pageNumberToString. If you wish to change the appearance of the label (for example, the color or font), override prepareLabel.

Here is a an example of a custom page number renderer that overrides pageNumberToString to display the word “Page” before each page number.

  class CustomPageNumberRenderer extends DefaultPageNumberRenderer

  {

    protected String pageNumberToString( int pageNumber )

    {

      return "Page " + pageNumber;

    }

  }

Custom Preview Pages

You can change the appearance of each previewed page. By default, the print preview pane creates a JPrintPreviewPage component for each page being previewed. Each JPrintPreviewPage gets rendered as a rectangle with a border and shadow atop a page number. You can substitute a custom java.awt.Component class for JPrintPreviewPage. To do this, subclass JPrintPreviewPane and override createPageComponent. Your custom component should implement Scaleable if it does not scale uniformly.

Customizing the Look and Feel

You can further customize your print preview pane by defining look-and-feel properties. At application start-up, define the properties you wish to change with the call

  UIManager.put( propertyKey, propertyValue );

where propertyKey specifies the property and propertyValue is the desired value. The type of propertyValue depends on the property key. The key should be one of the following keys:

Example

The example PrintPreviewDemo demonstrates the flexibility of print preview panes.  It displays pages of text beneath a custom tool bar and allows the user to add and remove pages, change the look and feel of the pages, and zoom in and out. In this application, you can find examples of how to

• Create a print preview pane
• Build a custom print preview toolbar with the help of PrintPreviewSupport
• Change the look and feel of the print preview pane
• Change the look and feel of the print preview pages
• Listen for a property change on a print preview pane
• Switch the print preview pane’s mode
• Create a custom page number renderer
• Alter the page selection model

You can run this sample application on the library’s homepage.

Home  |  Contact Us  |  Privacy Policy

Copyright © 2016 Side of Software, a branch of Natavision. All rights reserved.