Help system tutorial

This article is tutorial which explains how to produce and use a Help content in a Swing application.

You will:

• Generate a zip file containing the help content
• Use this content to create a help system for a Swing application

Create the help content

We will only create three articles for this tutorial:

• The index article:

     <index>
     Tutorial about the help system.
     </index>
  

• A first article:

     <article desc="button 1">
     Article on first button.
     </article>
  

• A second article:

     <article desc="button 2">
     Article on second button.
     </article>
  

• A third article:

     <article desc="several components">
        <title title="third button" />
     The third button.
  
       <title title="text field" />
     The text field.
  
        <title title="panel" />
     The panel.
     </article>
  

Generate the help content

Let's generate our help content. Double-click on the jar file of the application and:

• Input directories: Set your directory
• Output directory: Set another empty directory for the help content result
• Output type: Set "HELP" as the output type
• Click on "Apply"

Now we have a file named articles.zip at the same level as the output directory. This file contains the Help content generated with the content of our wiki^[1]

You should note that as the "Optimized for Swing" checkbox was checked by default, we will have a content which will not be perfectly adapted for integration in a JavaFX application (see help content optimization for more information on that). However in this case as there are no images in the wiki the JavaFX content would be the same as the content generated for Swing

Note the structure of the zip file:

      articles
      resources
      -- articles.xml
      -- index.html
      -- README.txt

The articles.xml contains the names and the paths of all the articles of the wiki, which will be used by the Help System.

Create our Swing application

In our example we will just use a JFrame which will show the content of our help system upon clicking on a Menu item. First we will create our very simple application with a MenuBar but without our help system:

   public class SwingJavaHelp extends JFrame {

     public SwingJavaHelp {
       super();
       this.setTitle("DocGenerator Help Tutorial");
       createLayout();
       this.setDefaultCloseOperation(JFrame.EXIT_ON_CLOSE);
     }

     private void createContent(Container cont) {
       JPanel areaPanel = new JPanel();
       areaPanel.setLayout(new BorderLayout());
       areaPanel.setBorder(new EmptyBorder(10, 10, 10, 10));
       JTextArea area = new JTextArea();
       area.setText("my area content");
       areaPanel.add(area, BorderLayout.CENTER);
      cont.add(areaPanel, BorderLayout.CENTER);
     }

     private void createMenu() {
       JMenuBar menuBar = new JMenuBar();
      this.setJMenuBar(menuBar);
       JMenu menu = new JMenu("Help");
       menuBar.add(menu);
       AbstractAction helpAction = new AbstractAction("Help Content") {
         @Override
         public void actionPerformed(ActionEvent e) {
         }
       };
       menu.add(helpAction);
     }

      private void createLayout() {
       Container cont = this.getContentPane();
       cont.setLayout(new BorderLayout());

       createContent(cont);
       createMenu();
     }

     public static void main(String[] args) {
       SwingJavaHelp helper = new SwingJavaHelp();
       helper.setSize(400, 400);
       helper.setVisible(true);
     }
   }

Integrating the help content in our Swing application

Now we will integrate a Help system with our Help content in this application.

Before we add our help system, copy the generated articles.zip alongside our application. First we need to initialize our Help factory:

      public SwingJavaHelp() {
        super();
        this.setTitle("DocGenerator Help Tutorial");
        createFactory();
        createLayout();
        this.setDefaultCloseOperation(JFrame.EXIT_ON_CLOSE);
      }

      
         private void createFactory() {
           URL url = this.getClass().getResource("resources/articles.zip");

           factory = new JavaHelpFactory(url);
           try {
             factory.create();
           } catch (IOException | SAXException ex) {
             ex.printStackTrace();
           }
         }

Now we will create a SwingHelpContentViewer, install the Help content on this viewer, and create our HelpWindow:

   private void createLayout() {
     Container cont = this.getContentPane();
     cont.setLayout(new BorderLayout());

      
     try {
       viewer = new SwingHelpContentViewer();
       factory.install(viewer);
       viewer.getHelpWindow(this, "Help Content", 600, 700);
     } catch (IOException ex) {
       ex.printStackTrace();
     }
      
     createContent(cont);
   }

The last step is to wire our help item to the help content:

      private void createMenu() {
        JMenuBar menuBar = new JMenuBar();
        this.setJMenuBar(menuBar);
        JMenu menu = new JMenu("Help");
        menuBar.add(menu);
        AbstractAction helpAction = new AbstractAction("Help Content") {
          @Override
          public void actionPerformed(ActionEvent e) {
            viewer.showHelpDialog(menu);
          }
      };
        menu.add(helpAction);
      }

See the full source code for the example

Now its done. Let's understand more precisely what we did:

• Get the URL of the zip file container the help content. This URL have been generated by the help content generation
• Create the JavaHelpFactory:

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

• Create a SwingHelpContentViewer and install the model on this viewer:

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

• In this case we created the Help window by viewer.getHelpWindow(this, "Help Content", 600, 700) but we did not need in this case to use this Window directly. It is performed by the viewer.showHelpDialog(menu) code. We could have use the Help window or directly get the Help component by viewer.getHelpComponent()

Launch our application

Now the help system is integrated in our Swing application, and the following Window appear upon clicking on the "Load" menu item: