Help API overview

This library is under the BSD license and don't have any dependencies.

The generated help content can be used either for a Swing or JavaFX application. The help content will be presented in a component which can be integrated in any GUI. The Swing and the JavaFX APIs are very similar:

• Help Swing API for using the Swing API. The Help Swing API is provided by the docGeneSwingHelp.jar jar file
• Help JavaFX API for using the JavaFX API. The Help JavaFX API is provided by the docGeneJFXHelp.jar jar file

API usage

To create a Help component:

• Get the URL of the zip file containing the help content^[1]
  See content of the help zip file for what this zip file containes
  . This URL have been generated by the help content generation
• Create the JavaHelpFactory. For example:

     JavaHelpFactory factory = new JavaHelpFactory(url);
     factory.create();
  

• Create a SwingHelpContentViewer (or JFXHelpContentViewer for JavaFX) and install the model on this viewer. For example for Swing:

    SwingHelpContentViewer viewer = new SwingHelpContentViewer();
    factory.installModel(viewer);
  

• Get the viewer associated component. For example for Swing:

     JComponent pane = viewer.getComponent();
  

• Alternatively get directly the viewer associated Help window (or Stage for JavaFX). For example for Swing:

     JDialog dialog = viewer.getHelpWindow(myParentFrame, <Help Content Title>, width, height);
  

Reloading the help content

It is possible to reload a new Help content by calling again JavaHelpFactory.install(HelpContentViewer), with a factory created with the new content.

For example this code is functional:

  JavaHelpFactory factory = new JavaHelpFactory(url);
  factory.create();

  SwingHelpContentViewer viewer = new SwingHelpContentViewer();
  factory.installModel(viewer);

  factory = new JavaHelpFactory(url);
  factory.create();
  factory.installModel(viewer);

Note that the viewer associated component will remain the same.

Merging help contents

It is possible to merge more than one Help content by using the JavaHelpFactory.merge(URL) method. For example, if you want to use two zip files to create your help model, you can write:

  // get the first zip file as an URL
  URL url = ...      
  // create the JavaHelpFactory with the first zip file
  JavaHelpFactory factory = new JavaHelpFactory(url);
  factory.create();      
      
  // get the second zip file as an URL
  URL url2 = ... 
      
  // cmerge the content of this zip file with the first one
  factory.merge(url2);                     

Using an alternate stylesheet

By default the StyleSheet which will be used to show the html content is in the "resources/stylesheet.css" file in the zip file containing the main help content.

It is possible to set an altenate CSS by specifying it in the Help content configuration. For example:

   <helpContent>
      <styleSheets defaultStyleSheet="myStyleSheet.css" />
   </helpContent>

Setting the index path

By default the path of the index entry in the zip file containing the main help content is the "resources/index.html" file.

It is possible to specify your own path by JavaHelpFactory.setIndexPath(String).

For example:

   // get the zip file as an URL
   URL url = ...      
      
   // create the JavaHelpFactory with the first zip file
   JavaHelpFactory factory = new JavaHelpFactory(url);
             
   // set the index path
   factory.setIndexPath("myHomePage.html");
      
   // create the factory
   factory.create();       

Setting the help GUI icons

Several methods in the HelpContentViewer interface allow to set the URL of the icons used in the help GUI.

Setting the toolbar icons

• The HelpContentViewer.setArticleIcon(URL) method set the icon for articles in the tree
• The HelpContentViewer.setExpandedChapterIcon(URL) method set the icon for expanded chapters in the tree
• The HelpContentViewer.setClosedChapterIcon(URL) method set the icon for closed chapters in the tree

Setting the tree icons

The HelpContentViewer.setIcon(String, URL) method allow to set the icons for buttons:

• HelpContentViewer.setIcon(HelpContentViewer.ICON_HOME, URL) for the home button
• HelpContentViewer.setIcon(HelpContentViewer.ICON_FORWARD, URL) for the forward button
• HelpContentViewer.setIcon(HelpContentViewer.ICON_BACKWARD, URL) for the backward button
• HelpContentViewer.setIcon(HelpContentViewer.ICON_GLOSSARY, URL) for the glossary button

Setting the context help icons

• The HelpContentViewer.setContextHelpIcon(URL) method set the icon for the content help
• The HelpContentViewer.setContextHelpPointerImage(URL) method set the image for the content help pointer

Example

  SwingHelpContentViewer viewer = new SwingHelpContentViewer();
  viewer.installModel(model);

  viewer.setArticleIcon(<icon URL>);

Setting the help locale

By default the localization of the help GUI is the Platform default localization but it is possible to change it.

Using the API with manually produced content

Even if docJGenerator can generate the Help content automatically, it is possible to produce the Help content manually. See Using the Help API with manually produced content.

Example with Swing

  // get the zip file as an URL
  URL url = ...

  try {
    // create the Help factory
    JavaHelpFactory factory = new JavaHelpFactory(url);
    factory.create();
    ArticlesModel model = factory.getModel();

    // create the viewer component
    SwingHelpContentViewer viewer = new SwingHelpContentViewer();
    viewer.installModel(model);

    JComponent pane = viewer.getComponent();
    // do whatever you want with the component
  } catch (IOException | SAXException ex) {
    ex.printStackTrace();
  }