Module org.bzdev.desktop
Package org.bzdev.swing

Class HtmlWithTocPane

java.lang.Object
java.awt.Component
java.awt.Container
javax.swing.JComponent
org.bzdev.swing.HtmlWithTocPane
All Implemented Interfaces:
ImageObserver, MenuContainer, Serializable, TocTree, UrlTocTree
public class HtmlWithTocPane extends JComponent implements UrlTocTree
Class providing an HTML Pane combined with a side panel showing a table of contents. One may initialize the class or set the table of contents by providing an XML document with the following DTD: 
 <!ELEMENT toc (node) >
 <!ELEMENT node (node)*>
 <!ATTLIST node 
              title CDATA #IMPLIED
              uri   CDATA #IMPLIED
              href  CDATA #IMPLIED
 >
A DOCTYPE directive is not necessary - the DTD above will be assumed. If a DOCTYPE directive is desired (e.g, for documentation reasons), one should use "sreource:/org/bzdev/swing/toc.dtd". For each node element, the titleattribute will be the title that appears in a table-of-contents panel and the uri attribute provides the URI for the contents for that title. The contents should be an HTML document using HTML 3.2 the HTML version that Java supports (Java is slowly migrating to full HTML 4.0 support but this class uses whatever the standard Java runtime environment supports). The href attribute is ignored by HtmlWithTocPane and is provided in case the XML file is also used by a web server, in which case the URL it needs to use may be different than the one provided by the uri attribute.

After the document is loaded (e.g., by using one of the constructors for this class), one should call setSelectionWithAction(row) to select the initial row and the corresponding URL. This will almost always be row 0. If setSelectionWithAction is not called, no initial contents will appear in the HTML portion of the pane.

