Merge pull request processing#2804 from joelmoniz/addReferences

benfry · benfry · commit 65bed4fba4b4 · 2014-11-18T14:04:15.000-05:00
Added References for installed tools and libraries, whenever available, to the Help menu.
diff --git a/app/src/processing/app/Editor.java b/app/src/processing/app/Editor.java
@@ -286,6 +286,11 @@ public void windowGainedFocus(WindowEvent e) {
   }
 
 
+  protected ArrayList<ToolContribution> getCoreTools() {
+    return coreTools;
+  }
+
+
   /**
    * Broken out to get modes working for GSOC, but this needs a longer-term
    * solution where the listeners are handled properly.
@@ -1258,11 +1263,22 @@ public void actionPerformed(ActionEvent e) {
 
   public void showReference(String filename) {
     File file = new File(mode.getReferenceFolder(), filename);
+    showReferenceFile(file);
+  }
+
+
+  /**
+   * Given the .html file, displays it in the default browser.
+   * 
+   * @param file
+   */
+  public void showReferenceFile(File file) {
     try {
       file = file.getCanonicalFile();
     } catch (IOException e) {
       e.printStackTrace();
     }
+
     // Prepend with file:// and also encode spaces & other characters
     Base.openURL(file.toURI().toString());
   }
diff --git a/app/src/processing/app/Library.java b/app/src/processing/app/Library.java
@@ -514,4 +514,26 @@ static protected void list(File folder, ArrayList<Library> libraries) {
   public ContributionType getType() {
     return ContributionType.LIBRARY;
   }
+
+
+  /**
+   * Returns the object stored in the referenceFile field, which contains an
+   * instance of the file object representing the index file of the reference
+   * 
+   * @return referenceFile
+   */
+  public File getReferenceIndexFile() {
+    return referenceFile;
+  }
+
+
+  /**
+   * Tests whether the reference's index file indicated by referenceFile exists.
+   * 
+   * @return true if and only if the file denoted by referenceFile exists; false
+   *         otherwise.
+   */
+  public boolean hasReference() {
+    return referenceFile.exists();
+  }
 }
diff --git a/app/src/processing/app/contrib/ToolContribution.java b/app/src/processing/app/contrib/ToolContribution.java
@@ -35,6 +35,7 @@
 public class ToolContribution extends LocalContribution implements Tool {
   private Tool tool;
 
+  private File referenceFile; // shortname/reference/index.html
 
   static public ToolContribution load(File folder) {
     try {
@@ -59,6 +60,8 @@ private ToolContribution(File folder) throws Exception {
       Class<?> toolClass = loader.loadClass(className);
       tool = (Tool) toolClass.newInstance();
     }
+
+    referenceFile = new File(folder, "reference/index.html");
   }
 
 
@@ -153,4 +156,26 @@ public String getMenuTitle() {
   public ContributionType getType() {
     return ContributionType.TOOL;
   }
+
+
+  /**
+   * Returns the object stored in the referenceFile field, which contains an
+   * instance of the file object representing the index file of the reference
+   * 
+   * @return referenceFile
+   */
+  public File getReferenceIndexFile() {
+    return referenceFile;
+  }
+
+
+  /**
+   * Tests whether the reference's index file indicated by referenceFile exists.
+   * 
+   * @return true if and only if the file denoted by referenceFile exists; false
+   *         otherwise.
+   */
+  public boolean hasReference() {
+    return referenceFile.exists();
+  }
 }
diff --git a/app/src/processing/mode/java/JavaEditor.java b/app/src/processing/mode/java/JavaEditor.java
@@ -4,12 +4,17 @@
 import java.awt.event.*;
 import java.beans.*;
 import java.io.*;
+import java.util.ArrayList;
+import java.util.Iterator;
 
 import javax.swing.*;
 import javax.swing.border.*;
+import javax.swing.event.MenuEvent;
+import javax.swing.event.MenuListener;
 
 import processing.app.*;
 import processing.app.Toolkit;
+import processing.app.contrib.ToolContribution;
 import processing.mode.java.runner.Runner;
 
 
@@ -134,6 +139,100 @@ public void actionPerformed(ActionEvent e) {
       }
     });
     menu.add(item);
