Creating Actions

Creating a Custom Action

Custom actions extend the abstract class AnAction. Classes that extend it should override AnAction.update() and must override AnAction.actionPerformed().

As an example, PopupDialogAction overrides AnAction for the action_basics code sample.

public class PopupDialogAction extends AnAction {

  @Override
  public void update(@NotNull AnActionEvent event) {
    // Using the event, evaluate the context,
    // and enable or disable the action.
  }

  @Override
  public void actionPerformed(@NotNull AnActionEvent event) {
    // Using the event, implement an action.
    // For example, create and show a dialog.
  }

  // Override getActionUpdateThread() when you target 2022.3 or later!

}

At this stage, update() implicitly defaults always to enable this action. The implementation of actionPerformed() does nothing. These methods are fully implemented in Developing the AnAction Methods below.

Before fleshing out those methods, to complete this minimal implementation, PopupDialogAction must be registered with the IntelliJ Platform.

Registering a Custom Action

Registering an Action with the New Action Form

To register PopupDialogAction and set up its basic attributes, press Alt+Shift+Enter. Fill out the New Action form to set up the parameters for PopupDialogAction:

In this case, PopupDialogAction would be available in the Tools menu, it would be placed at the top, and would have no shortcuts.

<actions>
  <action
      id="org.intellij.sdk.action.PopupDialogAction"
      class="org.intellij.sdk.action.PopupDialogAction"
      text="Popup Dialog Action"
      description="SDK action example">
    <add-to-group group-id="ToolsMenu" anchor="first"/>
  </action>
</actions>

Setting Registration Attributes Manually

The <action> declaration for PopupDialogAction in the action_basics plugin.xml file. It also contains an attribute for an Icon and encloses elements declaring text overrides, keyboard and mouse shortcuts, and to which menu group the action should be added.

<action
    id="org.intellij.sdk.action.PopupDialogAction"
    class="org.intellij.sdk.action.PopupDialogAction"
    text="Action Basics Plugin: Popup Dialog Action"
    description="SDK action example"
    icon="SdkIcons.Sdk_default_icon">
  <override-text place="MainMenu" text="Popup Dialog Action"/>
  <keyboard-shortcut
      keymap="$default"
      first-keystroke="control alt A"
      second-keystroke="C"/>
  <mouse-shortcut
      keymap="$default"
      keystroke="control button3 doubleClick"/>
  <add-to-group group-id="ToolsMenu" anchor="first"/>
</action>

Testing the Minimal Custom Action Implementation

To see the alternate, more verbose text declared by the override-text element, use Help | Find Action... and search for "Pop Dialog Action". The search shows the verbose menu text in a context outside the main menu:

Developing the `AnAction` Methods

At this point, the new action PopupDialogAction is registered with the IntelliJ Platform and functions in the sense that update() and actionPerformed() are called in response to user interaction with the IDE Tools menu. However, neither method implements any code to perform useful work.

This section describes adding useful code to these methods. The update() method defaults to always enable the action, which is satisfactory for intermediate testing. So actionPerformed() will be developed first.

Extending the `actionPerformed()` Method

Adding code to the PopupDialogAction.actionPerformed() method makes the action do something useful. The code below gets information from the anActionEvent input parameter and constructs a message dialog. A generic icon, and the message and title attributes from the invoking menu action are displayed. However, code in this method could manipulate a project, invoke an inspection, change the contents of a file, etc.

For demonstration purposes, the AnActionEvent.getData() method tests if a Navigatable object is available. If so, information about the selected element is added to the dialog.

See Determining the Action Context for more information about accessing information from the AnActionEvent input parameter.

@Override
public void actionPerformed(@NotNull AnActionEvent event) {
  // Using the event, create and show a dialog
  Project currentProject = event.getProject();
  StringBuilder message =
      new StringBuilder(event.getPresentation().getText() + " Selected!");
  // If an element is selected in the editor, add info about it.
  Navigatable selectedElement = event.getData(CommonDataKeys.NAVIGATABLE);
  if (selectedElement != null) {
    message.append("\nSelected Element: ").append(selectedElement);
  }
  String title = event.getPresentation().getDescription();
  Messages.showMessageDialog(
      currentProject,
      message.toString(),
      title,
      Messages.getInformationIcon());
}

Extending the `update()` Method

Adding code to PopupDialogAction.update() gives finer control of the action's visibility and availability. The action's state and(or) presentation can be dynamically changed depending on the context.

In this example, the update() method relies on a Project object being available. This requirement means the user must have at least one project open in the IDE for the PopupDialogAction to be available. So the update() method disables the action for contexts where a Project object isn't defined.

The availability (enabled and visible) is set on the Presentation object. Setting both the enabled state and visibility produces consistent behavior despite possible host menu settings, as discussed in Grouping Actions.

@Override
public void update(AnActionEvent e) {
  // Set the availability based on whether a project is open
  Project project = e.getProject();
  e.getPresentation().setEnabledAndVisible(project != null);
}

The update() method does not check to see if a Navigatable object is available before enabling PopupDialogAction. This check is unnecessary because using the Navigatable object is opportunistic in actionPerformed(). See Determining the Action Context for more information about accessing information from the AnActionEvent input parameter.

Creating Actions﻿

Creating a Custom Action﻿

warning

Registering a Custom Action﻿

Registering an Action with the New Action Form﻿

Setting Registration Attributes Manually﻿

Using override-text for an Action﻿

tip

Testing the Minimal Custom Action Implementation﻿

Developing the AnAction Methods﻿

Extending the actionPerformed() Method﻿

Extending the update() Method﻿

warning

Other Methods Overrides﻿

Testing the Custom Action﻿