Implement custom actions in the Java PDF Viewer

This tutorial explains how you can customize and override the default behaviour of all available actions in the JPedal Java PDF viewer.

By default, every possible action in the Java PDF viewer has a default Java implementation. For example, when you click the “Open” button, a JFileChooser is displayed. Once the user has selected a file, that file is then loaded into JPedal. Because of the flexible, and completely customizable nature of JPedal however, these default actions can be easily customized and overridden.

In this tutorial, we are going to show how easy it is to implement a new default action for the “Help” button. By default on the Viewer toolbar, there is a help button. It is the rubber ring icon shown below.

We are going to create our own java action for this button, so when the end-user clicks on it, they see a custom dialog box. The source code of this complete worked example is available in the ExampleActionHandler class.

Creating Your Own JPedalActionHandler Implementation

All custom action handlers must implement the org.jpedal.external.JPedalActionHandler Interface. This is only one method your class needs to implement, that is:

public void actionPerformed(SwingGUI currentGUI, Commands commands);

This method will be called whenever the user performs the action associated with the implementing handler, in our case the Help button. You can add your own code here to perform whatever action best suits your application.

Possible actions you could undertake might be to display a window containing help information, or perhaps load a web page containing support material. The choice is yours – it is totally customizable.

For the benefit of this example however, we are just going to bring up a simple message dialog. We can do that with the following code fragment:

JPedalActionHandler helpAction = new JPedalActionHandler() {
    public void actionPerformed(SwingGUI currentGUI, Commands commands) {
            "Custom help dialog", "JPedal Help", JOptionPane.INFORMATION_MESSAGE);

Injecting a JPedalActionHandler Implementation into the Java PDF viewer

For information on how to embed the Java PDF viewer into your new or existing application, please see here.

Once you have the Java PDF viewer up and running, and you have created your own JPedalActionHandler implementation, you are ready to plug it in. Doing this is easy. The Java PDF viewer exposes the method:

public void addExternalHandler(Object newHandler, int type)

This allows you to customize JPedal in several ways, one of which is to add your own JPedalActionHandler implementations. Because you may wish to override more that one default action, you don’t need to call this method for each custom action. Instead, you can add all your actions to a Map, and then pass the Map into the addExternalHandler method.

For example, in our case where we just want to add one action handler, we simply add our one action to a new HashMap.

Map actions = new HashMap();
actions.put(new Integer(Commands.HELP), helpAction);

Notice how we map our custom help action onto the corresponding HELP command. A full list of possible commands you can override is available in the Commands Class.

Now we have a list of actions to override, we can pass that Map into the addExternalHandler method. This is done as so:

viewer.addExternalHandler(actions, Options.JPedalActionHandler);


Now we have plugged our own default help action into the Java PDF viewer, whenever a user clicks on the Help button, they will see the new custom dialog rather than the default one.

Don’t forget, you can override any command you wish using this method. This means you have the ability to completely customize the behaviour of the Java PDF viewer in any way you wish.

Still need help? Send us your questions.