+    
+    menu.addSeparator();
+    
+    final JMenu libRefSubmenu = new JMenu(Language.text("menu.help.libraries_reference"));
+    // Populate only when sub-menu is opened, to avoid having spurious menu 
+    // options if a library is deleted, or a missing menu option if a library is added
+    libRefSubmenu.addMenuListener(new MenuListener() {
+      
+      @Override
+      public void menuSelected(MenuEvent e) {
+        boolean isCoreLibMenuItemAdded = false;
+        boolean isContribLibMenuItemAdded = false;
+        
+        // Adding this in case references are included in a core library,
+        // or other core libraries are incuded in future
+        isCoreLibMenuItemAdded = addLibReferencesToSubMenu(mode.coreLibraries, libRefSubmenu);
+        
+        if (isCoreLibMenuItemAdded && !mode.contribLibraries.isEmpty())
+          libRefSubmenu.addSeparator();
+        
+        isContribLibMenuItemAdded = addLibReferencesToSubMenu(mode.contribLibraries, libRefSubmenu);
+        
+        if (!isContribLibMenuItemAdded && !isCoreLibMenuItemAdded) {
+          JMenuItem emptyMenuItem = new JMenuItem(Language.text("menu.help.empty"));
+          emptyMenuItem.setEnabled(false);
+          emptyMenuItem.setFocusable(false);
+          emptyMenuItem.setFocusPainted(false);
+          libRefSubmenu.add(emptyMenuItem);
+        }
+        else if (!isContribLibMenuItemAdded && !mode.coreLibraries.isEmpty()) {
+          //re-populate the menu to get rid of terminal separator
+          libRefSubmenu.removeAll();
+          addLibReferencesToSubMenu(mode.coreLibraries, libRefSubmenu);
+        }
+      }
+      
+      @Override
+      public void menuDeselected(MenuEvent e) {
+        libRefSubmenu.removeAll();
+      }
+      
+      @Override
+      public void menuCanceled(MenuEvent e) {
+        menuDeselected(e);
+      }
+    });
+    menu.add(libRefSubmenu);
+    
+    final JMenu toolRefSubmenu = new JMenu(Language.text("menu.help.tools_reference"));
+    // Populate only when sub-menu is opened, to avoid having spurious menu 
+    // options if a tool is deleted, or a missing menu option if a library is added
+    toolRefSubmenu.addMenuListener(new MenuListener() {
+      
+      @Override
+      public void menuSelected(MenuEvent e) {
+        boolean isCoreToolMenuItemAdded = false;
+        boolean isContribToolMenuItemAdded = false;
+        
+        // Adding this in in case a reference folder is added for MovieMaker, or in case
+        // other core tools are introduced later
+        isCoreToolMenuItemAdded = addToolReferencesToSubMenu(getCoreTools(), toolRefSubmenu);
+        
+        if (isCoreToolMenuItemAdded && !contribTools.isEmpty())
+          toolRefSubmenu.addSeparator();
+        
+        isContribToolMenuItemAdded = addToolReferencesToSubMenu(contribTools, toolRefSubmenu);
+        
+        if (!isContribToolMenuItemAdded && !isCoreToolMenuItemAdded) {
+          toolRefSubmenu.removeAll(); // in case a separator was added
+          final JMenuItem emptyMenuItem = new JMenuItem(Language.text("menu.help.empty"));
+          emptyMenuItem.setEnabled(false);
+          emptyMenuItem.setBorderPainted(false);
+          emptyMenuItem.setFocusable(false);
+          emptyMenuItem.setFocusPainted(false);
+          toolRefSubmenu.add(emptyMenuItem);
+        }
+        else if (!isContribToolMenuItemAdded && !contribTools.isEmpty()) {
+          // re-populate the menu to get rid of terminal separator
+          toolRefSubmenu.removeAll();
+          addToolReferencesToSubMenu(getCoreTools(), toolRefSubmenu);
+        }
+      }
+      
+      @Override
+      public void menuDeselected(MenuEvent e) {
+        toolRefSubmenu.removeAll();
+      }
+      
+      @Override
+      public void menuCanceled(MenuEvent e) {
+        menuDeselected(e);
+      }
+    });
+    menu.add(toolRefSubmenu);
 
     menu.addSeparator();
     item = new JMenuItem(Language.text("menu.help.online"));
