mirror of
https://github.com/JetBrains/intellij-sdk-code-samples.git
synced 2025-07-29 09:47:50 +08:00
280 lines
23 KiB
HTML
280 lines
23 KiB
HTML
|
|
|
|
|
|
<!doctype html>
|
|
<html lang="en-US">
|
|
<head>
|
|
<meta charset="UTF-8">
|
|
<title>Action System / IntelliJ Platform SDK DevGuide</title>
|
|
<link rel="stylesheet" href="/intellij/sdk/docs/app/css/styles.min.css">
|
|
|
|
<!-- non-retina iPad pre iOS 7 -->
|
|
<link rel="apple-touch-icon" href="/intellij/sdk/docs/apple-touch-icon-72x72.png" sizes="72x72">
|
|
|
|
<!-- retina iPhone pre iOS 7 -->
|
|
<link rel="apple-touch-icon" href="/intellij/sdk/docs/apple-touch-icon-114x114.png" sizes="114x114">
|
|
|
|
<!-- retina iPad pre iOS 7 -->
|
|
<link rel="apple-touch-icon" href="/intellij/sdk/docs/apple-touch-icon-144x144.png" sizes="144x144">
|
|
<link rel="apple-touch-icon-precomposed" sizes="144x144" href="/intellij/sdk/docs/apple-touch-icon-precomposed.png">
|
|
|
|
<!-- normal favicon -->
|
|
<link rel="shortcut icon" type="image/x-icon" href="/intellij/sdk/docs/favicon.ico">
|
|
<link rel="icon" type="image/png" href="/intellij/sdk/docs/favicon.png">
|
|
<link rel="stylesheet" href="/intellij/sdk/docs/styles/styles.css"></head>
|
|
<body data-id="basics/action_system">
|
|
<div class="wrapper">
|
|
<section class="panel _nav">
|
|
<header class="panel__header">
|
|
<div class="container">
|
|
<form class="search-box">
|
|
<label for="search-box__input" class="search-box__label">
|
|
<input type="text" class="search-box__input" id="search-box__input" placeholder="Search IntelliJ Platform SDK DevGuide">
|
|
</label>
|
|
<div class="search-box__clear" title="Clear"></div>
|
|
</form>
|
|
</div>
|
|
</header>
|
|
<nav class="panel__content">
|
|
<div class="container _nav">
|
|
<menu class="nav-tree"></menu>
|
|
</div>
|
|
<div class="container _footer panel__footer">
|
|
<p><a href="https://youtrack.jetbrains.com/issues/IJSDK">Send feedback</a></p>
|
|
<p>© 2000–2016 <a href="//www.jetbrains.com">JetBrains</a> s.r.o.<br>
|
|
All rights reserved.</p>
|
|
</div>
|
|
</nav>
|
|
</section>
|
|
|
|
<main class="panel _main" role="main">
|
|
<header class="panel__header">
|
|
<div class="container">
|
|
<h3>IntelliJ Platform SDK DevGuide</h3>
|
|
|
|
<div class="shortcuts-switcher"><label for="switch-shortcuts">Keymap:</label><select id="switch-shortcuts" class="select _shortcuts" height="1">
|
|
<option data-group="primary" value="default" selected>Default</option>
|
|
<option data-group="primary" value="default_for_gnome">GNOME</option>
|
|
<option data-group="primary" value="default_for_kde">KDE</option>
|
|
<option data-group="primary" value="default_for_xwin">XWindow</option>
|
|
<option data-group="primary" value="emacs">Emacs</option>
|
|
<option data-group="primary" value="jbuilder">JBuilder</option>
|
|
<option data-group="primary" value="visual_studio">Visual Studio</option>
|
|
<option data-group="primary" value="netbeans_6.5">NetBeans 6.5</option>
|
|
<option data-group="primary" value="eclipse">Eclipse</option>
|
|
<option data-group="secondary" value="mac_os_x_10.5_">OS X 10.5+</option>
|
|
<option data-group="secondary" value="mac_os_x">OS X</option>
|
|
<option data-group="secondary" value="eclipse_mac_os_x">OS X Eclipse</option></select>
|
|
</div>
|
|
|
|
<div class="panel-trigger"></div>
|
|
</div>
|
|
</header>
|
|
<section class="panel__content">
|
|
<div class="container">
|
|
<article class="article" data-shortcut-switcher="false">
|
|
|
|
<h1>Action System</h1>
|
|
<a name="executing-and-updating-actions" class="elem-anchor"></a>
|
|
<h2>Executing and updating actions<a href="#executing-and-updating-actions" class="anchor-link"><span></span></a></h2>
|
|
|
|
<p>The system of actions allows plugins to add their own items to IDEA menus and toolbars. An action is a class, derived from the <a href="https://upsource.jetbrains.com/idea-ce/file/idea-ce-1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/editor-ui-api/src/com/intellij/openapi/actionSystem/AnAction.java" data-bypass="yes" target="_blank"><span><code class="code highlight language-text">AnAction</code></span></a> class, whose <code class="code highlight language-text">actionPerformed</code> method is called when the menu item or toolbar button is selected.
|
|
For example, one of the action classes is responsible for the <strong>File | Open File…</strong> menu item and for the <strong>Open File</strong> toolbar button.</p>
|
|
|
|
<p>Actions are organized into groups, which, in turn, can contain other groups. A group of actions can form a toolbar or a menu.
|
|
Subgroups of the group can form submenus of the menu.</p>
|
|
|
|
<p>Every action and action group has an unique identifier. Identifiers of many of the standard IDEA actions are defined in the <a href="https://upsource.jetbrains.com/idea-ce/file/idea-ce-1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-api/src/com/intellij/openapi/actionSystem/IdeActions.java" data-bypass="yes" target="_blank"><span>IdeActions</span></a> class.</p>
|
|
|
|
<p>Every action can be included in multiple groups, and thus appear in multiple places within the IDEA user interface. Different places where actions can appear are defined by constants in the <a href="https://upsource.jetbrains.com/idea-ce/file/idea-ce-1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-api/src/com/intellij/openapi/actionSystem/ActionPlaces.java" data-bypass="yes" target="_blank"><span><code class="code highlight language-text">ActionPlaces</code></span></a> interface. For every place where the action appears, a new <code class="code highlight language-text">Presentation</code> is created. Thus, the same action can have different text or icons when it appears in different places of the user interface. Different presentations for the action are created by copying the presentation returned by the <code class="code highlight language-text">AnAction.getTemplatePresentation()</code> method.</p>
|
|
|
|
<p>To update the state of the action, the method <code class="code highlight language-text">AnAction.update()</code> is periodically called by IDEA. The <code class="code highlight language-text">AnActionEvent</code> object passed to this method carries the information about the current context for the action, and in particular, the specific presentation which needs to be updated.</p>
|
|
|
|
<p>To retrieve the information about the current state of the IDE, including the active project, the selected file, the selection in the editor and so on, the method <code class="code highlight language-text">AnActionEvent.getData()</code> can be used. Different data keys that can be passed to that method are defined in the <code class="code highlight language-text">DataKeys</code> class.</p>
|
|
|
|
<p>The <code class="code highlight language-text">AnActionEvent</code> instance is also passed to the <code class="code highlight language-text">actionPerformed</code> method.</p>
|
|
|
|
<a name="registering-actions" class="elem-anchor"></a>
|
|
<h2>Registering Actions<a href="#registering-actions" class="anchor-link"><span></span></a></h2>
|
|
|
|
<p>There are two main ways to register an action: either by listing it in the <code class="code highlight language-text"><actions></code> section of the <code class="code highlight language-text">plugin.xml</code> file, or through Java code.</p>
|
|
|
|
<a name="registering-actions-in-pluginxml" class="elem-anchor"></a>
|
|
<h3>Registering Actions in plugin.xml<a href="#registering-actions-in-pluginxml" class="anchor-link"><span></span></a></h3>
|
|
|
|
<p>Registering actions in <code class="code highlight language-text">plugin.xml</code> is demonstrated in the following example. The example section of <code class="code highlight language-text">plugin.xml</code> demonstrates all elements which can be used in the <code class="code highlight language-text"><actions></code> section, and describes the meaning of each element.</p>
|
|
|
|
<pre><code class="code-block__wrapper code-block _highlighted lang_xml"><span class="c"><!-- Actions --></span>
|
|
<span class="nt"><actions></span>
|
|
<span class="c"><!-- The <action> element defines an action to register.
|
|
The mandatory "id" attribute specifies an unique
|
|
identifier for the action.
|
|
The mandatory "class" attribute specifies the
|
|
full-qualified name of the class implementing the action.
|
|
The mandatory "text" attribute specifies the text of the
|
|
action (tooltip for toolbar button or text for menu item).
|
|
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. --></span>
|
|
<span class="nt"><action</span> <span class="na">id=</span><span class="s">"VssIntegration.GarbageCollection"</span> <span class="na">class=</span><span class="s">"com.foo.impl.CollectGarbage"</span> <span class="na">text=</span><span class="s">"Collect _Garbage"</span> <span class="na">description=</span><span class="s">"Run garbage collector"</span> <span class="na">icon=</span><span class="s">"icons/garbage.png"</span><span class="nt">></span>
|
|
<span class="c"><!-- The <add-to-group> node specifies that the action should be added
|
|
to an existing group. An action can be added to several groups.
|
|
The mandatory "group-id" attribute specifies the ID of the group
|
|
to which the action is added.
|
|
The group must be implemented by an instance of the DefaultActionGroup class.
|
|
The mandatory "anchor" attribute specifies the position of the
|
|
action in the group relative to other actions. It can have the values
|
|
"first", "last", "before" and "after".
|
|
The "relative-to-action" attribute is mandatory if the anchor
|
|
is set to "before" and "after", and specifies the action before or after which
|
|
the current action is inserted. --></span>
|
|
<span class="nt"><add-to-group</span> <span class="na">group-id=</span><span class="s">"ToolsMenu"</span> <span class="na">relative-to-action=</span><span class="s">"GenerateJavadoc"</span> <span class="na">anchor=</span><span class="s">"after"</span><span class="nt">/></span>
|
|
<span class="c"><!-- 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.
|
|
The optional "second-keystroke" attribute specifies the second
|
|
keystroke of the action.
|
|
The mandatory "keymap" attribute specifies the keymap for which
|
|
the action is active. IDs of the standard keymaps are defined as
|
|
constants in the com.intellij.openapi.keymap.KeymapManager class. --></span>
|
|
<span class="nt"><keyboard-shortcut</span> <span class="na">first-keystroke=</span><span class="s">"control alt G"</span> <span class="na">second-keystroke=</span><span class="s">"C"</span> <span class="na">keymap=</span><span class="s">"$default"</span><span class="nt">/></span>
|
|
<span class="c"><!-- The <mouse-shortcut> node specifies the mouse shortcut for the
|
|
action. An action can have several mouse shortcuts.
|
|
The mandatory "keystroke" attribute specifies the clicks and
|
|
modifiers for the action. It is defined as a sequence of words
|
|
separated by spaces:
|
|
"button1", "button2", "button3" for the mouse buttons;
|
|
"shift", "control", "meta", "alt", "altGraph" for the modifier keys;
|
|
"doubleClick" if the action is activated by a double-click of the button.
|
|
The mandatory "keymap" attribute specifies the keymap for which
|
|
the action is active. IDs of the standard keymaps are defined as
|
|
constants in the com.intellij.openapi.keymap.KeymapManager class. --></span>
|
|
<span class="nt"><mouse-shortcut</span> <span class="na">keystroke=</span><span class="s">"control button3 doubleClick"</span> <span class="na">keymap=</span><span class="s">"$default"</span><span class="nt">/></span>
|
|
<span class="nt"></action></span>
|
|
<span class="c"><!-- The <group> element defines an action group. <action>, <group> and
|
|
<separator> elements defined within it are automatically included in the group.
|
|
The mandatory "id" attribute specifies an unique identifier for the action.
|
|
The optional "class" attribute specifies the full-qualified name of
|
|
the class implementing the group. If not specified,
|
|
com.intellij.openapi.actionSystem.DefaultActionGroup is used.
|
|
The optional "text" attribute specifies the text of the group (text
|
|
for the menu item showing the submenu).
|
|
The optional "description" attribute specifies the text which is displayed
|
|
in the status bar when the group is focused.
|
|
The optional "icon" attribute specifies the icon which is displayed on
|
|
the toolbar button or next to the group.
|
|
The optional "popup" attribute specifies how the group is presented in
|
|
the menu. If a group has popup="true", actions in it are placed in a
|
|
submenu; for popup="false", actions are displayed as a section of the
|
|
same menu delimited by separators. --></span>
|
|
<span class="nt"><group</span> <span class="na">class=</span><span class="s">"com.foo.impl.MyActionGroup"</span> <span class="na">id=</span><span class="s">"TestActionGroup"</span> <span class="na">text=</span><span class="s">"Test Group"</span> <span class="na">description=</span><span class="s">"Group with test actions"</span> <span class="na">icon=</span><span class="s">"icons/testgroup.png"</span> <span class="na">popup=</span><span class="s">"true"</span><span class="nt">></span>
|
|
<span class="nt"><action</span> <span class="na">id=</span><span class="s">"VssIntegration.TestAction"</span> <span class="na">class=</span><span class="s">"com.foo.impl.TestAction"</span> <span class="na">text=</span><span class="s">"My Test Action"</span> <span class="na">description=</span><span class="s">"My test action"</span><span class="nt">/></span>
|
|
<span class="c"><!-- The <separator> element defines a separator between actions.
|
|
It can also have an <add-to-group> child element. --></span>
|
|
<span class="nt"><separator/></span>
|
|
<span class="nt"><group</span> <span class="na">id=</span><span class="s">"TestActionSubGroup"</span><span class="nt">/></span>
|
|
<span class="c"><!-- The <reference> element allows to add an existing action to the group.
|
|
The mandatory "ref" attribute specifies the ID of the action to add. --></span>
|
|
<span class="nt"><reference</span> <span class="na">ref=</span><span class="s">"EditorCopy"</span><span class="nt">/></span>
|
|
<span class="nt"><add-to-group</span> <span class="na">group-id=</span><span class="s">"MainMenu"</span> <span class="na">relative-to-action=</span><span class="s">"HelpMenu"</span> <span class="na">anchor=</span><span class="s">"before"</span><span class="nt">/></span>
|
|
<span class="nt"></group></span>
|
|
<span class="nt"></actions></span>
|
|
</code></pre>
|
|
|
|
<a name="registering-actions-from-code" class="elem-anchor"></a>
|
|
<h2>Registering Actions from Code<a href="#registering-actions-from-code" class="anchor-link"><span></span></a></h2>
|
|
|
|
<p>To register an action from code, two steps are required.</p>
|
|
|
|
<ul>
|
|
<li>First, an instance of the class derived from <code class="code highlight language-text">AnAction</code> must be passed to the <code class="code highlight language-text">registerAction</code> method of the <a href="https://upsource.jetbrains.com/idea-ce/file/idea-ce-1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/editor-ui-api/src/com/intellij/openapi/actionSystem/ActionManager.java" data-bypass="yes" target="_blank"><span>ActionManager</span></a> class, to associate the action with an ID.</li>
|
|
<li>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 <code class="code highlight language-text">ActionManager.getAction()</code> and cast the returned value to the <a href="https://upsource.jetbrains.com/idea-ce/file/idea-ce-1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-api/src/com/intellij/openapi/actionSystem/DefaultActionGroup.java" data-bypass="yes" target="_blank"><span>DefaultActionGroup</span></a> class.</li>
|
|
</ul>
|
|
|
|
<p>You can create a plugin that registers actions on IDEA startup using the following procedure.</p>
|
|
|
|
<p><strong>To register an action on IDEA startup</strong></p>
|
|
|
|
<ul>
|
|
<li>Create a new class that implements the <code class="code highlight language-text">ApplicationComponent</code> interface.</li>
|
|
<li>In this class, override the <code class="code highlight language-text">getComponentName</code>, <code class="code highlight language-text">initComponent</code>, and <code class="code highlight language-text">disposeComponent</code> methods.</li>
|
|
<li>Register this class in the <code class="code highlight language-text"><application-components></code> section of the plugin.xml file.</li>
|
|
</ul>
|
|
|
|
<p>To clarify the above procedure, consider the following sample Java class <code class="code highlight language-text">MyPluginRegistration</code> that registers an action defined in a custom <code class="code highlight language-text">TextBoxes</code> class and adds a new menu command to the <em>Window</em> menu group on the main menu:</p>
|
|
|
|
<pre><code class="code-block__wrapper code-block _highlighted lang_java"><span class="kd">public</span> <span class="kd">class</span> <span class="nc">MyPluginRegistration</span> <span class="kd">implements</span> <span class="n">ApplicationComponent</span> <span class="o">{</span>
|
|
<span class="c1">// Returns the component name (any unique string value).</span>
|
|
<span class="nd">@NotNull</span> <span class="kd">public</span> <span class="n">String</span> <span class="nf">getComponentName</span><span class="o">()</span> <span class="o">{</span>
|
|
<span class="k">return</span> <span class="s">"MyPlugin"</span><span class="o">;</span>
|
|
<span class="o">}</span>
|
|
|
|
|
|
<span class="c1">// If you register the MyPluginRegistration class in the <application-components> section of</span>
|
|
<span class="c1">// the plugin.xml file, this method is called on IDEA start-up.</span>
|
|
<span class="kd">public</span> <span class="kt">void</span> <span class="nf">initComponent</span><span class="o">()</span> <span class="o">{</span>
|
|
<span class="n">ActionManager</span> <span class="n">am</span> <span class="o">=</span> <span class="n">ActionManager</span><span class="o">.</span><span class="na">getInstance</span><span class="o">();</span>
|
|
<span class="n">TextBoxes</span> <span class="n">action</span> <span class="o">=</span> <span class="k">new</span> <span class="n">TextBoxes</span><span class="o">();</span>
|
|
|
|
<span class="c1">// Passes an instance of your custom TextBoxes class to the registerAction method of the ActionManager class.</span>
|
|
<span class="n">am</span><span class="o">.</span><span class="na">registerAction</span><span class="o">(</span><span class="s">"MyPluginAction"</span><span class="o">,</span> <span class="n">action</span><span class="o">);</span>
|
|
|
|
<span class="c1">// Gets an instance of the WindowMenu action group.</span>
|
|
<span class="n">DefaultActionGroup</span> <span class="n">windowM</span> <span class="o">=</span> <span class="o">(</span><span class="n">DefaultActionGroup</span><span class="o">)</span> <span class="n">am</span><span class="o">.</span><span class="na">getAction</span><span class="o">(</span><span class="s">"WindowMenu"</span><span class="o">);</span>
|
|
|
|
<span class="c1">// Adds a separator and a new menu command to the WindowMenu group on the main menu.</span>
|
|
<span class="n">windowM</span><span class="o">.</span><span class="na">addSeparator</span><span class="o">();</span>
|
|
<span class="n">windowM</span><span class="o">.</span><span class="na">add</span><span class="o">(</span><span class="n">action</span><span class="o">);</span>
|
|
<span class="o">}</span>
|
|
|
|
<span class="c1">// Disposes system resources.</span>
|
|
<span class="kd">public</span> <span class="kt">void</span> <span class="nf">disposeComponent</span><span class="o">()</span> <span class="o">{</span>
|
|
<span class="o">}</span>
|
|
<span class="o">}</span>
|
|
</code></pre>
|
|
|
|
<p>Note, that the sample <code class="code highlight language-text">TextBoxes</code> class is described in <a href="/intellij/sdk/docs/basics/getting_started.html"><span>Getting Started with Plugin Development</span></a>.</p>
|
|
|
|
<p>To ensure that your plugin is initialized on IDEA start-up, make the following changes to the <code class="code highlight language-text"><application-components></code> section of the <code class="code highlight language-text">plugin.xml</code> file:</p>
|
|
|
|
<pre><code class="code-block__wrapper code-block _highlighted lang_xml"><span class="nt"><application-components></span>
|
|
<span class="c"><!-- Add your application components here --></span>
|
|
<span class="nt"><component></span>
|
|
<span class="nt"><implementation-class></span>MypackageName.MyPluginRegistration<span class="nt"></implementation-class></span>
|
|
<span class="nt"></component></span>
|
|
<span class="nt"></application-components></span>
|
|
</code></pre>
|
|
|
|
<a name="building-ui-from-actions" class="elem-anchor"></a>
|
|
<h2>Building UI from Actions<a href="#building-ui-from-actions" class="anchor-link"><span></span></a></h2>
|
|
|
|
<p>If a plugin needs to include a toolbar or popup menu built from a group of actions in its own user interface, that can be accomplished through the <code class="code highlight language-text">ActionPopupMenu</code> and <code class="code highlight language-text">ActionToolbar</code> classes. These objects can be created through calls to <code class="code highlight language-text">ActionManager.createActionPopupMenu</code> and <code class="code highlight language-text">ActionManager.createActionToolbar</code>. To get a Swing component from such an object, simply call the getComponent() method.</p>
|
|
|
|
<p>If your action toolbar is attached to a specific component (for example, a panel in a toolwindow), you usually need to call <code class="code highlight language-text">ActionToolbar.setTargetComponent()</code> and pass the instance of the related component as a parameter. This ensures that the state of the toolbar buttons depends on the state of the related component, and not on the current focus location within the IDE frame.</p>
|
|
|
|
|
|
<div class="last-modified">
|
|
Last modified: 26 November 2015
|
|
</div>
|
|
</article>
|
|
|
|
<section class="disqus">
|
|
<div id="disqus_thread"></div>
|
|
</section>
|
|
</div>
|
|
</section>
|
|
</main>
|
|
</div>
|
|
|
|
|
|
<script data-main="/intellij/sdk/docs/app/js/main.build" data-baseurl="/intellij/sdk/docs/" src="/intellij/sdk/docs/app/js/vendor/requirejs/require.js"></script>
|
|
|
|
</body>
|
|
</html>
|
|
|