Desktop JavaDoc comments for Mungo from gitter discussion

diff --git a/src/jalview/gui/Desktop.java b/src/jalview/gui/Desktop.java
index ace7529..4eff90a 100644 (file)
--- a/src/jalview/gui/Desktop.java
+++ b/src/jalview/gui/Desktop.java
@@ -229,6 +229,18 @@ public class Desktop extends GDesktop
 
   /**
    * just an instance (for testng, probably); no actual frames
+   * 
+   * This flag, when set true, allows a headless-like operation, with a Desktop
+   * object but no actual frames. The issue has to do with the mess-up of the
+   * Windows JInternalFrame implementation, which surreptitiously and
+   * unforgivingly accesses a native peer class, preventing headless operation.
+   * 
+   * It is set by invoking the Desktop(true) constructor.
+   * 
+   * It is possible that we can remove this option now, since headless mode is
+   * finally working on Windows through careful attention to not creating any
+   * JInternalFrame objects when in that mode.
+   * 
    */
   private boolean instanceOnly;
 
@@ -372,7 +384,11 @@ public class Desktop extends GDesktop
   }
 
   /**
-   * For testing.
+   * For testing purposes, this constructor can be utilized to allow the creation 
+   * of a singleton Desktop instance without the formation of frames. The Cache is 
+   * initialized, but that is all. 
+   * 
+   * It is not currently used. 
    * 
    * @param forInstance
    */
@@ -393,171 +409,180 @@ public class Desktop extends GDesktop
     Cache.initLogger();
     try
     {
-    /**
-     * A note to implementors. It is ESSENTIAL that any activities that might
-     * block are spawned off as threads rather than waited for during this
-     * constructor.
-     */
-    if (!Platform.isJS())
-    {
-      doVamsasClientCheck();
-    }
-    
-    doConfigureStructurePrefs();
-    setTitle("Jalview " + jalview.bin.Cache.getProperty("VERSION"));
-    setDefaultCloseOperation(JFrame.EXIT_ON_CLOSE);
-    boolean selmemusage = jalview.bin.Cache.getDefault("SHOW_MEMUSAGE",
-            false);
-    boolean showjconsole = jalview.bin.Cache.getDefault("SHOW_JAVA_CONSOLE",
-            false);
-    desktopPane = new MyDesktopPane(selmemusage);
-    
-    showMemusage.setSelected(selmemusage);
-    desktopPane.setBackground(Color.white);
-    getContentPane().setLayout(new BorderLayout());
-    // alternate config - have scrollbars - see notes in JAL-153
-    // JScrollPane sp = new JScrollPane();
-    // sp.getViewport().setView(desktop);
-    // getContentPane().add(sp, BorderLayout.CENTER);
-    
-    // BH 2018 - just an experiment to try unclipped JInternalFrames.
-    if (Platform.isJS())
-    {
-      getRootPane().putClientProperty("swingjs.overflow.hidden", "false");
-    }
-    
-    getContentPane().add(desktopPane, BorderLayout.CENTER);
-    desktopPane.setDragMode(JDesktopPane.OUTLINE_DRAG_MODE);
-    
-    // This line prevents Windows Look&Feel resizing all new windows to maximum
-    // if previous window was maximised
-    desktopPane.setDesktopManager(new MyDesktopManager(
-            (Platform.isWindowsAndNotJS() ? new DefaultDesktopManager()
-                    : Platform.isAMacAndNotJS()
-                            ? new AquaInternalFrameManager(
-                                    desktopPane.getDesktopManager())
-                            : desktopPane.getDesktopManager())));
-    
-    Rectangle dims = getLastKnownDimensions("");
-    if (dims != null)
-    {
-      setBounds(dims);
-    }
-    else
-    {
-      Dimension screenSize = Toolkit.getDefaultToolkit().getScreenSize();
-      int xPos = Math.max(5, (screenSize.width - 900) / 2);
-      int yPos = Math.max(5, (screenSize.height - 650) / 2);
-      setBounds(xPos, yPos, 900, 650);
-    }
-    
-    if (!Platform.isJS())
-    /**
-     * Java only
-     * 
-     * @j2sIgnore
-     */
-    {
-    
-      jconsole = new Console(this, showjconsole);
-      // add essential build information
-      jconsole.setHeader("Jalview Version: "
-              + jalview.bin.Cache.getProperty("VERSION") + "\n"
-              + "Jalview Installation: "
-              + jalview.bin.Cache.getDefault("INSTALLATION", "unknown")
-              + "\n" + "Build Date: "
-              + jalview.bin.Cache.getDefault("BUILD_DATE", "unknown") + "\n"
-              + "Java version: " + System.getProperty("java.version") + "\n"
-              + System.getProperty("os.arch") + " "
-              + System.getProperty("os.name") + " "
-              + System.getProperty("os.version"));
-    
-      showConsole(showjconsole);
-    
-      showNews.setVisible(false);
-    
-      experimentalFeatures.setSelected(showExperimental());
-    
-      getIdentifiersOrgData();
-    
-      checkURLLinks();
-    
-      // Spawn a thread that shows the splashscreen
-    
-      SwingUtilities.invokeLater(new Runnable()
+      /**
+       * A note to implementors. It is ESSENTIAL that any activities that might
+       * block are spawned off as threads rather than waited for during this
+       * constructor.
+       */
+      if (!Platform.isJS())
       {
-        @Override
-        public void run()
-        {
-          new SplashScreen();
-        }
-      });
-    
-      // Thread off a new instance of the file chooser - this reduces the time
-      // it
-      // takes to open it later on.
-      new Thread(new Runnable()
+        doVamsasClientCheck();
+      }
+
+      doConfigureStructurePrefs();
+      setTitle("Jalview " + jalview.bin.Cache.getProperty("VERSION"));
+      setDefaultCloseOperation(JFrame.EXIT_ON_CLOSE);
+      boolean selmemusage = jalview.bin.Cache.getDefault("SHOW_MEMUSAGE",
+              false);
+      boolean showjconsole = jalview.bin.Cache
+              .getDefault("SHOW_JAVA_CONSOLE", false);
+      desktopPane = new MyDesktopPane(selmemusage);
+
+      showMemusage.setSelected(selmemusage);
+      desktopPane.setBackground(Color.white);
+      getContentPane().setLayout(new BorderLayout());
+      // alternate config - have scrollbars - see notes in JAL-153
+      // JScrollPane sp = new JScrollPane();
+      // sp.getViewport().setView(desktop);
+      // getContentPane().add(sp, BorderLayout.CENTER);
+
+      // BH 2018 - just an experiment to try unclipped JInternalFrames.
+      if (Platform.isJS())
       {
-        @Override
-        public void run()
+        getRootPane().putClientProperty("swingjs.overflow.hidden", "false");
+      }
+
+      getContentPane().add(desktopPane, BorderLayout.CENTER);
+      desktopPane.setDragMode(JDesktopPane.OUTLINE_DRAG_MODE);
+
+      // This line prevents Windows Look&Feel resizing all new windows to
+      // maximum
+      // if previous window was maximised
+      desktopPane.setDesktopManager(new MyDesktopManager(
+              (Platform.isWindowsAndNotJS() ? new DefaultDesktopManager()
+                      : Platform.isAMacAndNotJS()
+                              ? new AquaInternalFrameManager(
+                                      desktopPane.getDesktopManager())
+                              : desktopPane.getDesktopManager())));
+
+      Rectangle dims = getLastKnownDimensions("");
+      if (dims != null)
+      {
+        setBounds(dims);
+      }
+      else
+      {
+        Dimension screenSize = Toolkit.getDefaultToolkit().getScreenSize();
+        int xPos = Math.max(5, (screenSize.width - 900) / 2);
+        int yPos = Math.max(5, (screenSize.height - 650) / 2);
+        setBounds(xPos, yPos, 900, 650);
+      }
+
+      // Note that this next syntax, checking for Platform.isJS and also
+      // escaping the code using @j2sIgnore, serves two purposes. It gives
+      // us an easily findable tag, Platform.isJS(), to places in the code where
+      // there is something different about the SwingJS implementation. Second,
+      // it deletes the unneeded Java-only code form the JavaScript version
+      // completely (@j2sIgnore), since it will never be used there.
+
+      if (!Platform.isJS())
+      /**
+       * Java only
+       * 
+       * @j2sIgnore
+       */
+      {
+
+        jconsole = new Console(this, showjconsole);
+        // add essential build information
+        jconsole.setHeader("Jalview Version: "
+                + jalview.bin.Cache.getProperty("VERSION") + "\n"
+                + "Jalview Installation: "
+                + jalview.bin.Cache.getDefault("INSTALLATION", "unknown")
+                + "\n" + "Build Date: "
+                + jalview.bin.Cache.getDefault("BUILD_DATE", "unknown")
+                + "\n" + "Java version: "
+                + System.getProperty("java.version") + "\n"
+                + System.getProperty("os.arch") + " "
+                + System.getProperty("os.name") + " "
+                + System.getProperty("os.version"));
+
+        showConsole(showjconsole);
+
+        showNews.setVisible(false);
+
+        experimentalFeatures.setSelected(showExperimental());
+
+        getIdentifiersOrgData();
+
+        checkURLLinks();
+
+        // Spawn a thread that shows the splashscreen
+
+        SwingUtilities.invokeLater(new Runnable()
         {
-          Cache.log.debug("Filechooser init thread started.");
-          String fileFormat = Cache.getProperty("DEFAULT_FILE_FORMAT");
-          JalviewFileChooser.forRead(Cache.getProperty("LAST_DIRECTORY"),
-                  fileFormat);
-          Cache.log.debug("Filechooser init thread finished.");
-        }
-      }).start();
-      // Add the service change listener
-      changeSupport.addJalviewPropertyChangeListener("services",
-              new PropertyChangeListener()
-              {
-    
-                @Override
-                public void propertyChange(PropertyChangeEvent evt)
+          @Override
+          public void run()
+          {
+            new SplashScreen();
+          }
+        });
+
+        // Thread off a new instance of the file chooser - this reduces the time
+        // it
+        // takes to open it later on.
+        new Thread(new Runnable()
+        {
+          @Override
+          public void run()
+          {
+            Cache.log.debug("Filechooser init thread started.");
+            String fileFormat = Cache.getProperty("DEFAULT_FILE_FORMAT");
+            JalviewFileChooser.forRead(Cache.getProperty("LAST_DIRECTORY"),
+                    fileFormat);
+            Cache.log.debug("Filechooser init thread finished.");
+          }
+        }).start();
+        // Add the service change listener
+        changeSupport.addJalviewPropertyChangeListener("services",
+                new PropertyChangeListener()
                 {
-                  Cache.log.debug("Firing service changed event for "
-                          + evt.getNewValue());
-                  JalviewServicesChanged(evt);
-                }
-    
-              });
-    
-    }
-    
-    this.setDropTarget(new java.awt.dnd.DropTarget(desktopPane, this));
-    
-    this.addWindowListener(new WindowAdapter()
-    {
-      @Override
-      public void windowClosing(WindowEvent evt)
-      {
-        quit();
+
+                  @Override
+                  public void propertyChange(PropertyChangeEvent evt)
+                  {
+                    Cache.log.debug("Firing service changed event for "
+                            + evt.getNewValue());
+                    JalviewServicesChanged(evt);
+                  }
+
+                });
+
       }
