How can I override JavaHelp to display my own help or documentation?

Apache NetBeans Wiki Index

Note: These pages are being reviewed.

Step 1: HelpCtx.Displayer

First, you must create a HelpCtx.Displayer that is capable of displaying your help and register it as a service provider

@ServiceProviders({
    @ServiceProvider(service = HelpCtx.Displayer.class, position = 1000)
})
public class CustomHelpDisplayer implements HelpCtx.Displayer {

    public boolean display(final HelpCtx helpCtx) {

        // Put your displaying code here.
        JOptionPane.showMessageDialog(
                WindowManager.getDefault().getMainWindow(),
                helpCtx.getHelpID());

        return true;
    }
}

Step 2: Help.class

An instance of org.netbeans.api.javahelp.Help determines what to do with a particular HelpCtx. In order to use your custom help displayer, you need to create an instance of Help that can display using your custom help displayer. In this case, you want to override the Help class provided with the NetBeans platform, so you set the 'position' attribute low. The purpose of this class is two-fold:

  • If the HelpCtx.getHelpID() is a value we recognize and can use, we display it with our displayer. For our example below, we handle any help ID that starts with "PREFIX."

  • If not, we pass it on to the default help system.

@ServiceProviders({
    @ServiceProvider(service = Help.class, position = 1)
})
public class CustomHelp extends Help {

    @Override
    public Boolean isValidID(final String id, final boolean force) {
        // We return true because even if it's not a valid ID for our purposes, we just pass it
        // to the default help and let it deal with it.
        return true;
    }

    @Override
    public void showHelp(final HelpCtx ctx, final boolean showmaster) {

        // Here, we examine the ID and if it starts with "PREFIX", we find our implementation
        // of HelpCtx.Displayer using the Lookup API and use it to display our help.
        if (ctx.getHelpID().startsWith("PREFIX")) {

            final HelpCtx.Displayer displayer =
                    Lookup.getDefault().lookup(HelpCtx.Displayer.class);

            displayer.display(ctx);
        }

        // If we don't know what do with the ID, we find all the implementations of Help and
        // pass the HelpCtx along to the first one we find that isn't this class.
        else {
            final Collection<? extends Help> helps =
                    Lookup.getDefault().lookupAll(Help.class);

            for (Help help : helps) {
                if (help != this) {
                    help.showHelp(ctx, showmaster);

                    break;
                }
            }
        }
    }

    @Override
    public void addChangeListener(final ChangeListener listener) {
        // *** Not sure what to do here.
    }

    @Override
    public void removeChangeListener(final ChangeListener listener) {
        // *** Not sure what to do here.
    }
}

Step 3: Connecting UI To JavaHelp

See Connecting Help In NetBeans.

Step 4: Add the JavaHelp Integration Module

This module is not "eager", so to force it to load, at least one module must depend on it. Simply make JavaHelp Integeration a dependency of one your modules to make Help available. The JavaHelp Integration module is in the 'platform' library.

Summary: Putting It All Together

  • Your UI provides the HelpCtx.

  • The CustomHelp class (invoked when the user launches help, usually by pressing F1) examines help IDs.

  • If it’s one we recognize, we invoke our custom displayer.

  • If it’s not, we hand it off to another Help instance.

Applies to: NetBeans IDE 7.2 Platforms: All