Merge pull request #108 from JohnHake/master

Refactor register_actions code and documentation.

register_actions/resources/META-INF/plugin.xml

@@ -1,12 +1,12 @@
 <idea-plugin>
-  <id>org.jetbrains.plugins.sample.RegisterActions</id>
+  <id>org.jetbrains.tutorials.actions.RegisterActions</id>
   <name>Sample plugin for working with IntelliJ Action System</name>
-  <version>1.0</version>
+  <version>1.1</version>
   <vendor email="support@jetbrains.com" url="http://www.jetbrains.com">JetBrains</vendor>
 
-  <description>Illustration of Action System</description>
+  <description>Illustration of the Action System</description>
 
-  <change-notes>Initial commit</change-notes>
+  <change-notes>Refactor to give users feedback when menu items are selected.</change-notes>
 
   <!-- please see http://www.jetbrains.org/intellij/sdk/docs/basics/getting_started/build_number_ranges.html for description -->
   <idea-version since-build="131"/>
@@ -39,7 +39,7 @@
     The optional "use-shortcut-of" attribute specifies the ID of the action whose keyboard shortcut this action will use.
     The optional "description" attribute specifies the text which is displayed in the status bar when the action is focused.
     The optional "icon" attribute specifies the icon which is displayed on the toolbar button or next to the menu item. -->
-    <action id="org.jetbrains.tutorials.actions.SimpleAction" class="org.jetbrains.tutorials.actions.SimpleAction"
+    <action id="org.jetbrains.tutorials.actions.SimpleAction" class="org.jetbrains.tutorials.actions.SimplePopDialogAction"
             text="Simple Action" description="IntelliJ Action System Demo">
       <!-- The <keyboard-shortcut> node specifies the keyboard shortcut for the action. An action can have several keyboard shortcuts.
       The mandatory "first-keystroke" attribute specifies the first keystroke of the action. The key strokes are specified according to the regular Swing rules.
@@ -63,21 +63,45 @@
       the current action is inserted. -->
       <add-to-group group-id="ToolsMenu" anchor="first"/>
     </action>
-    <group id="SimpleGroup" text="Custom Action Group" popup="true">
+    <!--
-      <add-to-group group-id="EditorPopupMenu" anchor="first"/>
+    The <group> element defines an action group to register.
-      <action class="org.jetbrains.tutorials.actions.GroupedAction" id="org.jetbrains.tutorials.actions.GroupedAction"
+        "id" attribute - mandatory, specifies an unique identifier for the group.
-              text="Grouped Action" description="Grouped Action Demo">
+        "class" attribute - optional, specifies the full-qualified name of the class implementing the group.
+          If omitted, the ActionGroup implementation will be constructed by the IntelliJ Platform Framework.
+        "popup" attribute - mandatory, specifies whether the group will be shown as a popup in menus.
+        "text" attribute - mandatory, specifies the text of the action group to be displayed in the menu, or tooltip for toolbar button.
+        "description" attribute - optional, specifies the text which is displayed in the status bar when the action is focused.
+        "icon" attribute - optional, specifies the icon which is displayed on the toolbar button or next to the menu item.
+      The <add-to-group> element - see documentation above for attributes.
+      The <action> element - optional, used for static declarations of action(s) within a group, but can be
+      omitted if actions will be added at runtime. See documentation above for attributes.
+    -->
+    <!-- All off the following menu groups add the action SimplePopDialogAction to menus in different ways.
+      Note the action ids are unique. -->
+    <!-- GroupedActions demonstrates declaring an action group using the default ActionGroup implementation provided by the
+      IntelliJ Platform framework. (Note the lack of a "class" attribute.) GroupedActions gets inserted after SimpleAction
+      in the Tools menu. Because the group's implementation is default, it cannot impose enable/disable conditions. Instead it
+      must rely on the conditions imposed by the parent menu where it is inserted. It declares one action in the group. -->
+    <group id="org.jetbrains.tutorials.actions.GroupedActions" text="Example Grouped Actions" popup="true">
+      <add-to-group group-id="ToolsMenu" anchor="after" relative-to-action="org.jetbrains.tutorials.actions.SimpleAction"/>
+      <action class="org.jetbrains.tutorials.actions.SimplePopDialogAction" id="org.jetbrains.tutorials.actions.SimpleGroupedAction"
+              text="A Grouped Action" description="Grouped Action Demo">
       </action>
     </group>
