Back to Basics: Adding Button Fields using the Datalogics PDF Java Toolkit

Back to Basics: Adding Button Fields using the Datalogics PDF Java Toolkit

Sample of the Week:

It’s still Back to Basics Month here at Sample of the Week. This week we’ll use the Datalogics PDF Java Toolkit to add a button field to a PDF page, assign the icons for the various button states, and then add some JavaScript to track the different events that get triggered when a user interacts with the button. This sample will also demonstrate how to copy PDF content from one document to another.

The AppearanceService in the Datalogics PDF Java Toolkit makes it very easy to create the default appearances for button fields that only use a text label for their appearance. What the AppearanceService can’t do for you automatically is create the icons that you might want to use as button appearances; even in the Acrobat interface, we need to pull those in from other PDF files or images.

If you’ve done any form authoring in Adobe Acrobat, you’ll recognize the two dialog boxes below. This is the area where you define what a button will look like and what it will do. The Gist that I discuss in this article replicates the functionality of these dialogs.


We start by reading in the two PDF files that we need to run the sample; a blank input file that we are going to add a button to and the PDF file that has three pages, one page for each button icon representing the different states, Up, Over, and Down.

The we get the first page, define the location of the button we want to add, add it, and then set it to be a PushButton

At this point we now have a default button field defined in the AcroForm dictionary of the PDF file and a button field widget on the first page of the PDF. We can now create our appearance object and assign it to the button field widget. We do this by creating PDFXObjectForm objects from the PDF pages in the file that we want to get our button icons from. From the button field that we added, we can locate the corresponding widget on the first page and then assign it’s appearance.

Now we have a button that will appear differently when the user interacts with it. It has a normal (or “Up” ) state, a rollover state and a down state that appears when the user clicks it.

But for the user interaction to effect a change in the document, we need to add some scripts and associate them with the various event triggers for Acrobat buttons. The JavaScript that you want to associate with an event gets added as a string so you’ll need to be familiar with Acrobat JavaScript first to make really good use of this capability in the Datalogics PDF Java Toolkit.

As a convenience, the Gist also adds some code to the PDF file so that, in Acrobat, it opens the JavaScript console so you can see the messages that the button events generate.

Finally, we need to do a little bit of clean up.  Button fields can be Push Buttons, CheckBoxes, or Radio Buttons. CheckBoxes and Radio Buttons have values and possibly children, Push Buttons do not. Unfortunately, an artifact of the Java Toolkit class that creates these buttons is a set of default values that are not needed by Push Buttons and actually interfere with Acrobat’s ability to display the buttons properly. We just need to remove them and everything works.

Using the techniques outlined in this article, developers can dynamically add buttons to PDF files that respond to user interaction, submitting the PDF file back to your server, sending it via email, checking it into a document repository or just about anything else you can think of.

Leave a Reply

Your email address will not be published. Required fields are marked *