Skip to content

Viewer Swing AWT RI

Patrick Corless edited this page Oct 18, 2026 · 2 revisions

The icepdf Swing viewer is a reference implementation of a stand-alone PDF viewer built on Swing/AWT. You can use it as is, embed it in your own application, or use it as a starting point for a custom viewer.

The viewer is built from two classes. SwingViewBuilder creates the user interface components, such as the toolbar, menus and page view, and SwingController connects them to the document and manages their state. Together they produce a full-featured viewer that works as is for most applications.

A newer JavaFX viewer is also available; see Viewer JavaFX RI.

Maven dependencies

<dependency>
    <groupId>com.github.pcorless.icepdf</groupId>
    <artifactId>icepdf-core</artifactId>
    <version>x.y.z</version>
</dependency>
<dependency>
    <groupId>com.github.pcorless.icepdf</groupId>
    <artifactId>icepdf-viewer</artifactId>
    <version>x.y.z</version>
</dependency>

Launching the Viewer

From any Maven project with the icepdf dependencies:

mvn exec:java -Dexec.mainClass=org.icepdf.ri.viewer.Launcher

From a source checkout:

./gradlew :viewer:viewer-awt:run

Command line options

Option Description
-loadfile <file> Opens a local PDF file, for example -loadfile /home/user/file.pdf
-loadurl <url> Opens a PDF file from a URL, for example -loadurl https://www.example.com/file.pdf
-print <printer> Prints the loaded file to the named printer
-pkcs11path <file> Path to a PKCS#11 configuration file for signing
-pkcs12path <file> Path to a PKCS#12 keystore for signing

Configuring the Viewer

ViewerPropertiesManager

The viewer is configured with properties, so its features can be turned on and off without changing or recompiling the viewer source. Settings are stored with the Java Preferences API, whose backing store is platform dependent.

Default values come from ICEpdfDefault.properties in org/icepdf/ri/viewer/res/. Supplying your own copy of this file is the easiest way to configure a custom build. Alternatively, set properties through ViewerPropertiesManager.getInstance() before the viewer is built. Once settings have been saved to the user's preferences, clearPreferences() restores the defaults.

The most commonly used properties are listed below. ViewerPropertiesManager defines many more, including annotation colours, search defaults and preference dialog tabs.

General

Property Type Default Description
application.viewerpreferences.hidemenubar boolean false Hides the menu bar.
application.viewerpreferences.hidetoolbar boolean false Hides the toolbar.
application.viewerpreferences.fitwindow boolean true Fits the page to the window width when the document doesn't specify a view.
application.menuitem.show.keyboard.shortcuts boolean true Enables menu keyboard shortcuts.
application.zoom.factor.default number 1.0 Default page zoom.
application.zoom.range.default string 0.05,0.1,0.25,0.5,0.75,1.0,1.5,2.0,3.0,4.0,8.0,16.0,24.0,32.0,64.0 Comma-separated zoom levels for the zoom combo box.

Toolbar

Property Type Default Description
application.toolbar.show.utility boolean true Shows the utility toolbar (open, save, print, search, utility pane).
application.toolbar.show.utility.open boolean true Shows the open control.
application.toolbar.show.utility.save boolean true Shows the save control.
application.toolbar.show.utility.print boolean true Shows the print control.
application.toolbar.show.utility.search boolean true Shows the search control.
application.toolbar.show.utility.upane boolean true Shows the control that shows or hides the utility pane.
application.toolbar.show.pagenav boolean true Shows page navigation: first, previous, next and last.
application.toolbar.show.zoom boolean true Shows zoom controls.
application.toolbar.show.fit boolean true Shows page fit controls: actual size, fit page and fit width.
application.toolbar.show.rotate boolean true Shows page rotation controls.
application.toolbar.show.fullscreen boolean true Shows the full screen control.
application.toolbar.show.tool boolean true Shows the tools toolbar (select, pan and zoom tools).
application.toolbar.show.annotation boolean true Shows the annotation tools.
application.toolbar.show.forms boolean true Shows the forms toolbar.
application.toolbar.show.search boolean true Shows the quick search field.

Individual annotation tools can be hidden with the application.toolbar.annotation.<tool>.enabled properties, for example application.toolbar.annotation.ink.enabled.

Utility pane

Property Type Default Description
application.utilitypane.hide boolean false Starts with the utility pane hidden.
application.utilitypane.show.bookmarks boolean true Shows the outline tab.
application.utilitypane.show.thumbs boolean true Shows the thumbnails tab.
application.utilitypane.show.search boolean true Shows the search tab.
application.utilitypane.show.annotation boolean true Shows the annotations tab.
application.utilitypane.show.layers boolean true Shows the layers tab.
application.utilitypane.show.attachments boolean true Shows the attachments tab.
application.utilitypane.show.signatures boolean true Shows the signatures tab.

Status bar

Property Type Default Description
application.statusbar boolean true Shows the status bar.
application.statusbar.show.statuslabel boolean true Shows the status label.
application.statusbar.show.viewmode boolean true Shows the view mode controls.

SwingViewBuilder

org.icepdf.ri.common.SwingViewBuilder builds the viewer's components, pre-configured to work with org.icepdf.ri.common.SwingController. buildViewerFrame() and buildViewerPanel() build a complete viewer, and many smaller build... methods build individual parts. For example, buildCompleteMenuBar() returns the full menu bar and buildFileMenu() returns just the File menu. Use whichever level suits your application; see the SwingViewBuilder JavaDoc for the full list.