-    <group id="CustomDefaultActionGroup" class="org.jetbrains.tutorials.actions.CustomDefaultActionGroup" popup="true"
+    <!-- CustomDefaultActionGroup demonstrates declaring an action group based on a ActionGroup class supplied by this plugin.
-           text="DefaultActionGroup Inheritor" description="Default Action Group Demo">
+      This group is to be inserted atop the Editor Popup Menu. It declares one action in the group. -->
-      <add-to-group group-id="ToolsMenu" anchor="last"/>
+    <group id="org.jetbrains.tutorials.actions.ExampleCustomDefaultActionGroup" class="org.jetbrains.tutorials.actions.CustomDefaultActionGroup" popup="true"
-      <action class="org.jetbrains.tutorials.actions.CustomGroupedAction" id="CustomGroupedAction"
+           text="Example Custom DefaultActionGroup" description="Custom DefaultActionGroup Demo">
-              text="Custom Grouped Action" description="Custom Grouped Action Demo"/>
+      <add-to-group group-id="EditorPopupMenu" anchor="first"/>
+      <action class="org.jetbrains.tutorials.actions.SimplePopDialogAction" id="org.jetbrains.tutorials.actions.CustomGroupedAction"
+              text="A Custom Grouped Action" description="Custom Grouped Action Demo"/>
     </group>
-    <group id="BaseActionGroup" class="org.jetbrains.tutorials.actions.BaseActionGroup" popup="true"
+    <!-- DynamicActionGroup demonstrates declaring an action group without a static action declaration.
-           text="ActionGroup Demo" description="Extending AnAction Demo">
+     An action is added to the group programmatically in the DynamicActionGroup implementation. The group is added
-      <add-to-group group-id="ToolsMenu" anchor="first"/>
+     last in the tools menu. -->
+    <group id="org.jetbrains.tutorials.actions.DynamicActionGroup" class="org.jetbrains.tutorials.actions.DynamicActionGroup" popup="true"
+           text="Dynamic ActionGroup" description="Dynamic ActionGroup Demo">
+      <add-to-group group-id="ToolsMenu" anchor="last"/>
     </group>
   </actions>
 </idea-plugin>

register_actions/src/org/jetbrains/tutorials/actions/BaseActionGroup.java

@@ -1,26 +0,0 @@
-package org.jetbrains.tutorials.actions;
-
-import com.intellij.openapi.actionSystem.*;
-import org.jetbrains.annotations.NotNull;
-
-/**
- * @author Anna Bulenkova
- */
-public class BaseActionGroup extends ActionGroup {
-  @NotNull
-  @Override
-  public AnAction[] getChildren(AnActionEvent anActionEvent) {
-    return new AnAction[]{new MyAction()};
-  }
-
-  class MyAction extends AnAction {
-    public MyAction() {
-      super("Dynamically Added Action");
-    }
-
-    @Override
-    public void actionPerformed(@NotNull AnActionEvent anActionEvent) {
-      //does nothing
-    }
-  }
-}

register_actions/src/org/jetbrains/tutorials/actions/CustomDefaultActionGroup.java

@@ -1,18 +1,37 @@
+/*
+ * Copyright 2000-2018 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license that can be found in the LICENSE file.
+ */
+
 package org.jetbrains.tutorials.actions;
 
 import com.intellij.icons.AllIcons;