To initialize the class manually, use the same procedure as for an instance of the class UrlTocPane. A number of method signatures are borrowed from the JSplitPane class (with some of the Javadoc comments) and simply call the corresponding JSplitPane methods (but with 'left' and 'right' replaced by the edges closest to the TOC pane and HTML pane respectively.

When an instance of this class is no longer needed, one should call clearToc() to release some resources.

See Also:

  • Constructor Details

  • Method Details

    • setComponentOrientation

      public void setComponentOrientation(ComponentOrientation o)
      Overrides:
      setComponentOrientation in class Component

    • setLocale

      public void setLocale(Locale locale)
      Overrides:
      setLocale in class Component

    • setContentLocale

      public void setContentLocale(Locale locale)
      Set the local of the content pane. This method allows the locale of the content panes (the table of contents and its corresponding HTML pane) to be set without changing the layout of navigation controls.
      Parameters:
      locale - the locale.

    • getSplitPaneBorder

      public Border getSplitPaneBorder()
      Get the border for this component's split pane.
      Returns:
      the border

    • setSplitPaneBorder

      public void setSplitPaneBorder(Border border)
      Set the border for this component's split pane.
      Parameters:
      border - the border

    • getTocPaneBorder

      public Border getTocPaneBorder()
      Get the border for this component's table of contents.
      Returns:
      the border

    • setTocPaneBorder

      public void setTocPaneBorder(Border border)
      Set the border for this component's table of contents.
      Parameters:
      border - the border

    • getHtmlPaneBorder

      public Border getHtmlPaneBorder()
      Get the border for this component's HTML pane.
      Returns:
      the border

    • setHtmlPaneBorder

      public void setHtmlPaneBorder(Border border)
      Set the border for this component's HTML pane.
      Parameters:
      border - the border

    • getContentPaneBorder

      public Border getContentPaneBorder()
      Get the border for this component's contents.
      Returns:
      the border

    • setContentPaneBorder

      public void setContentPaneBorder(Border border)
      Set the border for this component's contents.
      Parameters:
      border - the border

    • getTocPreferredSize

      public Dimension getTocPreferredSize()
      Get the preferred size for the TOC pane.
      Returns:
      the preferred size

    • getHtmlPanePreferredSize

      public Dimension getHtmlPanePreferredSize()
      Get the preferred size for the HTML pane.
      Returns:
      the preferred size

    • setTocPreferredSize

      public void setTocPreferredSize(Dimension preferredSize)
      Set the preferred size for the Table of Contents pane.
      Parameters:
      preferredSize - the preferred size

    • setHtmlPanePreferredSize

      public void setHtmlPanePreferredSize(Dimension preferredSize)
      Set the preferred size for the HTML pane.
      Parameters:
      preferredSize - the preferred size

    • setBackground

      public void setBackground(Color color)
      Set the background color. This method will also set the background color of scroll bars unless the last call to setTocScrollbarBackground(Color) or setHtmlPaneScrollbarBackground(Color) if any were made, had a non-null argument, which explicitly sets the background color for the corresponding scrollbars.

      Note: with some pluggable look and feels, this method may be fully or partially ignored. It works as expected with the default look and feel.

      Overrides:
      setBackground in class JComponent
      Parameters:
      color - the color

    • setTocScrollbarBackground

      public void setTocScrollbarBackground(Color color)
      Set the background color for the table of contents scroll bars. If color is null and the last call to setBackground(Color), if one was made, had a non-null argument, that background color will be used. If the last call to setBackground(Color) had a null argument, the color passed as an argument will be used.

      Note: with some pluggable look and feels, this method may be fully or partially ignored. It works as expected with the default look and feel.

      Parameters:
      color - the color; null for the default color

    • setHtmlPaneScrollbarBackground

      public void setHtmlPaneScrollbarBackground(Color color)
      Set the background color for the HTML pane scroll bars. If color is null and the last call to setBackground(Color), if one was made, had a non-null argument, that background color will be used. If the last call to setBackground(Color) had a null argument, the color passed as an argument will be used.

      Note: with some pluggable look and feels, this method may be fully or partially ignored. It works as expected with the default look and feel.

      Parameters:
      color - the color; null for the default color as modified by the last call (if any) to setBackground(Color)

    • setHtmlButtonBackground

      public void setHtmlButtonBackground(Color color, boolean rvmode)
      Set the background color for the 'start', 'back', 'reload', 'forward', and 'end' controls. When rvmode is true, the icons will be white when enabled and grey when disabled, the reverse from the normal behavior.

      Note: with some pluggable look and feels, this method may be fully or partially ignored. It works as expected with the default look and feel.

      Parameters:
      color - the color
      rvmode - true for reverse video; false otherwise

    • setSplitterBackground

      public void setSplitterBackground(Color color)
      Set the background color of the splitter (or divider).

      Note: with some pluggable look and feels, this method may be fully or partially ignored. It works as expected with the default look and feel.

      Parameters:
      color - the color

    • setHtmlPaneBackground

      public void setHtmlPaneBackground(Color color)
      Set the background color for the HTML pane.

      Note: sometimes the background color for the HTML pane will be visible such as when the HTML code is being loaded and this method can produce a suitable color for this case.

      Note: with some pluggable look and feels, this method may be fully or partially ignored. It works as expected with the default look and feel.

      Parameters:
      color - the color

    • resetToPreferredSizes

      public void resetToPreferredSizes()
      Reset the split pane to the preferred sizes. This must be called after individual preferred sizes are set for those to have any effect. The divider may move as a result of using this method.

    • setDividerLocation

      public void setDividerLocation(double proportionalLocation)
      Sets the divider location as a percentage of the HtmlWithTocPane's size.

      This method is implemented in terms of setDividerLocation(int). This method immediately changes the size of the split pane based on its current size. If the split pane is not correctly realized and on screen, this method will have no effect (new divider location will become (current size * proportionalLocation) which is 0).

      Parameters:
      proportionalLocation - a double-precision floating point value that specifies a percentage, from zero (The TOC side of the component) to 1.0 (the HTML Pane side of the component)

    • getDividerLocation

      public int getDividerLocation()
      Returns the last value passed to setDividerLocation. The value returned from this method may differ from the actual divider location (if setDividerLocation was passed a value bigger than the current size).
      Returns:
      an integer specifying the location of the divider

    • setDividerLocation

      public void setDividerLocation(int location)
      Sets the location of the divider. This is passed off to the look and feel implementation, and then listeners are notified. A value less than 0 implies the divider should be reset to a value that attempts to honor the preferred size of the TOC component.
      Parameters:
      location - an integer specifying the location of the divider measured from the right or left hand edge adjacent to the TOC pane.

    • setResizeWeight

      public void setResizeWeight(double weight)
      Specifies how to distribute extra space when the size of the split pane changes. A value of 0, the default, indicates the right/bottom component gets all the extra space (the left/top component acts fixed), where as a value of 1 specifies the left/top component gets all the extra space (the right/bottom component acts fixed). Specifically, the left/top component gets (weight * diff) extra space and the right/bottom component gets (1 - weight) * diff extra space.
      Parameters:
      weight - as described above

    • getResizeWeight

      public double getResizeWeight()
      Returns the number that determines how extra space is distributed.
      Returns:
      how extra space is to be distributed on a resize of the split pane contained in this component.

    • addEntry

      public void addEntry(String title, Object obj)
      Description copied from interface: TocTree
      Add a new node to the tree, giving it a name.
      Specified by:
      addEntry in interface TocTree
      Parameters:
      title - A string naming the node.
      obj - The object that represents the value of the node.
      See Also:

    • addEntry

      public void addEntry(String title, String url) throws MalformedURLException
      Description copied from interface: UrlTocTree
      Add an entry. This will define a new TOC entry.
      Specified by:
      addEntry in interface UrlTocTree
      Parameters:
      title - A string naming the entry.
      url - The URL to associate with the entry;
      Throws:
      MalformedURLException - if the url is malformed
      See Also:

    • addEntry

      public void addEntry(String title, URL url) throws MalformedURLException
      Description copied from interface: UrlTocTree
      Add an entry. This will define a new TOC entry.
      Specified by:
      addEntry in interface UrlTocTree
      Parameters:
      title - A string naming the entry.
      url - The URL to associate with the entry;
      Throws:
      MalformedURLException - if the url is malformed
      See Also:

    • nextLevel

      public void nextLevel()
      Description copied from interface: TocTree
      Add a new level to the tree rooted at the last node entered.
      Specified by:
      nextLevel in interface TocTree
      See Also:

    • prevLevel

      public void prevLevel()
      Description copied from interface: TocTree
      Return to the previous level in the tree.
      Specified by:
      prevLevel in interface TocTree
      See Also:

    • entriesCompleted

      public void entriesCompleted()
      Description copied from interface: TocTree
      Assert that no more entries will be added. A call to this method will complete construction of the tree. It is equivalent to calling entriesCompleted(false).
      Specified by:
      entriesCompleted in interface TocTree
      See Also:

    • entriesCompleted

      public void entriesCompleted(boolean expand)
      Description copied from interface: TocTree
      Assert that no more entries will be added. A call to this method will complete construction of the tree.
      Specified by:
      entriesCompleted in interface TocTree
      Parameters:
      expand - true if all nodes should be expanded before the tree is displayed; false if no nodes should be expanded
      See Also:

    • setSelectionWithAction

      public void setSelectionWithAction(int row)
      Description copied from interface: TocTree
      Set the selection and perform an action. This method should be called after the call to entriesCompleted. It sets the selected object and calls fireActionPerformed(). Rows are indexed with 0 indicating the first visible node and with only visible nodes counted, regardless of whether these nodes are displayable. Expanding or collapsing nodes changes the indexing. Changing the portion of the pane that is shown in the display does not change the indexing. At the time this description was written, the JTree documentation was somewhat obscure regarding how this indexing works.
      Specified by:
      setSelectionWithAction in interface TocTree
      Parameters:
      row - the row to select.

    • clearSelection

      public void clearSelection()
      Description copied from interface: TocTree
      Clear the selection. This method also generates action events with the source set to an entry with a null title and a null object.
      Specified by:
      clearSelection in interface TocTree

    • addActionListener

      public void addActionListener(ActionListener l)
      Description copied from interface: TocTree
      Add an action listener.
      Specified by:
      addActionListener in interface TocTree
      Parameters:
      l - the action listener to add.

    • removeActionListener

      public void removeActionListener(ActionListener l)
      Description copied from interface: TocTree
      Remove an action listener.
      Specified by:
      removeActionListener in interface TocTree
      Parameters:
      l - the action listener to remove.

    • collapseRow

      public void collapseRow(int row)
      Description copied from interface: TocTree
      Ensures that the node in the specified row is collapsed. If row is < 0 or ≥ getRowCount this will have no effect.
      Specified by:
      collapseRow in interface TocTree
      Parameters:
      row - an integer specifying a row, where 0 is the first viewable row.

    • expandRow

      public void expandRow(int row)
      Description copied from interface: TocTree
      Ensures that the node in the specified row is expanded and viewable. If row is < 0 or ≥ getRowCount this will have no effect.
      Specified by:
      expandRow in interface TocTree
      Parameters:
      row - an integer specifying a display row, where 0 is the first viewable row.

    • isCollapsed

      public boolean isCollapsed(int row)
      Description copied from interface: TocTree
      Returns true if the node at the specified display row is collapsed.
      Specified by:
      isCollapsed in interface TocTree
      Parameters:
      row - the row to check, where 0 is the first viewable row.
      Returns:
      true if the node is currently collapsed, otherwise false

    • isExpanded

      public boolean isExpanded(int row)
      Description copied from interface: TocTree
      Returns true if the node at the specified display row is currently expanded.
      Specified by:
      isExpanded in interface TocTree
      Parameters:
      row - he row to check, where 0 is the first viewable row.
      Returns:
      true if the node is currently expanded, otherwise false

    • clearToc

      public void clearToc()
      Description copied from interface: TocTree
      Clear the table of contents and puts it in a state where entries can be added.
      Specified by:
      clearToc in interface TocTree

    • setToc

      public void setToc(URL url, boolean expand, boolean validating) throws FactoryConfigurationError, SAXException, IOException, ParserConfigurationException, MalformedURLException
      Description copied from interface: UrlTocTree
      Set the table of contents from a URL. This method should be used as as an alternative to addEntry, nextLevel, prevLevel and entriesCompleted
      Specified by:
      setToc in interface UrlTocTree
      Parameters:
      url - the URL containing the table of contents.
      expand - True if the nodes should be expanded; false otherwise
      validating - True if the parser is validating; false otherwise
      Throws:
      FactoryConfigurationError - the XML parser cannot be configured
      SAXException - the XML data in the input stream in not well formed or is not valid.
      IOException - an IO error was seen
      MalformedURLException - if the url is malformed
      ParserConfigurationException - the XML parser cannot be configured

    • setToc

      public void setToc(String url, boolean expand, boolean validating) throws FactoryConfigurationError, SAXException, IOException, ParserConfigurationException
      Description copied from interface: UrlTocTree
      Set the table of contents from a URL represented as a String. This method should be used as as an alternative to addEntry, nextLevel, prevLevel and entriesCompleted
      Specified by:
      setToc in interface UrlTocTree
      Parameters:
      url - the URL containing the table of contents.
      expand - True if the nodes should be expanded; false otherwise
      validating - True if the parser is validating; false otherwise
      Throws:
      FactoryConfigurationError - the XML parser cannot be configured
      SAXException - the XML data in the input stream in not well formed or is not valid.
      IOException - an IO error was seen
      MalformedURLException - the string representing the URL was illformed.
      ParserConfigurationException - the XML parser cannot be configured

    • setToc

      public void setToc(InputStream is, boolean expand, boolean validating) throws FactoryConfigurationError, SAXException, IOException, ParserConfigurationException
      Description copied from interface: UrlTocTree
      Set the table of contents from a URL represented as a String. This method should be used as as an alternative to addEntry, nextLevel, prevLevel and entriesCompleted
      Specified by:
      setToc in interface UrlTocTree
      Parameters:
      is - the Inputstream containing the table of contents.
      expand - True if the nodes should be expanded; false otherwise
      validating - True if the parser is validating; false otherwise
      Throws:
      FactoryConfigurationError - the XML parser cannot be configured
      SAXException - the XML data in the input stream in not well formed or is not valid.
      IOException - an IO error was seen
      MalformedURLException - the string representing the URL was illformed.
      ParserConfigurationException - the XML parser cannot be configured

    • getHtmlErrorTitle

      public final String getHtmlErrorTitle()
      Get the title used in error message dialog boxes associated with the HTML pane.
      Returns:
      the current title.

    • getTocCellRenderer

      public DefaultTreeCellRenderer getTocCellRenderer()
      Get the tre cell renderer for the table of contents.
      Returns:
      the cell renderer

    • getTocBackgound

      public final Color getTocBackgound()
      Get the background color for the table of contents.
      Returns:
      the background color for the table of contents (if none has been explicitly set, the background color of the TOC component's parent is returned)

    • setTocBackground

      public final void setTocBackground(Color c)
      Set the background color for the table of contents.

      Note: with some pluggable look and feels, this method may be fully or partially ignored. It works as expected with the default look and feel.

      Parameters:
      c - the background color; null if the parent component's color should be used.

    • getTocForeground

      public final Color getTocForeground()
      Get the foreground color for the table of contents.
      Returns:
      the foreground color for the table of contents (if none has been explicitly set, the foreground color of the TOC component's parent is returned)

    • setTocForeground

      public final void setTocForeground(Color c)
      Set the foreground color for the table of contents.

      Note: with some pluggable look and feels, this method may be fully or partially ignored. It works as expected with the default look and feel.

      Parameters:
      c - the foreground color; null if the parent component's color should be used.

    • setTocBackgroundSelectionColor

      public void setTocBackgroundSelectionColor(Color c)
      Set the background color for items that are selected in the table of contents.

      Note: with some pluggable look and feels, this method may be fully or partially ignored. It works as expected with the default look and feel.

      Parameters:
      c - the color

    • setTocBackgroundNonSelectionColor

      public void setTocBackgroundNonSelectionColor(Color c)
      Set the background color for items that are not selected in the table of contents.

      Note: with some pluggable look and feels, this method may be fully or partially ignored. It works as expected with the default look and feel.

      Parameters:
      c - the color

    • setTocTextSelectionColor

      public void setTocTextSelectionColor(Color c)
      Set the color of text describing items that are selected in the table of contents.

      Note: with some pluggable look and feels, this method may be fully or partially ignored. It works as expected with the default look and feel.

      Parameters:
      c - the color

    • setTocTextNonSelectionColor

      public void setTocTextNonSelectionColor(Color c)
      Set the color of text describing items that are not selected in the table of contents.

      Note: with some pluggable look and feels, this method may be fully or partially ignored. It works as expected with the default look and feel.

      Parameters:
      c - the color

    • setTocTCRFont

      public final void setTocTCRFont(Font font)
      Set the font for the entries in table of contents.

      Note: with some pluggable look and feels, this method may be fully or partially ignored. It works as expected with the default look and feel.

      Parameters:
      font - the font