Help Swing API

The Help Swing API is provided by the docGeneSwingHelp.jar jar file (distributed in the help directory in the binary release). Note that this library is under the BSD license and don't have any dependencies.

Detailed procedure

To create a Help component in Swing:

• Get the URL of the zip file container the help content. 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 and install the model on this viewer:

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

• Get the viewer associated component:

     JComponent pane = viewer.getComponent();    
  

• Alternatively get directly the viewer associated Help window:

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

Managing the help format

Depending on the generated help format^[1]

See DocGenerator Help feature

Additional functionalities

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.

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 StyleSheet theme

Several methods in the HelpContentViewer interface allow to manage the StyleSheet theme of the Help GUI.



The theme used at start will always be the default theme. You can change the theme at runtime at any time by using one of the following methods:

• The HelpContentViewer.setStyleSheetTheme(String) to switch to a named theme
• The HelpContentViewer.resetStyleSheetTheme() to switch to the default theme

Internal html content

resource files and javadoc HTML pages will also be rendered^[2]

The help viewer will try to render resource files different from HTML pages using syntax-coloring for the file extension language

.

HTML pages internal to the help content (different from the articles themselves) will be rendered by default using the JavaFX WebEngine.

• If the WebEngine is not available^[3]
  Such as on a Windows XP Platform
  , the Swing HTML engine will be used
• It is also possible to set explicitly the rendering engine for these HTML pages to be the Swing HTML engine

Forcing the usage of Swing for the rendering

To force the usage of Swing for the rendering, you have to call the SwingHelpContentViewer.setLoadHTMLInSwing(boolean)before performing the install.

For example:

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

      try {
        // create the Help factory
        JavaHelpFactory factory = new JavaHelpFactory(url);
        factory.create();
      
        // create the viewer component
        SwingHelpContentViewer viewer = new SwingHelpContentViewer();
        viewer.setLoadHTMLInSwing(true);
        factory.install(viewer);
      
        JComponent pane = viewer.getHelpComponent();    
        // do whatever you want with the component 
      } catch (IOException | SAXException ex) {
        ex.printStackTrace();
      }

Using the articles model

It is also possible to get the articles model and install the model on the viewer by

   ArticlesModel model = factory.getModel();      
   viewer.installModel(model);    

However getting the underlying articles model is not necessary.

Update the UI of the Swing help component

Calling the ContentViewer.updateUI() wil update the UI of the component managed by the help viewer. it can be useful to use this method if you change the Look and Feel of your application at runtime.

For example:

  UIManager.setLookAndFeel(<new Look and Feel>);
  viewer.updateUI();

Java 9 integration

The Help Swing API is a Java 9 automatic module. The name of the module is org.docgene.help.swing. See ModuleFinder.of(Path...) for more information.

Search in page limitation

The help search in page function is supported only when using a JavaFX Internal html content. Additionally, you will need to specify the --add-opens options to make it available.

Example

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

  try {
    // create the Help factory
    JavaHelpFactory factory = new JavaHelpFactory(url);
    factory.create();
      
    // create the viewer component
    SwingHelpContentViewer viewer = new SwingHelpContentViewer();
    factory.install(viewer);
      
    JComponent pane = viewer.getHelpComponent();    
    // do whatever you want with the component 
  } catch (IOException | SAXException ex) {
    ex.printStackTrace();
  }