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

Class ObjTocPane

java.lang.Object
java.awt.Component
java.awt.Container
javax.swing.JComponent
javax.swing.JTree
org.bzdev.swing.ObjTocPane
All Implemented Interfaces:
ImageObserver, MenuContainer, Serializable, Accessible, Scrollable, TocTree
Direct Known Subclasses:
UrlTocPane
public class ObjTocPane extends JTree implements TocTree
ObjTocPane provides a JTree that provides a table of contents for a set of objects. The table of contents is arranged hierarchically with a single root. The tree is configured to support single selections. Each time a node is selected (including being selected a second time without first deselecting it), all action listeners are notified.

To initialize the tree, the user should first call its constructor (which takes zero arguments), followed by a call to the method addEntry(name, obj) to add the root of the tree. This assigns the root node a name name and value obj. To add children, this must be followed by a call to nextLevel, followed by calls to addEntry for each child. Each call to nextLevel() must be balanced with a call to prevLevel(). When all entries are defined, the method entriesCompleted(). If you do not want the root node to be displayed, use entriesCompleted(false) instead of entriesCompleted(). One may also use the addActionListener method to add action listeners in order to respond to changes in the selection. These listeners are notified whenever an entry is clicked, not just when the entry was changed.

Finally, one should call setSelectionWithAction(int) to execute the action that would occur when the initial node is selected (this is not done automatically to give the programmer some control over when this should occur, and allows software to change the selection as needed.)

Access methods for ObjTocPane.Entry allow one to recover any relevant mouse event. These are valid for the duration of action listeners fired by a selection or a call to setSelectionWithAction(int). An instance of ObjTocPane.Entry will be used as the source of action events created by this class in response to a call to setSelectionWithAction(int).

See Also:

  • Constructor Details

  • Method Details

    • clearToc

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

    • addActionListener

      public void addActionListener(ActionListener l)
      Add an action listener. The source of an action event will be the entry that was selected: an object whose type is ObjTocPane.Entry. The action's command is the title for the entry.
      Specified by:
      addActionListener in interface TocTree
      Parameters:
      l - the action listener to add.

    • removeActionListener

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

    • fireActionPerformed

      protected void fireActionPerformed()
      Notify all action listeners of action-performed events.

    • clearSelection

      public void clearSelection()
      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
      Overrides:
      clearSelection in class JTree

    • addEntry

      public void addEntry(String name, Object obj)
      Add a new node to the tree, giving it a name.
      Specified by:
      addEntry in interface TocTree
      Parameters:
      name - A string naming the node.
      obj - The object that represents the value of the node.
      Throws:
      IllegalStateException - if this method was called after a call to entriesCompleted.
      See Also:

    • nextLevel

      public void nextLevel()
      Add a new level to the tree rooted at the last node entered.
      Specified by:
      nextLevel in interface TocTree
      Throws:
      IllegalStateException - if this method was called after a call to entriesCompleted.
      See Also:

    • prevLevel

      public void prevLevel()
      Return to the previous level in the tree.
      Specified by:
      prevLevel in interface TocTree
      Throws:
      IllegalStateException - if this method was called after a call to entriesCompleted or if it was called more times than nextLevel
      See Also:

    • entriesCompleted

      public void entriesCompleted()
      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
      Throws:
      IllegalStateException - if this method was already called.
      See Also:

    • entriesCompleted

      public void entriesCompleted(boolean expand)
      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
      Throws:
      IllegalStateException - if this method was already called.
      See Also:

    • setSelectionWithAction

      public final void setSelectionWithAction(int row)
      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.
      Throws:
      IllegalStateException - if this method was called before entriesCompleted.

    • setCellRenderer

      public void setCellRenderer(TreeCellRenderer x)
      Sets the TreeCellRenderer that will be used to draw each cell.
      Overrides:
      setCellRenderer in class JTree
      Parameters:
      x - the tree-cell renderer that is to render each cell
      See Also:

    • setBackground

      public void setBackground(Color color)
      Set the backgound color of this component. A background color is used only if a component is opaque; however, unless the colors for the selected or non-selected tree endtries are already set explicitly, this method will also set the background color for those entries to reasonable values.

      Modifications to a table-cell renderer are not automtically reapplied if the table-cell renderer is changed.

      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
      See Also:

    • setForeground

      public void setForeground(Color color)
      Set the foreground color of this component. A foreground color is used only if a component is opaque; however, unless the colors for the selected or non-selected tree entries are already set explicitly, this method will also set the text color for those entries.

      Modifications to a table-cell renderer are not automtically reapplied if the table-cell renderer is changed.

      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:
      setForeground in class JComponent
      Parameters:
      color - the color
      See Also:

    • setTCRBackgroundSelectionColor

      public void setTCRBackgroundSelectionColor(Color c) throws UnsupportedOperationException
      Set the current table-cell-renderer's background color for selected items.

      This method is provided for convenience. To get the value, use JTree.getCellRenderer() to get the current cell renderer. If the cell renderer is an instance of DefaultTreeCellRenderer, use the method DefaultTreeCellRenderer.getBackgroundSelectionColor().

      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
      Throws:
      UnsupportedOperationException - if the tree cell renderer is not an instance of DefaultTreeCellRenderer

    • setTCRBackgroundNonSelectionColor

      public void setTCRBackgroundNonSelectionColor(Color c) throws UnsupportedOperationException
      Set the current table-cell-renderer's background color for non-selected items.

      This method is provided for convenience. To get the value, use JTree.getCellRenderer() to get the current cell renderer. If the cell renderer is an instance of DefaultTreeCellRenderer, use the method DefaultTreeCellRenderer.getBackgroundNonSelectionColor().

      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
      Throws:
      UnsupportedOperationException - if the tree cell renderer is not an instance of DefaultTreeCellRenderer

    • setTCRTextSelectionColor

      public void setTCRTextSelectionColor(Color c) throws UnsupportedOperationException
      Set the current table-cell-renderer's text color for selected items.

      This method is provided for convenience. To get the value, use JTree.getCellRenderer() to get the current cell renderer. If the cell renderer is an instance of DefaultTreeCellRenderer, use the method DefaultTreeCellRenderer.getTextSelectionColor().

      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
      Throws:
      UnsupportedOperationException - if the tree cell renderer is not an instance of DefaultTreeCellRenderer

    • setTCRTextNonSelectionColor

      public void setTCRTextNonSelectionColor(Color c) throws UnsupportedOperationException
      Set the current table-cell-renderer's text color for non-selected items. This method is provided for convenience. To get the value, use JTree.getCellRenderer() to get the current cell renderer. If the cell renderer is an instance of DefaultTreeCellRenderer, use the method DefaultTreeCellRenderer.getTextNonSelectionColor().

      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
      Throws:
      UnsupportedOperationException - if the tree cell renderer is not an instance of DefaultTreeCellRenderer

    • setTCRFont

      public void setTCRFont(Font font) throws UnsupportedOperationException
      Set the current table-cell-renderer's font.

      This method is provided for convenience. To get the value, use JTree.getCellRenderer() to get the current cell renderer. If the cell renderer is an instance of DefaultTreeCellRenderer, use the method DefaultTreeCellRenderer.getFont().

      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
      Throws:
      UnsupportedOperationException - if the tree cell renderer is not an instance of DefaultTreeCellRenderer