com.pixelmed.database

## Class DatabaseTreeBrowser

- java.lang.Object
- - com.pixelmed.database.DatabaseTreeBrowser

Direct Known Subclasses:
  DicomCleaner.OurDestinationDatabaseTreeBrowser, DicomCleaner.OurSourceDatabaseTreeBrowser, DoseUtility.OurSourceDatabaseTreeBrowser, DownloadOrTransmit.OurSourceDatabaseTreeBrowser

    public class DatabaseTreeBrowser
    extends java.lang.Object

The `DatabaseTreeBrowser` class implements a Swing graphical user interface to browse the contents of `DatabaseInformationModel`.

The browser is rendered as a tree view of the entire database and a one row tabular representation of the contents of any entity (record) that the user selects in the tree. Constructors are provided to either add the browser to a frame and creating the tree and table, or to make use of a pair of existing scrolling panes.

Only selection of single nodes is permitted by default.

Though a functional browser can be built using this class, to add application-specific behavior to be applied when a user selects one or more instance entities in the tree, a sub-class inheriting from this class should be constructed that overrides the `buildTreeSelectionListenerToDoSomethingWithSelectedFiles` method. The default implementation, which handles single and multiple selections is as follows:

            protected TreeSelectionListener buildTreeSelectionListenerToDoSomethingWithSelectedFiles() {
                    return new TreeSelectionListener() {
                            public void valueChanged(TreeSelectionEvent tse) {
                                    DatabaseTreeRecord[] records = getSelectionPaths();
                                    if (!doSomethingWithSelections(records)) {
                                            Vector names = new Vector();
                                            for (DatabaseTreeRecord r : records) {
                                                    recurseThroughChildrenGatheringFileNames(r,names);
                                            }
                                    doSomethingWithSelectedFiles(names);
                            }
                    };
            }

Note that this allows you to take the simple approach of overriding the protected method `doSomethingWithSelectedFiles`, the default implementation of which is just to print the file name.

See Also:
  `com.pixelmed.database`, `DatabaseTreeRecord`, `DatabaseInformationModel`, `TreePath`, `TreeSelectionListener`

### Constructor Summary

Constructors
Constructor and Description
`DatabaseTreeBrowser(DatabaseInformationModel d, java.awt.Container content)` Build and display a graphical user interface view of a database information model.
`DatabaseTreeBrowser(DatabaseInformationModel d, javax.swing.JFrame frame)` Build and display a graphical user interface view of a database information model.
`DatabaseTreeBrowser(DatabaseInformationModel d, javax.swing.JScrollPane treeBrowserScrollPane, javax.swing.JScrollPane attributeBrowserScrollPane)` Build and display a graphical user interface view of a database information model.

### Method Summary

Methods
`protected java.awt.event.MouseListener` `buildMouseListenerToDetectDoubleClickEvents()`
`protected javax.swing.event.TreeSelectionListener` `buildTreeSelectionListenerToDisplayAttributesOfSelectedRecord(javax.swing.JScrollPane attributeBrowserScrollPane)` By default this method populates the tabular attribute browser when an entity is selected in the tree browser.
`protected javax.swing.event.TreeSelectionListener` `buildTreeSelectionListenerToDoSomethingWithSelectedFiles()` Override this method to perform application-specific behavior when an entity is selected in the tree browser.
`protected void` `doSomethingMoreWithWhateverWasSelected()` Will be called when a double-click event is detected unless `buildMouseListenerToDetectDoubleClickEvents` is overriden to do something else.
`protected void` `doSomethingWithSelectedFiles(java.util.Vector paths)` Will be called when a selection is made or changed and `doSomethingWithSelections()` returns false and not otherwise.
`protected boolean` `doSomethingWithSelections(DatabaseTreeRecord[] selections)` Will be called when a selection is made or changed.
`DatabaseTreeRecord[]` `getSelectionPaths()` Return the records currently selected.
`static void` `recurseThroughChildrenGatheringFileNames(DatabaseTreeRecord r, java.util.Vector names)` Recursively process the specified DatabaseTreeRecord and all its children finding file paths at the instance level.

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

### Constructor Detail

#### DatabaseTreeBrowser

    public DatabaseTreeBrowser(DatabaseInformationModel d,
                       javax.swing.JScrollPane treeBrowserScrollPane,
                       javax.swing.JScrollPane attributeBrowserScrollPane)
                        throws DicomException

Build and display a graphical user interface view of a database information model.

Parameters:
  `d` - the instance of the database (information model)
  `treeBrowserScrollPane` - the scrolling pane in which the tree view of the entire model (database) will be rendered
  `attributeBrowserScrollPane` - the scrolling pane in which the tabular view of the currently selected entity (record) will be rendered
Throws:
  `DicomException` - thrown if the information cannot be extracted

#### DatabaseTreeBrowser

    public DatabaseTreeBrowser(DatabaseInformationModel d,
                       javax.swing.JFrame frame)
                        throws DicomException

Build and display a graphical user interface view of a database information model.

Parameters:
  `d` - the instance of the database (information model)
  `frame` - a frame to whose content pane will be added scrolling panes containing tree and tabular selection views
Throws:
  `DicomException` - thrown if the information cannot be extracted

#### DatabaseTreeBrowser

    public DatabaseTreeBrowser(DatabaseInformationModel d,
                       java.awt.Container content)
                        throws DicomException

Build and display a graphical user interface view of a database information model.

Parameters:
  `d` - the instance of the database (information model)
  `content` - a container to which will be added scrolling panes containing tree and tabular selection views
Throws:
  `DicomException` - thrown if the information cannot be extracted

### Method Detail

#### getSelectionPaths

    public DatabaseTreeRecord[] getSelectionPaths()

Return the records currently selected.

Returns:
  the records currently selected

#### buildTreeSelectionListenerToDoSomethingWithSelectedFiles

    protected javax.swing.event.TreeSelectionListener buildTreeSelectionListenerToDoSomethingWithSelectedFiles()

Override this method to perform application-specific behavior when an entity is selected in the tree browser.

By default, this method calls `doSomethingWithSelections`, then if that returns false, for each of the selected records (and there may be more than one), adds to a `Vector` of file names (paths) of that record and the subtrees below it, then calls `doSomethingWithSelectedFiles`.

#### recurseThroughChildrenGatheringFileNames

    public static void recurseThroughChildrenGatheringFileNames(DatabaseTreeRecord r,
                                                java.util.Vector names)

Recursively process the specified DatabaseTreeRecord and all its children finding file paths at the instance level.

A static helper method, that is public so that it can be used in subclasses that override `buildTreeSelectionListenerToDoSomethingWithSelectedFiles`.

Parameters:
  `r` - the current DatabaseTreeRecord to process
  `names` - the file names (paths) to add to

#### buildTreeSelectionListenerToDisplayAttributesOfSelectedRecord

    protected javax.swing.event.TreeSelectionListener buildTreeSelectionListenerToDisplayAttributesOfSelectedRecord(javax.swing.JScrollPane attributeBrowserScrollPane)

By default this method populates the tabular attribute browser when an entity is selected in the tree browser.

Override this method to perform application-specific behavior, perhaps if not all attributes in the database for the selected entity are to be displayed, or their values are to be rendered specially. The default implementation renders everything as strings except those local database administrative attributes normally excluded.

Parameters:
  `attributeBrowserScrollPane` - the tabular attribute browser

#### buildMouseListenerToDetectDoubleClickEvents

    protected java.awt.event.MouseListener buildMouseListenerToDetectDoubleClickEvents()

#### doSomethingWithSelections

    protected boolean doSomethingWithSelections(DatabaseTreeRecord[] selections)

Will be called when a selection is made or changed.

Note that during multi-selection, or deselection, this may be called multiple times, so use this method to update cache of what is selected rather than initiating action on the selections, which should be done by some other means.

Parameters:
  `selections` - return true if did something and hence should do no more

#### doSomethingWithSelectedFiles

    protected void doSomethingWithSelectedFiles(java.util.Vector paths)

Will be called when a selection is made or changed and `doSomethingWithSelections()` returns false and not otherwise.

Note that during multi-selection, or deselection, this may be called multiple times, so use this method to update cache of what is selected rather than initiating action on the selections, which should be done by some other means.

Parameters:
  `paths` -

#### doSomethingMoreWithWhateverWasSelected

    protected void doSomethingMoreWithWhateverWasSelected()

Will be called when a double-click event is detected unless `buildMouseListenerToDetectDoubleClickEvents` is overriden to do something else.