@@ -184,6 +283,81 @@ public void actionPerformed(ActionEvent e) {
   }
 
 
+  //. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
+
+
+  /**
+   * Populates the JMenu with JMenuItems, one for each Library that has a
+   * reference accompanying it. The JMenuItems open the index.htm/index.html
+   * file of the reference in the user's default browser, or the readme.txt in
+   * the user's default text editor.
+   * 
+   * @param libsList
+   *          A list of the Libraries to be added
+   * @param subMenu
+   *          The JMenu to which the JMenuItems corresponding to the Libraries
+   *          are to be added
+   * @return true if and only if any JMenuItems were added; false otherwise
+   */
+  private boolean addLibReferencesToSubMenu(ArrayList<Library> libsList, JMenu subMenu) {
+    boolean isItemAdded = false;
+    Iterator<Library> iter = libsList.iterator();
+    while (iter.hasNext()) {
+      final Library libContrib = iter.next();
+      if (libContrib.hasReference()) {
+        JMenuItem libRefItem = new JMenuItem(libContrib.getName());
+        libRefItem.addActionListener(new ActionListener() {
+
+          @Override
+          public void actionPerformed(ActionEvent arg0) {
+            showReferenceFile(libContrib.getReferenceIndexFile());
+          }
+        });
+        subMenu.add(libRefItem);
+        isItemAdded = true;
+      }
+    }
+    return isItemAdded;
+  }
+
+
+  /**
+   * 
+   * Populates the JMenu with JMenuItems, one for each Tool that has a reference
+   * accompanying it. The JMenuItems open the index.htm/index.html file of the
+   * reference in the user's default browser, or the readme.txt in the user's
+   * default text editor.
+   * 
+   * @param toolsList
+   *          A list of Tools to be added
+   * @param subMenu
+   *          The JMenu to which the JMenuItems corresponding to the Tools are
+   *          to be added
+   * @return true if and only if any JMenuItems were added; false otherwise
+   */
+  private boolean addToolReferencesToSubMenu(ArrayList<ToolContribution> toolsList, JMenu subMenu) {
+    boolean isItemAdded = false;
+    Iterator<ToolContribution> iter = toolsList.iterator();
+    while (iter.hasNext()) {
+      final ToolContribution toolContrib = iter.next();
+      final File toolRef = new File(toolContrib.getFolder(), "reference/index.html");
+      if (toolRef.exists()) {
+        JMenuItem libRefItem = new JMenuItem(toolContrib.getName());
+        libRefItem.addActionListener(new ActionListener() {
+
+          @Override
+          public void actionPerformed(ActionEvent arg0) {
+            showReferenceFile(toolRef);
+          }
+        });
+        subMenu.add(libRefItem);
+        isItemAdded = true;
+      }
+    }
+    return isItemAdded;
+  }
+
+
   // . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
 
 
diff --git a/build/shared/lib/languages/PDE.properties b/build/shared/lib/languages/PDE.properties
@@ -105,6 +105,9 @@ menu.help.about = About Processing
 menu.help.environment = Environment
 menu.help.reference = Reference
 menu.help.find_in_reference = Find in Reference
+menu.help.libraries_reference = Libraries Reference
+menu.help.tools_reference = Tools Reference
+menu.help.empty = (empty)
 menu.help.online = Online
 menu.help.getting_started = Getting Started
 menu.help.getting_started.url = http://processing.org/learning/gettingstarted/