-import com.intellij.openapi.actionSystem.*;
+import com.intellij.openapi.actionSystem.AnActionEvent;
+import com.intellij.openapi.actionSystem.CommonDataKeys;
+import com.intellij.openapi.actionSystem.DefaultActionGroup;
 import com.intellij.openapi.editor.Editor;
 
 /**
+ * Creates an action group to contain menu actions. See plugin.xml declarations.
+ * @see DefaultActionGroup
  * @author Anna Bulenkova
  */
 public class CustomDefaultActionGroup extends DefaultActionGroup {
+
+  /**
+   * Given CustomDefaultActionGroup is derived from AnAction, in this context
+   * update() determines whether the action group itself should be enabled or disabled.
+   * Requires an editor to be active in order to enable the group functionality.
+   * @see com.intellij.openapi.actionSystem.AnAction#update(AnActionEvent)
+   * @param event  Event received when the associated group-id menu is chosen.
+   */
   @Override
   public void update(AnActionEvent event) {
+    // Enable/disable depending on whether user is editing
     Editor editor = event.getData(CommonDataKeys.EDITOR);
-    event.getPresentation().setVisible(true);
     event.getPresentation().setEnabled(editor != null);
+    // Always make visible.
+    event.getPresentation().setVisible(true);
+    // Take this opportunity to set an icon for the menu entry.
     event.getPresentation().setIcon(AllIcons.General.Error);
   }
 }

register_actions/src/org/jetbrains/tutorials/actions/CustomGroupedAction.java

@@ -1,10 +0,0 @@
-package org.jetbrains.tutorials.actions;
-
-import com.intellij.openapi.actionSystem.*;
-
-public class CustomGroupedAction extends AnAction {
-  @Override
-  public void actionPerformed(AnActionEvent anActionEvent) {
-    //Does nothing
-  }
-}

register_actions/src/org/jetbrains/tutorials/actions/DynamicActionGroup.java

@@ -0,0 +1,40 @@
+/*
+ * Copyright 2000-2018 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license that can be found in the LICENSE file.
+ */
+
+package org.jetbrains.tutorials.actions;
+
+import com.intellij.openapi.actionSystem.ActionGroup;
+import com.intellij.openapi.actionSystem.AnAction;
+import com.intellij.openapi.actionSystem.AnActionEvent;
+import org.jetbrains.annotations.*;
+
+/**
+ * Demonstrates adding an action group to a menu statically in plugin.xml, and then creating a menu item
+ * within the group at runtime. See plugin.xml for the declaration of DynamicActionGroup,
+ * and note the group declaration does not contain an action.
+ * DynamicActionGroup is based on ActionGroup because menu children are determined
+ * on rules other than just positional constraints.
+ *
+ * @author Anna Bulenkova
+ * @see ActionGroup
+ */
+public class DynamicActionGroup extends ActionGroup {
+
+  /**
+   * Returns an array of menu actions for the group.
+   *
+   * @param anActionEvent Event received when the associated group-id menu is chosen.
+   * @return AnAction[]  An instance of AnAction, in this case containing a single instance of the
+   * SimplePopDialogAction class.
+   */
+  @NotNull
+  @Override
+  public AnAction[] getChildren(AnActionEvent anActionEvent) {
+    return new AnAction[]{ new SimplePopDialogAction("Action Added at Runtime",
+                                                "Dynamic Action Demo",
+                                                      null)
+                          };
+  }
+
+}

register_actions/src/org/jetbrains/tutorials/actions/GroupedAction.java

@@ -1,14 +0,0 @@
-package org.jetbrains.tutorials.actions;
-
-import com.intellij.openapi.actionSystem.*;
-
-public class GroupedAction extends AnAction {
-  @Override
-  public void update(AnActionEvent event) {
-  }
-
-  @Override
-  public void actionPerformed(AnActionEvent event) {
-    //Does nothing
-  }
-}

register_actions/src/org/jetbrains/tutorials/actions/SimpleAction.java

@@ -1,26 +0,0 @@
-package org.jetbrains.tutorials.actions;
-
-import com.intellij.openapi.actionSystem.AnAction;
-import com.intellij.openapi.actionSystem.AnActionEvent;
-import com.intellij.openapi.actionSystem.CommonDataKeys;
-import com.intellij.openapi.project.Project;
-import com.intellij.openapi.ui.Messages;
-import com.intellij.pom.Navigatable;
-
-public class SimpleAction extends AnAction {
-  @Override
-  public void actionPerformed(AnActionEvent anActionEvent) {
-    Project project = anActionEvent.getProject();
-    Navigatable navigatable = anActionEvent.getData(CommonDataKeys.NAVIGATABLE);
-    if (project != null && navigatable != null) {
-      Messages.showMessageDialog(project, navigatable.toString(), "Selected Element", Messages.getInformationIcon());
-    }
-  }
-
-  @Override
-  public void update(AnActionEvent anActionEvent) {
-    Project project = anActionEvent.getProject();
-    Navigatable navigatable = anActionEvent.getData(CommonDataKeys.NAVIGATABLE);
-      anActionEvent.getPresentation().setEnabledAndVisible(project != null && navigatable != null);
-  }
-}

