Repository navigation
Viewer Swing AWT RI
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.
<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>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
| 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 |
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.
| 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. |
| 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.
| 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. |
| 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. |
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:
-
Subclass
SwingViewBuilderand override thebuild...methods you need to change. For example, overridebuildAboutMenuItem()to show your own About dialog. Your application automatically picks up improvements to the methods you didn't override in future releases. -
Copy
SwingViewBuilderinto 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.
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.
| 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 |
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.
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.
The viewer validates digital signatures and shows their certificate details. Right-click a signature to open its signature properties or certificate details.
- Use the Signature tool on the toolbar to draw a signature field.
- Right-click the field and choose to add a signature.
- 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.
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.
To create a self-signed certificate and keystore for testing:
- Create a private key and self-signed certificate:
openssl req -newkey rsa:2048 -keyout my-private.key -x509 -days 365 -out my-cert.crt - Combine them into a PKCS#12 file:
openssl pkcs12 -inkey my-private.key -in my-cert.crt -export -out my-pkcs12-combo.pfx - Point the Signatures tab of the Preferences dialog at
my-pkcs12-combo.pfx.
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.
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.
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);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);Project site · Javadoc · Releases · Discussions · Issues
Start
Use the library
Viewers
Configure and tune
Project