Geertjan's Blog

  • February 2, 2011

Embedded JavaHelp in a NetBeans Platform Application

Geertjan Wielenga
Product Manager
Some applications may need JavaHelp embedded into the user interface of the application, rather than (or in addition to) being accessible from the "Help" menu item. Something like this, which is by the team at IAV Automotive Engineering in Berlin:

I got some help from Tobias Lehmann today, who is from the IAV team, who told me that the JavaHelp component in the window on the right above is created like this:

public MyHelpBrowser(String initialPage) {
// set up the editor pane
JEditorPane jep = new JEditorPane();
setPage(jep, initialPage);
// set up the window
JScrollPane scrollPane = new JScrollPane(jep);

However, the above implies that you're creating the whole JavaHelp infrastructure from scratch, which makes sense if you're not happy with the default JavaHelp component, which you could add to a TopComponent like this:

import javax.help.JHelp;
import org.my.MyHelpTopComponent;
import org.openide.util.NbBundle;
import org.openide.windows.TopComponent;
import org.netbeans.api.settings.ConvertAsProperties;
import org.openide.awt.ActionID;
import org.openide.awt.ActionReference;
@ConvertAsProperties(dtd = "-//org.my//Help//EN", autostore = false)
@TopComponent.Description(preferredID = "HelpTopComponent", persistenceType = TopComponent.PERSISTENCE_ALWAYS)
@TopComponent.Registration(mode = "properties", openAtStartup = true)
@ActionID(category = "Window", id = "org.my.HelpTopComponent")
@ActionReference(path = "Menu/Window")
@TopComponent.OpenActionRegistration(displayName = "#CTL_HelpAction", preferredID = "HelpTopComponent")
public class MyHelpTopComponent extends TopComponent {
private static JHelp helpViewer = null;
public MyHelpTopComponent() {
setLayout(new BorderLayout());//You can use the Lookup to find the HelpSet,
//because help sets are registered in the Services folder,
//automatically (if you're using the JavaHelp Wizard in the IDE),
//which is accessible from the default Lookup:

HelpSet help = Lookup.getDefault().lookup(HelpSet.class);
helpViewer = new JHelp(help);
add(helpViewer, BorderLayout.CENTER);
public static JHelp getHelpViewer() {
return helpViewer;

By making the help viewer accessible, you can set the current topic via anywhere in your application, e.g:

private void Window1HelpButtonActionPerformed(java.awt.event.ActionEvent evt) {
JHelp helpViewer = MyHelpTopComponent.getHelpViewer();

And the result is as follows, i.e., from anywhere in the application you can specify the current topic in the JavaHelp component:

You might find that the left pane of the JavaHelp component, i.e., its navigator, is taking up too much space. In that case, add:


Now you'll only have the right pane, which still allows you to page back and forward through previously opened topics (and even print individual topics), though you won't have a table of contents (nor an index, nor a search facility) anymore:

If you use the Matisse GUI Builder, you can add the "JHelp" component to the Palette, drag and drop it into a TopComponent, and then integrate it like any other Swing component. You could then create interesting UI components like this:

The above is a starting point. Two areas worth exploring are how to persist the custom size of the JavaHelp component (assuming you're using the navigator pane), i.e., the user resizes the navigator pane of the component and would like that new size to be persisted across restarts, and how to handle multiple help sets, e.g., localized help sets.

Thanks for the help, Tobias!

Join the discussion

Comments ( 2 )
  • Jesse Glick Wednesday, February 2, 2011

    Lookup.getDefault().lookup(HelpSet.class) will return one of the registered help sets if there are multiple. If you wanted to load a particular help set from among many, just create the HelpSet directly based on a URL. Or you can lookupAll(HelpSet.class) and merge the result, as the javahelp module does.

    Handling localized help sets should be trivial - if there are locale variants of HTML pages, they should be loaded automatically when the relevant locale is active.

    Rather than embedding a help viewer, you can also use the NB API to show a particular topic in the standard viewer window.

  • guest Wednesday, April 17, 2013


    Thanks for the tip, we'll be using a similar approach.

    Now I'm interested in the first screenshot, where there is a correlation graph and a regression curve in the window.

    Does anyone know which library was used to diaplay it? We are using JasperReports, but it's not very flexible as it only produces PDFs, asnd we would like to see the results in the window first.

    Thanks a lot!


Please enter your name.Please provide a valid email address.Please enter a comment.CAPTCHA challenge response provided was incorrect. Please try again.