Add views (#231)

Work on #228.  

Suppose there are one or more classes that provide a view of a model, in
the sense of a <a
href="https://en.wikipedia.org/wiki/Model%E2%80%93view%E2%80%93controller">model-view-controller
design pattern</a>.

When class A provides a GUI for class B, A should be Annotated
`View(of=B.class)`. A must also implement the `ViewProvider` interface.
ViewProvider then empowers other systems to locate and build the Swing
GUIs for A.

Annotating a View and failing to implement the ViewProvider interface
will cause a test to fail.

src/main/java/com/marginallyclever/ro3/SceneChangeListener.java

@@ -4,7 +4,19 @@
 
 import java.util.EventListener;
 
+/**
+ * A listener for scene changes.
+ */
 public interface SceneChangeListener extends EventListener {
+    /**
+     * Called before the scene changes.  This is a good time to unregister listeners.
+     * @param oldScene the scene that is about to be replaced.
+     */
     void beforeSceneChange(Node oldScene);
+
+    /**
+     * Called after the scene changes.  This is a good time to register listeners.
+     * @param newScene the scene that has just been added.
+     */
     void afterSceneChange(Node newScene);
 }

src/main/java/com/marginallyclever/ro3/apps/App.java

@@ -4,7 +4,7 @@
 import java.awt.*;
 
 /**
- * Marker interface for all apps.
+ * All apps extend from App for Reflection.
  */
 public class App extends JPanel {
     public App() {

src/main/java/com/marginallyclever/ro3/apps/DockingPanel.java

@@ -30,6 +30,11 @@ public String getTabText() {
         return tabText;
     }
 
+    /**
+     * Refuse to wrap this {@link DockingPanel} in a {@link JScrollPane}.  The panel is responsibile for scrolling,
+     * not the docking system.
+     * @return false
+     */
     @Override
     public boolean isWrappableInScrollpane() {
         return false;

src/main/java/com/marginallyclever/ro3/apps/FactoryPanel.java

@@ -1,13 +1,11 @@
 package com.marginallyclever.ro3.apps;
 
 import com.marginallyclever.ro3.Factory;
-import com.marginallyclever.ro3.apps.nodetreeview.NodeTreeBranch;
 import com.marginallyclever.ro3.apps.shared.SearchBar;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
 import javax.swing.*;
-import javax.swing.border.Border;
 import javax.swing.tree.DefaultMutableTreeNode;
 import javax.swing.tree.DefaultTreeCellRenderer;
 import javax.swing.tree.DefaultTreeModel;
@@ -136,7 +134,7 @@ private void addAllParents(List<Factory.Category<T>> matches) {
      * @return a list of all categories that match the search criteria
      */
     private List<Factory.Category<T>> findAllTypesMatching(Factory.Category<T> root, String searchCriteria) {
-        boolean isRegex = searchBar.isRegex();
+        boolean isRegex = searchBar.getRegex();
         List<Factory.Category<T>> matches = new ArrayList<>();
         List<Factory.Category<T>> toSearch = new ArrayList<>();
         toSearch.add(root);

src/main/java/com/marginallyclever/ro3/apps/RO3Frame.java

@@ -12,7 +12,6 @@
 import com.marginallyclever.communications.application.TextInterfaceToSessionLayer;
 import com.marginallyclever.convenience.helpers.FileHelper;
 import com.marginallyclever.ro3.RO3;
-import com.marginallyclever.ro3.UndoSystem;
 import com.marginallyclever.ro3.apps.about.AboutPanel;
 import com.marginallyclever.ro3.apps.actions.*;
 import com.marginallyclever.ro3.apps.editorpanel.EditorPanel;
@@ -43,6 +42,10 @@
 import java.util.Properties;
 import java.util.prefs.Preferences;
 
+/**
+ * <p>{@link RO3Frame} is the main frame for the Robot Overlord 3 application.  It contains the menu bar and docking
+ * panels.  It also maintains one instance of each {@link App}.</p>
+ */
 public class RO3Frame extends JFrame {
     private static final Logger logger = LoggerFactory.getLogger(RO3Frame.class);
     private final List<DockingPanel> windows = new ArrayList<>();

src/main/java/com/marginallyclever/ro3/apps/RO3FrameDropTarget.java

@@ -7,7 +7,6 @@
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
-import javax.swing.*;
 import java.awt.datatransfer.DataFlavor;
 import java.awt.datatransfer.Transferable;
 import java.awt.dnd.DnDConstants;
@@ -17,7 +16,8 @@
 import java.util.List;
 
 /**
- * Allows the user to drop Scenes and Meshes onto the main window.  They will be imported to the existing scene.
+ * Allows the user to drop Scene or a supported mesh file onto the main window.  They will be
+ * imported to the existing scene and appear at the world origin.
  */
 public class RO3FrameDropTarget extends DropTargetAdapter {
     private static final Logger logger = LoggerFactory.getLogger(RO3FrameDropTarget.class);
@@ -32,30 +32,32 @@ public void drop(DropTargetDropEvent event) {
         try {
             Transferable tr = event.getTransferable();
             DataFlavor[] flavors = tr.getTransferDataFlavors();
+            int complete = 0;
             for (DataFlavor flavor : flavors) {
                 logger.debug("Possible flavor: {}", flavor.getMimeType());
                 if (flavor.isFlavorJavaFileListType()) {
                     event.acceptDrop(DnDConstants.ACTION_COPY);
                     Object object = tr.getTransferData(flavor);
                     if (object instanceof List<?> list) {
-                        if (!list.isEmpty()) {
-                            object = list.get(0);
-                            if (object instanceof File file) {
-                                // drop a mesh
+                        for(Object item : list) {
+                            if (item instanceof File file) {
                                 if(importMesh(file.getAbsolutePath())) {
-                                    event.dropComplete(true);
-                                    return;
-                                }
-                                // drop a scene
-                                if(importScene(file)) {
-                                    event.dropComplete(true);
-                                    return;
-                                }
+                                    // drop a mesh
+                                    complete++;
+                                } else if(importScene(file)) {
+                                    // drop a scene
+                                    complete++;
+                                } // else silently ignore
                             }
                         }
                     }
                 }
             }
+            if(complete>0) {
+                logger.debug("Drop ok: {}", complete);
+                event.dropComplete(true);
+                return;
+            }
             logger.debug("Drop failed: {}", event);
             event.rejectDrop();
         } catch (Exception e) {

src/main/java/com/marginallyclever/ro3/apps/RecentFilesMenu.java

@@ -11,7 +11,7 @@
 import java.util.prefs.Preferences;
 
 /**
- * A menu that keeps track of recently loaded files.
+ * {@link RecentFilesMenu} is a menu that keeps track of recently loaded files.
  */
 public class RecentFilesMenu extends JMenu {
     private static final Logger logger = LoggerFactory.getLogger(RecentFilesMenu.class);

src/main/java/com/marginallyclever/ro3/UndoSystem.java → src/main/java/com/marginallyclever/ro3/apps/UndoSystem.java

@@ -1,4 +1,4 @@
-package com.marginallyclever.ro3;
+package com.marginallyclever.ro3.apps;
 
 import com.marginallyclever.ro3.apps.actions.RedoAction;
 import com.marginallyclever.ro3.apps.actions.UndoAction;
@@ -7,8 +7,7 @@
 import javax.swing.undo.UndoManager;
 
 /**
- * A singleton to manage undo/redo actions.
- * @author Dan Royer
+ * {@link UndoSystem} is a singleton to manage the undo/redo history and associated {@link javax.swing.AbstractAction}s.
  */
 public class UndoSystem {
 	private static final UndoManager undoManager = new UndoManager();

src/main/java/com/marginallyclever/ro3/apps/about/AboutPanel.java

@@ -10,6 +10,9 @@
 import java.io.BufferedInputStream;
 import java.util.Objects;
 
+/**
+ * {@link AboutPanel} is a panel that displays the contents of the file "about.html" in the same package.
+ */
 public class AboutPanel extends App {
     private static final Logger logger = LoggerFactory.getLogger(AboutPanel.class);
 

src/main/java/com/marginallyclever/ro3/apps/actions/AddNode.java

@@ -3,7 +3,7 @@
 import com.marginallyclever.ro3.apps.FactoryPanel;
 import com.marginallyclever.ro3.Registry;
 import com.marginallyclever.ro3.node.Node;
-import com.marginallyclever.ro3.UndoSystem;
+import com.marginallyclever.ro3.apps.UndoSystem;
 
 import javax.swing.*;
 import java.awt.*;

src/main/java/com/marginallyclever/ro3/apps/actions/CopyNode.java

@@ -1,7 +1,7 @@
 package com.marginallyclever.ro3.apps.actions;
 
 import com.marginallyclever.ro3.Registry;
-import com.marginallyclever.ro3.UndoSystem;
+import com.marginallyclever.ro3.apps.UndoSystem;
 
 import javax.swing.*;
 import java.awt.event.ActionEvent;

src/main/java/com/marginallyclever/ro3/apps/actions/CutNode.java

@@ -1,12 +1,15 @@
 package com.marginallyclever.ro3.apps.actions;
 
 import com.marginallyclever.ro3.Registry;
-import com.marginallyclever.ro3.UndoSystem;
+import com.marginallyclever.ro3.apps.UndoSystem;
 
 import javax.swing.*;
 import java.awt.event.ActionEvent;
 import java.util.Objects;
 
+/**
+ * {@link CutNode} is an action that cuts the selected node(s) from the scene.
+ */
 public class CutNode extends AbstractAction {
 
     public CutNode() {

src/main/java/com/marginallyclever/ro3/apps/actions/ExportScene.java

@@ -20,7 +20,7 @@
 import java.util.zip.ZipOutputStream;
 
 /**
- * <p>Export the scene and all the assets used to a single file for sharing on another computer.
+ * <p>Export the scene and all the assets used to a single ZIP file for sharing on another computer.
  * This is not the same as saving the scene.</p>
  */
 public class ExportScene extends AbstractAction {

src/main/java/com/marginallyclever/ro3/apps/actions/ImportScene.java

@@ -1,25 +1,17 @@
 package com.marginallyclever.ro3.apps.actions;
 
-import com.marginallyclever.ro3.Registry;
-import com.marginallyclever.ro3.UndoSystem;
+import com.marginallyclever.ro3.apps.UndoSystem;
 import com.marginallyclever.ro3.apps.RO3Frame;
-import com.marginallyclever.ro3.node.Node;
-import org.json.JSONObject;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
 import javax.swing.*;
 import java.awt.*;
 import java.awt.event.ActionEvent;
-import java.io.File;
-import java.io.IOException;
-import java.nio.file.Files;
-import java.nio.file.Paths;
-import java.security.InvalidParameterException;
 import java.util.Objects;
 
 /**
- * Load a Scene into the existing Scene.
+ * Load a Scene and insert it into the existing Scene.
  */
 public class ImportScene extends AbstractAction {
     private static final Logger logger = LoggerFactory.getLogger(ImportScene.class);

src/main/java/com/marginallyclever/ro3/apps/actions/LoadScene.java

@@ -1,11 +1,9 @@
 package com.marginallyclever.ro3.apps.actions;
 
-import com.marginallyclever.convenience.helpers.FileHelper;
-import com.marginallyclever.ro3.UndoSystem;
+import com.marginallyclever.ro3.apps.UndoSystem;
 import com.marginallyclever.ro3.apps.RecentFilesMenu;
 import com.marginallyclever.ro3.Registry;
 import com.marginallyclever.ro3.node.Node;
-import com.marginallyclever.ro3.texture.TextureFactory;
 import org.json.JSONObject;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;

src/main/java/com/marginallyclever/ro3/apps/actions/NewScene.java

@@ -1,7 +1,7 @@
 package com.marginallyclever.ro3.apps.actions;
 
 import com.marginallyclever.ro3.Registry;
-import com.marginallyclever.ro3.UndoSystem;
+import com.marginallyclever.ro3.apps.UndoSystem;
 import com.marginallyclever.ro3.node.Node;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;

src/main/java/com/marginallyclever/ro3/apps/actions/PasteNode.java

@@ -2,23 +2,20 @@
 
 import com.marginallyclever.convenience.helpers.JSONHelper;
 import com.marginallyclever.ro3.Registry;
-import com.marginallyclever.ro3.UndoSystem;
-import com.marginallyclever.ro3.node.Node;
-import org.json.JSONArray;
-import org.json.JSONObject;
+import com.marginallyclever.ro3.apps.UndoSystem;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
 import javax.swing.*;
 import java.awt.*;
-import java.awt.datatransfer.DataFlavor;
 import java.awt.datatransfer.FlavorEvent;
-import java.awt.datatransfer.StringSelection;
-import java.awt.datatransfer.Transferable;
 import java.awt.event.ActionEvent;
 import java.util.ArrayList;
 import java.util.Objects;
 
+/**
+ * {@link PasteNode} is an action that pastes the selected node(s) from the clipboard.
+ */
 public class PasteNode extends AbstractAction {
     private final Logger logger = LoggerFactory.getLogger(PasteNode.class);
 

src/main/java/com/marginallyclever/ro3/apps/actions/RedoAction.java

@@ -8,7 +8,7 @@
 import java.util.Objects;
 
 /**
- * go forward one step in the undo/redo history.
+ * Go forward one step in the undo/redo history.
  * @author Dan Royer
  */
 public class RedoAction extends AbstractAction {

src/main/java/com/marginallyclever/ro3/apps/actions/RemoveNode.java

@@ -1,8 +1,7 @@
 package com.marginallyclever.ro3.apps.actions;
 
 import com.marginallyclever.ro3.Registry;
-import com.marginallyclever.ro3.UndoSystem;
-import com.marginallyclever.ro3.apps.nodetreeview.NodeTreeView;
+import com.marginallyclever.ro3.apps.UndoSystem;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
@@ -11,6 +10,9 @@
 import java.util.ArrayList;
 import java.util.Objects;
 
+/**
+ * {@link RemoveNode} is an action that removes the selected node(s) from the scene.
+ */
 public class RemoveNode extends AbstractAction {
     private final Logger logger = LoggerFactory.getLogger(RemoveNode.class);
 

src/main/java/com/marginallyclever/ro3/apps/actions/UndoAction.java

@@ -8,7 +8,7 @@
 import java.util.Objects;
 
 /**
- * go back one step in the undo/redo history.
+ * Go back one step in the undo/redo history.
  * @author Dan Royer
  */
 public class UndoAction extends AbstractAction {

src/main/java/com/marginallyclever/ro3/apps/dialogs/NodeSelectionDialog.java

@@ -133,7 +133,7 @@ private void addAllParents(List<Node> matches) {
      * @return a list of all nodes matching the search criteria
      */
     private List<Node> findAllNodesMatching(Node rootNode, String searchCriteria) {
-        boolean isRegex = searchBar.isRegex();
+        boolean isRegex = searchBar.getRegex();
         List<Node> matches = new ArrayList<>();
         List<Node> toSearch = new ArrayList<>();
         toSearch.add(rootNode);

src/main/java/com/marginallyclever/ro3/apps/editorpanel/LoadAction.java

@@ -13,6 +13,9 @@
 import java.security.InvalidParameterException;
 import java.util.Objects;
 
+/**
+ * Load a file into the {@link EditorPanel}
+ */
 public class LoadAction extends AbstractAction {
     private static final Logger logger = LoggerFactory.getLogger(LoadAction.class);
     private final EditorPanel editorPanel;

src/main/java/com/marginallyclever/ro3/apps/editorpanel/NewAction.java

@@ -4,6 +4,9 @@
 import java.awt.event.ActionEvent;
 import java.util.Objects;
 
+/**
+ * Clear the text area of the {@link EditorPanel}
+ */
 public class NewAction extends AbstractAction {
     private final EditorPanel editorPanel;
 

src/main/java/com/marginallyclever/ro3/apps/editorpanel/SaveAction.java

@@ -12,6 +12,9 @@
 import java.io.IOException;
 import java.util.Objects;
 
+/**
+ * Save the text area of the {@link EditorPanel} to a file.
+ */
 public class SaveAction extends AbstractAction {
     private static final Logger logger = LoggerFactory.getLogger(SaveAction.class);
     private final EditorPanel editorPanel;

src/main/java/com/marginallyclever/ro3/apps/logpanel/LogPanel.java

@@ -20,8 +20,8 @@
 import java.util.*;
 
 /**
- * {@link LogPanel} is a read-only panel that contains the log.  It cannot be derived from {@link DockingPanel}
- * because it is created before {@link ModernDocking.app.Docking} is initialized.
+ * <p>{@link LogPanel} is a read-only panel that contains the log and a button to open the log file location in the
+ * OS.</p>
  */
 public class LogPanel extends App {
     private static final org.slf4j.Logger logger = LoggerFactory.getLogger(LogPanel.class);