Add bindings for the designer treeview

pmd-core/src/main/java/net/sourceforge/pmd/util/designerbindings/DesignerBindings.java

@@ -4,9 +4,16 @@
 
 package net.sourceforge.pmd.util.designerbindings;
 
+import java.util.Collection;
+import java.util.Collections;
+
 import net.sourceforge.pmd.annotation.Experimental;
+import net.sourceforge.pmd.lang.ast.Node;
+import net.sourceforge.pmd.lang.ast.xpath.Attribute;
 import net.sourceforge.pmd.lang.symboltable.ScopedNode;
 
+import com.sun.istack.internal.Nullable;
+
 /**
  * Gathers some services to customise how language implementations bind
  * to the designer.
@@ -25,6 +32,103 @@ public interface DesignerBindings {
     RelatedNodesSelector getRelatedNodesSelector();
 
 
+    /**
+     * Returns a collection of "additional information" entries pertaining to
+     * the given node. An entry may look like {@code ("Type = List<String>", 0)},
+     * or show the result of an XPath function. The information is shown
+     * when the node is displayed.
+     *
+     * <p>Order of the collection is unimportant, it's sorted using
+     * {@link AdditionalInfo#getAlphaSortKey()}.
+     */
+    @Nullable
+    Collection<AdditionalInfo> getAdditionalInfo(Node node);
+
+
+    /**
+     * An entry for the "additional info" panel.
+     */
+    class AdditionalInfo {
+
+        private final String alphaKey;
+        private final String display;
+
+
+        public AdditionalInfo(String alphaKey, String display) {
+            this.alphaKey = alphaKey;
+            this.display = display;
+        }
+
+        /**
+         * Returns the string used to sort the additional info.
+         * For example, returning {@code "A"} ensures this is displayed
+         * first, provided there's no other entry with an {@code "A"}.
+         */
+        public String getAlphaSortKey() {
+            return alphaKey;
+        }
+
+        /**
+         * Returns the string displayed to the user.
+         */
+        public String getDisplayString() {
+            return display;
+        }
+    }
+
+
+    /**
+     * Returns the "main" attribute of the given node.
+     * The string representation of this attribute ({@link Attribute#getStringValue()})
+     * will be displayed next to the node type in the treeview. For
+     * example, for a numeric literal, this could return the attribute
+     * {@code (@IntValue, 1)}, for a class declaration, it could return the name
+     * of the class (eg {@code (@SimpleName, String)}.
+     *
+     * <p>If there's no obvious "main" attribute, or if the node is not
+     * supported, returns null. If the returned attribute is non-null,
+     * but its string value is, the return value is ignored.
+     *
+     * <p>Note: the attribute doesn't need to originate from
+     * {@link Node#getXPathAttributesIterator()}, it can be constructed
+     * ad-hoc. The name of the attribute should be a valid name for the
+     * XPath attribute though.
+     *
+     * <p>This method is meant to break the designer's dependency on {@link Node#getImage()}.
+     */
+    @Nullable
+    Attribute getMainAttribute(Node node);
+
+
+    /**
+     * Returns true if the children of this node should be displayed in
+     * the treeview by default. Returning "true" is the safe default value.
+     */
+    boolean isExpandedByDefaultInTree(Node node);
+
+
+    /**
+     * Returns a constant describing an icon that the node should bear
+     * in the treeview and other relevant places. Returns null if no icon
+     * is applicable.
+     */
+    @Nullable
+    TreeIconId getIcon(Node node);
+
+
+    /**
+     * See {@link #getIcon(Node)}.
+     */
+    @Experimental
+    enum TreeIconId {
+        CLASS,
+        METHOD,
+        CONSTRUCTOR,
+        FIELD,
+        LOCAL_VAR
+    }
+
+
     /**
      * A base implementation for {@link DesignerBindings}.
      */
@@ -37,6 +141,30 @@ public interface DesignerBindings {
             return null;
         }
 
+        @Override
+        public Collection<AdditionalInfo> getAdditionalInfo(Node node) {
+            return Collections.emptyList();
+        }
+
+        @Override
+        public Attribute getMainAttribute(Node node) {
+            String image = node.getImage();
+            if (image != null) {
+                return new Attribute(node, "Image", image);
+            }
+            return null;
+        }
+
+        @Override
+        public boolean isExpandedByDefaultInTree(Node node) {
+            return true;
+        }
+
+        @Override
+        public TreeIconId getIcon(Node node) {
+            return null;
+        }
+
         /** Returns the default instance. */
         public static DefaultDesignerBindings getInstance() {
             return INSTANCE;