To customize the components themselves, you can either:

  1. Subclass SwingViewBuilder and override the build... methods you need to change. For example, override buildAboutMenuItem() to show your own About dialog. Your application automatically picks up improvements to the methods you didn't override in future releases.
  2. Copy SwingViewBuilder into your own class and change it freely. Future changes to the default interface won't affect your application, but you'll need to merge any you want by hand.

Annotation Tools

icepdf has a rich set of annotation tools, available from the viewer's toolbar and through the core API.

  • Text markup: highlight, underline and strike out selected text. Double-clicking a markup annotation opens its popup note.
  • Notes and free text: sticky notes, and free text boxes with custom borders and background colours.
  • Shapes and ink: rectangles, circles, lines, arrows and freehand ink.
  • Links: link annotations to pages or URLs.
  • Redaction: draw a rectangle over text or images to mark them for redaction. The redactions are applied when the document is exported: intersecting text is removed and the covered areas of images are set to black.

Text Selection Key Commands

Action Keys
Move caret by character / line ←/→ / ↑/↓
Extend by character / line Shift+←/→ / Shift+↑/↓
Move / extend by word Ctrl+←/→ / Ctrl+Shift+←/→
Line start / end Home / End
Extend to line start / end Shift+Home / Shift+End
Select all Ctrl+A
Copy Ctrl+C

Text Editing

Since icepdf 7.3.0, text can be edited when the text selection tool is active and nothing is selected. Right-click a text block to edit a word or a whole line. The edit dialog warns when the font doesn't contain the characters needed.

Text editing is intended for small corrections, not general editing. Results depend heavily on how the document's content was written. If a line mixes fonts or styles, edit individual words, or some formatting will be lost.

Destinations and Outlines

Since icepdf 7.3.0, outlines (bookmarks) can be edited when the document's permissions allow it, and the Insert > Outline menu item adds new outline items.

  • Destinations: with the annotation selection tool active, right-click a page to insert a named destination. A document's named destinations are listed in the annotations tab of the utility pane.
  • Outlines: drag nodes to rearrange the tree, triple-click a node to rename it, and use the context menu to add, edit or delete items. The edit dialog sets an item's destination, either explicitly or by choosing a named destination.

Digital Signatures

Validation

The viewer validates digital signatures and shows their certificate details. Right-click a signature to open its signature properties or certificate details.

Signing

  1. Use the Signature tool on the toolbar to draw a signature field.
  2. Right-click the field and choose to add a signature.
  3. Export the document. The signature is applied when the exported copy is written.

A document can contain several signature fields, but they must all use the same certificate. For a second signer, use the first signer's exported document as the source.

Keystore configuration

The Signatures tab of the Preferences dialog sets the path to a PKCS#12 keystore or a PKCS#11 configuration file, and an optional Time Stamp Authority (TSA) URL used to timestamp signatures. The paths can also be passed on the command line with -pkcs12path and -pkcs11path.

PKCS12 keystore setup

To create a self-signed certificate and keystore for testing:

  1. Create a private key and self-signed certificate: openssl req -newkey rsa:2048 -keyout my-private.key -x509 -days 365 -out my-cert.crt
  2. Combine them into a PKCS#12 file: openssl pkcs12 -inkey my-private.key -in my-cert.crt -export -out my-pkcs12-combo.pfx
  3. Point the Signatures tab of the Preferences dialog at my-pkcs12-combo.pfx.

PKCS11 keystore setup

PKCS#11 keystores are read from a smart card or hardware token, and configuration varies by vendor. See the Java PKCS#11 Reference Guide for options. Once configured, the device's signing certificates appear in the add signature dialog.

Internationalization

The viewer uses standard Java resource bundles for its text, stored in org.icepdf.ri.resources. Translations are included for Danish, German, Swiss German, Spanish, Finnish, French, Italian, Dutch, Norwegian, Portuguese, Swedish, and Simplified and Traditional Chinese.

Callbacks

SecurityCallback

When a document is encrypted, Document first tries an empty password. If that fails, it asks the org.icepdf.core.SecurityCallback for one. The viewer's own implementation, org.icepdf.ri.common.MyGUISecurityCallback, shows a password dialog. You can supply your own, for example to read the password from the command line:

Document document = new Document();
document.setSecurityCallback(doc -> {
    System.out.println("This document is encrypted. Please type the password:");
    try {
        return new BufferedReader(new InputStreamReader(System.in)).readLine();
    } catch (IOException e) {
        return "";
    }
});
document.setFile(filePath);

AnnotationCallback

When a user clicks an annotation such as a link, icepdf draws its effect but doesn't run its action. Instead it passes the annotation to an org.icepdf.ri.common.views.AnnotationCallback, which decides what to do. The default implementation, org.icepdf.ri.common.MyAnnotationCallback, follows links within the document and opens external URIs in the system's default browser.

SwingController controller = new SwingController();
SwingViewBuilder factory = new SwingViewBuilder(controller);
JPanel viewerComponentPanel = factory.buildViewerPanel();

// handle link and other annotation actions
controller.getDocumentViewController().setAnnotationCallback(
        new MyAnnotationCallback(controller.getDocumentViewController()));

JFrame applicationFrame = new JFrame();
applicationFrame.setDefaultCloseOperation(JFrame.EXIT_ON_CLOSE);
applicationFrame.getContentPane().add(viewerComponentPanel);
applicationFrame.pack();
applicationFrame.setVisible(true);

controller.openDocument(filePath);

Clone this wiki locally