Class HelpMenuItem

All Implemented Interfaces:
ImageObserver, ItemSelectable, MenuContainer, Serializable, Accessible, MenuElement, SwingConstants

public class HelpMenuItem extends JMenuItem
A menu item for displaying help. Menu items of this type should be installed in a 'help' menu. A URL provides the contents of a help window, which contains either an HTML file suitable for an HtmlPane (basically HTML 3.2) or an XML file suitable for an HtmlWithTocPane. If the URL's path ends with the suffix"xml" (".xml"), an HtmlWithTocPane is used; otherwise an HtmlPane is used. A description of the XML format can be found in the documentation for HtmlWithTocPane.

Once the frame is created, it will persist for the lifetime of an application. Closing a window simply makes the frame invisible. This allows the help window to maintain its state as the application runs. Constructors may also provide a resource-bundle name and keys for the menu-item title, URL, and help-frame title.

If some or all of the Help HTML files are stored in an application's JAR file or JAR files, on can use the "sresource" or "resource" URL scheme to access them. In this case one should call the method Handlers.enable() in order to enable the "resource" and "sresource" URL schemes. It may also be necessary to set some Java properties (e.g., with the java -D option).

As an example, Suppose the file toc.xml is accessed using the URL file:///PATH/toc.xml, where PATH should be replace by a path from the root directory to the directory that contains toc.xml, and that toc.xml contains the following:


  <?xml version="1.0" ?>
 <!DOCTYPE toc SYSTEM "sresource:/org/bzdev/swing/toc.dtd">
 <toc>
   <node title="table of contents" uri="file:///PATH/manual.html" >
     <node title="chapter1" uri="file:///PATH/manual.html#gui" />
     <node title="chapter2" uri="file:///PATH/manual.html#output" >
       <node title="Section1" uri="file:///PATH/manual.html#request" />
       <node title="Section2" uri="file:///PATH/manual.html#prefs" />
       <node title="Section3" uri="file:///PATH/manual.html#menus" />
     </node>
     <node title="chapter3" uri="file:///PATH/manual.html#terminal" />
   </node>
 </toc>
 
Also suppose that the file manual.html is accessed using the URL file:///PATH/manual.html and that manual.html is an HTML 3.2 file with anchors names "gui", "output", "request", "prefs", menus", and "terminal". Then the following code will create on-line help for an application and make it accessible from a "Help" menu.

    JFrame frame = new JFrame("Application");
    JMenuBar menubar = new JMenuBar();
    ...
    JMenuItem helpMenuItem =
       new HelpMenuItem("Help", "file:///PATH/toc.xml",
                          "Help", 800, 600);
    JMenu helpMenu = new JMenu("Help");
    helpMenu.add(helpMenuItem);
    menubar.add(helpMenu);
    ...
    frame.setJMenuBar(menubar);
    ...
 
Other constructors can be used when internationalization is needed. For a HelpMenuItem, the internationalized constructors uses a resource bundle to look up the titles and uris based on a locale.
See Also:
  • Constructor Details

    • HelpMenuItem

      public HelpMenuItem(String menuItemName, String url, String title, int xsize, int ysize) throws IOException
      Constructor.
      Parameters:
      menuItemName - the name to use in the menu item created
      url - the URL for the help-frame's HTML or XML file
      title - the title of the help frame
      xsize - the horizontal size of the frame in points
      ysize - the vertical size of the frame in points
      Throws:
      IOException - the URL could not be loaded
    • HelpMenuItem

      public HelpMenuItem(String menuItemName, String url, String title, int xsize, int ysize, String dmURL) throws IOException
      Constructor with a dark mode option.
      Parameters:
      menuItemName - the name to use in the menu item created
      url - the URL for the help-frame's HTML or XML file
      title - the title of the help frame
      xsize - the horizontal size of the frame in points
      ysize - the vertical size of the frame in points
      dmURL - the help-frame's URL for dark mode.
      Throws:
      IOException - the URL could not be loaded
    • HelpMenuItem

      public HelpMenuItem(String bundleName, String menuItemNameKey, String urlKey, String titleKey, int xsize, int ysize) throws IOException
      Constructor using resource bundles. A resource bundle is used to look up the menu-title, help-frame URL, and help-frame title, from keys, with the names of the keys provided as arguments.
      Parameters:
      bundleName - the name of the resource bundle used to configure the help frame.
      menuItemNameKey - the bundle's key for the title to use in the menu item created
      urlKey - the bundle's key for the URL
      titleKey - the bundle's key for the title of the help frame
      xsize - the horizontal size of the help frame in points
      ysize - the vertical size of the help frame in points
      Throws:
      IOException - the URL could not be loaded
    • HelpMenuItem

      public HelpMenuItem(String bundleName, String menuItemNameKey, String urlKey, String titleKey, int xsize, int ysize, String dmUrlKey) throws IOException
      Constructor using resource bundles with a dark mode option. A resource bundle is used to look up the menu-title, help-frame URL, and help-frame title, from keys, with the names of the keys provided as arguments.
      Parameters:
      bundleName - the name of the resource bundle used to configure the help frame.
      menuItemNameKey - the bundle's key for the title to use in the menu item created
      urlKey - the bundle's key for the URL
      titleKey - the bundle's key for the title of the help frame
      xsize - the horizontal size of the help frame in points
      ysize - the vertical size of the help frame in points
      dmUrlKey - the bundle's key for the content's dark-mode URL
      Throws:
      IOException - the URL could not be loaded
    • HelpMenuItem

      public HelpMenuItem(Locale locale, String bundleName, String menuItemNameKey, String urlKey, String titleKey, int xsize, int ysize) throws IOException
      Constructor given a locale and resource bundle. A resource bundle is used to look up the menu-title, help-frame URL, and help-frame title, from keys, with the names of the keys provided as arguments.
      Parameters:
      locale - the locale
      bundleName - the name of the resource bundle
      menuItemNameKey - the bundle's key for the title to use in the menu item created
      urlKey - the bundle's key for the content's URL
      titleKey - the bundle's key for the title of the help frame
      xsize - the horizontal size of the help frame in points
      ysize - the vertical size of the help frame in points
      Throws:
      IOException - the URL could not be loaded
    • HelpMenuItem

      public HelpMenuItem(Locale locale, String bundleName, String menuItemNameKey, String urlKey, String titleKey, int xsize, int ysize, String dmUrlKey) throws IOException
      Constructor given a locale and resource bundle with a dark mode option. A resource bundle is used to look up the menu-title, help-frame URL, and help-frame title, from keys, with the names of the keys provided as arguments.
      Parameters:
      locale - the locale
      bundleName - the name of the resource bundle
      menuItemNameKey - the bundle's key for the title to use in the menu item created
      urlKey - the bundle's key for the content's URL
      titleKey - the bundle's key for the title of the help frame
      xsize - the horizontal size of the help frame in points
      ysize - the vertical size of the help frame in points
      dmUrlKey - the bundle's key for the content's dark-mode URL
      Throws:
      IOException - the URL could not be loaded
  • Method Details