Help JavaFX API

The Help Swing API is provided by the docGeneJFXHelp.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 JavaFX:

• 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 JFXHelpContentViewer and install the model on this viewer:

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

• Get the viewer associated Node:

     Node pane = viewer.getComponent();    
  

• Alternatively get directly the viewer associated Help Stage:

     Stage helpStage = viewer.getHelpWindow(myParentStage, <Help Content Title>, width, height);    
  

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

Resources files and javadoc content

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

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

.

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.

Java 9 integration

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

Search in page limitation

You will need to specify the --add-opens options to make the help search in page function 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
    JFXHelpContentViewer viewer = new JFXHelpContentViewer();
    factory.install(viewer);
      
    Node pane = viewer.getComponent();    
    // do whatever you want with the Node 
  } catch (IOException | SAXException ex) {
    ex.printStackTrace();
  }