The actions system allows plugins to add their items to IntelliJ Platform-based IDE menus and toolbars. For example, one of the action classes is responsible for the Open... toolbar button.menu item and the
Actions in the IntelliJ Platform require a code implementation and must be registered. The action implementation determines the contexts in which an action is available, and its functionality when selected in the UI. Registration determines where an action appears in the IDE UI. Once implemented and registered, an action receives callbacks from the IntelliJ Platform in response to user gestures.
An action is a class derived from the abstract class
AnAction. The IntelliJ Platform calls methods of actions when a user interacts with a menu item or toolbar button.
Principal Implementation Overrides
Every IntelliJ Platform action should override
AnAction.update() and must override
An action's method
AnAction.update()is called by the IntelliJ Platform framework to update an action state. The state (enabled, visible) of an action determines whether the action is available in the UI. An object of the
AnActionEventtype is passed to this method and contains information about the current context for the action. Actions are made available by changing state in the
Presentationobject associated with the event context. As explained in Overriding the
AnAction.update()Method, it is vital
update()methods execute quickly and return execution to platform.
AnAction.getActionUpdateThread()(2022.3+) return an
ActionUpdateThread, which specifies if the
update()method is called on a background thread (BGT) or the event-dispatching thread (EDT). The preferred method is to run the update on the BGT, which has the advantage of guaranteeing application-wide read access to PSI, the virtual file system (VFS), or project models. Actions that run the update session on the BGT should not access the Swing component hierarchy directly. Conversely, actions that specify to run their update on the EDT must not access PSI, VFS, or project data but have access to Swing components and other UI models. All accessible data is provided by the
DataContextas explained in Determining the Action Context. When switching from BGT to EDT is absolutely necessary, actions can use
AnActionEvent.getUpdateSession()to access the
UpdateSessionand then call
UpdateSession.compute()to run a function on the EDT. Starting from IntelliJ Platform version 2022.3, the Plugin DevKit will have an inspection in to notify plugin authors about a missing implementation of
An action's method
AnAction.actionPerformed()is called by the IntelliJ Platform if available and selected by the user. This method does the heavy lifting for the action: it contains the code executed when the action gets invoked. The
actionPerformed()method also receives
AnActionEventas a parameter, which is used to access any context data like projects, files, selection, etc. See Overriding the
AnAction.actionPerformed()Method for more information.
There are other methods to override in the
AnAction class, such as changing the default
Presentation object for the action. There is also a use case for overriding action constructors when registering them with dynamic action groups, demonstrated in the Grouping Actions tutorial.
Overriding the AnAction.update Method
AnAction.update() is periodically called by the IntelliJ Platform in response to user gestures. The
update() method gives an action to evaluate the current context and enable or disable its functionality. Implementors must ensure that changing presentation and availability status handles all variants and state transitions; otherwise, the given Action will get "stuck".
Determining the Action Context
AnActionEvent object passed to
update() carries information about the current context for the action. Context information is available from the methods of
AnActionEvent, providing information such as the Presentation and whether the action is triggered by a Toolbar. Additional context information is available using the method
AnActionEvent.getData(). Keys defined e.g. in
CommonDataKeys are passed to the
getData() method to retrieve objects such as
PsiFile, and other information. Accessing this information is relatively light-weight and is suited for
Enabling and Setting Visibility for an Action
Based on information about the action context, the
AnAction.update() method can enable, disable, or hide an action. An action's enabled/disabled state and visibility are set using methods of the
Presentation object, which is accessed using
Presentation object is a set of descriptive information about a menu or toolbar action. Every context for an action - it might appear in multiple menus, toolbars, or Navigation search locations - has a unique presentation. Attributes such as an action's text, description, and icons and visibility and enable/disable state, are stored in the presentation. The attributes in a presentation get initialized from the action registration. However, some can be changed at runtime using the methods of the
Presentation object associated with an action.
The enabled/disabled state of an action is set using
Presentation.setEnabled(). The visibility state of an action is set using
Presentation.setVisible(). If an action is enabled, the
AnAction.actionPerformed() can be called if a user selects an action in the IDE. A menu action shows in the UI location specified in its registration. A toolbar action displays its enabled (or selected) icon, depending on the user interaction.
When an action is disabled
AnAction.actionPerformed() will not be called. Toolbar actions display their respective icons for the disabled state. The visibility of a disabled action in a menu depends on whether the host menu (e.g., "ToolsMenu") containing the action has the
compact attribute set. See Grouping Actions for more information about the
compact attribute and menu actions' visibility.
An example of enabling a menu action based on whether a project is open is demonstrated in
Overriding the AnAction.actionPerformed Method
When the user selects an enabled action, be it from a menu or toolbar, the action's
AnAction.actionPerformed() method is called. This method contains the code executed to perform the action, and it is here that the real work gets done.
By using the
AnActionEvent methods and
CommonDataKeys, objects such as the
PsiFile, and other information is available. For example, the
actionPerformed() method can modify, remove, or add PSI elements to a file open in the editor.
The code that executes in the
AnAction.actionPerformed() method should execute efficiently, but it does not have to meet the same stringent requirements as the
An example of inspecting PSI elements is demonstrated in the SDK code sample
Every action and action group has a unique identifier. Basing the identifier for a custom action on the fully qualified name of the implementation is the best practice, assuming the package incorporates the
<id> of the plugin. Including the plugin identifier in the action identifier should prevent it from clashing with other plugins' actions. An action must have a unique identifier for each place. It is used in the IDE UI, even though the FQN of the implementation is the same. Definitions of identifiers for the standard IntelliJ Platform actions are in
Groups organize actions into logical UI structures, which in turn can contain other groups. A group of actions can form a toolbar or a menu. Subgroups of a group can form submenus of a menu.
Actions can be included in multiple groups, and thus appear in different places within the UI. An action must have a unique identifier for each place it appears in the UI. See the Action Declaration Reference section for information about how to specify locations.
Presentation gets created for every place where the action appears. Therefore, the same action can have a different text or icon when it appears in different places of the user interface. Different presentations for the action are created by copying the Presentation returned by the
compact attribute specifies whether an action within that group is visible when disabled. See Registering Actions in plugin.xml for an explanation of how the
compact attribute is set for a group. If the
compact attribute is
true for a menu group, an action in the menu only appears if its state is both enabled and visible. In contrast, if the
compact attribute is
false, an action in the menu appears if its state is disabled but visible. Some menus like have the
compact attribute set, so there isn't a way to show an action on the menu if it is not enabled.
Menu Item Visible?
Menu Item Appears Gray?
All other combinations of
compact, visibility, and enablement produce N/A for gray appearance because the menu item isn't visible.
See the Grouping Actions tutorial for examples of creating action groups.
Registering Actions in plugin.xml
Registering actions in plugin.xml is demonstrated in the following reference examples, which document all elements and attributes used in the
<actions> section and describe each element's meaning.
Setting the Override-Text Element
Beginning in 2020.1, an alternate version of an action's menu text can be declared for use depending on where an action appears. Using the
<override-text> element, the menu text for an action can be different depending on context: menu location, toolbar, etc. This is also available for groups in 2020.3 and later.
<action> element reference example (below) with
VssIntegration.GarbageCollection, the default is to use the menu text "Garbage Collector: Collect _Garbage." The
<add-to-group> element declares the action is added to the menu.
<override-text> element declares that text for
VssIntegration.GarbageCollection displayed anywhere in the main menu system should be the alternate text "Collect _Garbage." The menu is part of the main menu, so the displayed menu text is "Collect _Garbage." A different context, such as searching for the action using , displays the default text "Garbage Collector: Collect _Garbage" to give the user additional information about the action.
<override-text> element uses
use-text-of-place attributes to declare the same version of the text used in the main menu is also used in the editor popup menu. Additional
<override-text> elements could be used to specify other places where the main menu text should be used.
An example of using
<override-text> is demonstrated in the Creating Actions tutorial.
Setting the Synonym Element
2020.3 Users can locate actions via their name by invoking .
To provide a localized synonym, specify
key instead of
Disabling Search for Group
2020.3 To exclude a group from appearing in results (e.g., New... popup), specify
Localizing Actions and Groups
Action and group localization use resource bundles containing property files named $NAME$Bundle.properties, each file consisting of
key=value pairs. The
action_basics plugin demonstrates using a resource bundle to localize the group and action entries added to the Editor Popup Menu.
When localizing actions and groups, the
description attributes are not declared in plugin.xml. Instead, those attribute values vary depending on the locale and get declared in a resource bundle.
The name and location of the resource bundle must be declared in the plugin.xml file. In the case of
action_basics, only a default localization resource bundle (/resources/messages/BasicActionsBundle.properties) is provided:
2020.1 If necessary, a dedicated resource bundle to use for actions and groups can be defined on
See Extending DefaultActionGroup for a tutorial of localizing Actions and Groups.
For Actions, the key in property files incorporates the action
id in this specific structure:
action.<action-id>.text=Translated Action Text
action.<action-id>.description=Translated Action Description
<override-text> is used for an action
id, the key includes the
action.<action-id>.<place>.text=Place-dependent Translated Action Text
For Groups, the
key in the property files incorporates the group
id in this specific structure:
group.<group-id>.text=Translated Group Text
group.<group-id>.description=Translated Group Description
<override-text> is used for a group
id, the key includes the
group.<group-id>.<place>.text=Place-dependent Translated Group Text
Action Declaration Reference
Registering Actions from Code
Two steps are required to register an action from code:
First, an instance of the class derived from
AnActionmust be passed to the
ActionManager, to associate the action with an ID.
Second, the action needs to be added to one or more groups. To get an instance of an action group by ID, it is necessary to call
ActionManager.getAction()and cast the returned value to
Building UI from Actions
If a plugin needs to include a toolbar or popup menu built from a group of actions in its user interface, that is accomplished through
ActionToolbar. These objects can be created through calls to the
createActionToolbar() methods. To get a Swing component from such an object, call the respective
If an action toolbar is attached to a specific component (for example, a panel in a tool window), call
ActionToolbar.setTargetComponent() and pass the related component's instance as a parameter. Setting the target ensures that the toolbar buttons' state depends on the state of the related component, not on the current focus location within the IDE frame.
See Toolbar in IntelliJ Platform UI Guidelines for an overview.