-    });
-    
-    MouseAdapter ma;
-    this.addMouseListener(ma = new MouseAdapter()
-    {
-      @Override
-      public void mousePressed(MouseEvent evt)
+
+      this.setDropTarget(new java.awt.dnd.DropTarget(desktopPane, this));
+
+      this.addWindowListener(new WindowAdapter()
       {
-        if (evt.isPopupTrigger()) // Mac
+        @Override
+        public void windowClosing(WindowEvent evt)
         {
-          showPasteMenu(evt.getX(), evt.getY());
+          quit();
         }
-      }
-    
-      @Override
-      public void mouseReleased(MouseEvent evt)
+      });
+
+      MouseAdapter ma;
+      this.addMouseListener(ma = new MouseAdapter()
       {
-        if (evt.isPopupTrigger()) // Windows
+        @Override
+        public void mousePressed(MouseEvent evt)
         {
-          showPasteMenu(evt.getX(), evt.getY());
+          if (evt.isPopupTrigger()) // Mac
+          {
+            showPasteMenu(evt.getX(), evt.getY());
+          }
         }
-      }
-    });
-    desktopPane.addMouseListener(ma);
+
+        @Override
+        public void mouseReleased(MouseEvent evt)
+        {
+          if (evt.isPopupTrigger()) // Windows
+          {
+            showPasteMenu(evt.getX(), evt.getY());
+          }
+        }
+      });
+      desktopPane.addMouseListener(ma);
     } catch (Throwable t)
     {
       t.printStackTrace();