Customise the User Interface in the Java PDF Viewer

The JPedal library contains a Viewer to allow you to view, search, extract and even convert PDF documents. In order to ensure this Viewer will fit your purposes the Viewer uses a properties file to control its appearance and functionality.

Using your own properties file

The Viewer can load properties files in three ways.

  • Specifying a location of a properties file with the “org.jpedal.Viewer.Prefs” VM argument.
    java -Dorg.jpedal.Viewer.Prefs="file://path/to/properties.xml" -jar jpedal.jar --view
  • Providing the properties file path to the Viewer constructors Viewer(String) or Viewer(Accessible, String). The later can be used to embed the Viewer in another application, a detailed tutorial for this can be found here.
    //Create a Viewer object with properties path specified
    Viewer viewer = new Viewer("path/to/properties.xml");
    //Set up the viewer for use
  • Otherwise, JPedal will save and load a file called .properties.xml in the same directory as the JPedal jar.

The VM argument can specify a location within the jar, a server location, or from the local machine by starting the address with jar://, http://, or file://.

If no properties file is present (such as when the Viewer is first opened) the Viewers default properties will be used, and a new file is created when the Viewer closes. This new file is created either in the location specified by the VM argument, if set, or the same directory as the jar.

The properties file

The properties file is a simple xml file with a default name of .properties.xml, although if you are using the “org.jpedal.Viewer.Prefs” VM argument you can give the file any name you wish.

The properties file contains each value in a different element, each preceded by a comment explaining the properties use and value.

Properties file visible in a text editor

If you wish to create your own properties file we recommend you take the default file generated by the Viewer as a starting point and modify the file from there.

The Preferences Window

The JPedal Viewer has a Preferences Window that will allow you to set properties files within the Viewer (although you will need to save and restart the Viewer for all values to take effect). This window can be accessed from the menu item Edit-> Preferences (Ctrl + K).

The preferences window is divided into different views selected using the icons down the left-hand side. Each view focuses on controlling different aspects of the Viewers appearance and functionality.

Once you have set the properties you wish to use and are ready to save them you can either save them directly to the current properties file by using the OK button or to another file leaving the current settings intact using the Save As button.

Image of the preferences window displayiny the Menu view

The preferences window contains a view that allows you to specify which GUI elements you wish to hide, this is the Menu view. The menu is divided into 5 segments on different tabs, each representing a different area of the Viewer. Each tab contains a tree of elements that allow you to specify individual buttons or elements to hide from view, below each of these is a button that allows you to completely remove this element from the GUI.

Image showing the names for each xection of the GUI

If you wish to create your own properties file using this preferences window we recommend you use the preferences file to design the Viewer as you want it and then use Save-as to save the properties into a new file.

Locking the properties

Any user with access to the preferences window can change some of the values in the properties file.

In order to prevent this we suggest you disable the preferences element in your properties file and ensure the properties file is stored in a place the user can not have access such as storing the preferences file within your jar.

However, please note that the recent-documents functionality is handled by storing file names in the properties file. If the file is stored so that it can’t be updated (such as within the jar or making the file read-only) the recent-documents values can’t be updated so values will not be saved when the Viewer closes.

Still need help? Send us your questions.