register_actions/src/org/jetbrains/tutorials/actions/SimplePopDialogAction.java

@@ -0,0 +1,82 @@
+/*
+ * Copyright 2000-2018 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license that can be found in the LICENSE file.
+ */
+
+package org.jetbrains.tutorials.actions;
+
+import com.intellij.openapi.actionSystem.AnAction;
+import com.intellij.openapi.actionSystem.AnActionEvent;
+import com.intellij.openapi.actionSystem.CommonDataKeys;
+import com.intellij.openapi.project.Project;
+import com.intellij.openapi.ui.Messages;
+import com.intellij.pom.Navigatable;
+import org.jetbrains.annotations.*;
+
+import javax.swing.*;
+
+/**
+ * Action class to demonstrate how to interact with the IntelliJ Platform.
+ * The only action this class performs is to provide the user with a popup dialog as feedback.
+ * Typically this class is instantiated by the IntelliJ Platform framework based on declarations
+ * in the plugin.xml file. But when added at runtime this class is instantiated by an action group.
+ * @see com.intellij.openapi.actionSystem.AnAction
+ * @see com.intellij.openapi.actionSystem.AnActionEvent
+ */
+public class SimplePopDialogAction extends AnAction {
+
+  /**
+   * This default constructor is used by the IntelliJ Platform framework to
+   * instantiate this class based on plugin.xml declarations. Only needed in SimplePopDialogAction
+   * class because another constructor is overridden.
+   * @see AnAction#AnAction()
+   */
+  public SimplePopDialogAction() {
+    super();
+  }
+
+  /**
+   * This constructor is used to support dynamically added menu actions.
+   * It sets the text, description to be displayed for the menu item.
+   * Otherwise, the default AnAction constructor is used by the IntelliJ Platform.
+   * @see AnAction#AnAction(String, String, Icon)
+   * @param menuText  The text to be displayed as a menu item.
+   * @param menuDescription  The description of the menu item.
+   * @param menuIcon  The icon to be used with the menu item.
+   */
+  public SimplePopDialogAction(@Nullable String menuText, @Nullable String menuDescription, @Nullable Icon menuIcon) {
+    super(menuText, menuDescription, menuIcon);
+  }
+
+  /**
+   * Gives the user feedback when the dynamic action menu is chosen.
+   * Pops a simple message dialog. See the psi_demo plugin for an
+   * example of how to use AnActionEvent to access data.
+   * @param anActionEvent Event received when the associated menu item is chosen.
+   */
+  @Override
+  public void actionPerformed(@NotNull AnActionEvent anActionEvent) {
+    // Using the event, create and show a dialog
+    Project currentProject = anActionEvent.getProject();
+    StringBuffer dlgMsg = new StringBuffer(anActionEvent.getPresentation().getText() + " Selected!");
+    String dlgTitle = anActionEvent.getPresentation().getDescription();
+    // If an element is selected in the editor, add info about it.
+    Navigatable nav = anActionEvent.getData(CommonDataKeys.NAVIGATABLE);
+    if (nav != null) {
+      dlgMsg.append(String.format("\nSelected Element: %s", nav.toString()));
+    }
+    Messages.showMessageDialog(currentProject, dlgMsg.toString(), dlgTitle, Messages.getInformationIcon());
+  }
+
+  /**
+   * Determines whether this menu item is available for the current context.
+   * Requires a project to be open.
+   * @param anActionEvent Event received when the associated group-id menu is chosen.
+   */
+  @Override
+  public void update(AnActionEvent anActionEvent) {
+    // Set the availability based on whether a project is open
+    Project project = anActionEvent.getProject();
+    anActionEvent.getPresentation().setEnabledAndVisible(project != null);
+  }
+
+}