hxuanyu/intellij-sdk-code-samples
1
0
Fork 0
mirror of https://github.com/JetBrains/intellij-sdk-code-samples.git synced 2025-07-28 01:07:49 +08:00
Code Issues Packages Projects Releases Wiki Activity

[md] syntax highlighting

Browse Source
This commit is contained in:
Anna Bulenkova 2015-01-27 13:19:14 +01:00
parent c568fcaea3
commit e3090af795
1 changed files with 166 additions and 132 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

298
tutorials/action_system/action_system.md
View File

@ -24,19 +24,23 @@ To create a new we need to extend
[AnAction] (https://github.com/JetBrains/intellij-community/blob/master/platform/editor-ui-api/src/com/intellij/openapi/actionSystem/AnAction.java) [AnAction] (https://github.com/JetBrains/intellij-community/blob/master/platform/editor-ui-api/src/com/intellij/openapi/actionSystem/AnAction.java)
class: class:
public class SimpleAction extends AnAction { ```java
} public class SimpleAction extends AnAction {
}
```
The only method of an inheritor of The only method of an inheritor of
[AnAction] (https://github.com/JetBrains/intellij-community/blob/master/platform/editor-ui-api/src/com/intellij/openapi/actionSystem/AnAction.java) [AnAction] (https://github.com/JetBrains/intellij-community/blob/master/platform/editor-ui-api/src/com/intellij/openapi/actionSystem/AnAction.java)
which needs to be overridden is ```public void actionPerformed(AnActionEvent anActionEvent);``` which needs to be overridden is ```public void actionPerformed(AnActionEvent anActionEvent);```
, and it should contain a part of code to be executed after the action has been invoked. In this case the action does nothing. , and it should contain a part of code to be executed after the action has been invoked. In this case the action does nothing.
public class SimpleAction extends AnAction { ```java
@Override public class SimpleAction extends AnAction {
public void actionPerformed(AnActionEvent anActionEvent) { @Override
} public void actionPerformed(AnActionEvent anActionEvent) {
} }
}
```
------------- -------------
@ -57,52 +61,56 @@ After filling the "New Action" form and applying the changes *<actions>* section
[plugin.xml]() [plugin.xml]()
file will look like this: file will look like this:
<actions> ```xml
<!-- Add your actions here --> <actions>
<action id="org.jetbrains.tutorials.actions.SimpleAction" class="org.jetbrains.tutorials.actions.SimpleAction" <!-- Add your actions here -->
text="Simple Action" description="IntelliJ Action System Demo"> <action id="org.jetbrains.tutorials.actions.SimpleAction" class="org.jetbrains.tutorials.actions.SimpleAction"
<add-to-group group-id="ToolsMenu" anchor="first"/> text="Simple Action" description="IntelliJ Action System Demo">
</action> <add-to-group group-id="ToolsMenu" anchor="first"/>
</actions> </action>
</actions>
```
Full list of action's attributes can also be set manually in Full list of action's attributes can also be set manually in
[plugin.xml]() [plugin.xml]()
configuration file like the following code sample shows: configuration file like the following code sample shows:
<actions> ```xml
<!-- Add your actions here --> <actions>
<!-- The <action> element defines an action to register. <!-- Add your actions here -->
The mandatory "id" attribute specifies an unique identifier for the action. <!-- The <action> element defines an action to register.
The mandatory "class" attribute specifies the full-qualified name of the class implementing the action. The mandatory "id" attribute specifies an unique identifier for the action.
The mandatory "text" attribute specifies the text of the action (tooltip for toolbar button or text for menu item). The mandatory "class" attribute specifies the full-qualified name of the class implementing the action.
The optional "use-shortcut-of" attribute specifies the ID of the action whose keyboard shortcut this action will use. The mandatory "text" attribute specifies the text of the action (tooltip for toolbar button or text for menu item).
The optional "description" attribute specifies the text which is displayed in the status bar when the action is focused. The optional "use-shortcut-of" attribute specifies the ID of the action whose keyboard shortcut this action will use.
The optional "icon" attribute specifies the icon which is displayed on the toolbar button or next to the menu item. --> The optional "description" attribute specifies the text which is displayed in the status bar when the action is focused.
<action id="org.jetbrains.tutorials.actions.SimpleAction" class="org.jetbrains.tutorials.actions.SimpleAction" The optional "icon" attribute specifies the icon which is displayed on the toolbar button or next to the menu item. -->
text="Simple Action" description="IntelliJ Action System Demo"> <action id="org.jetbrains.tutorials.actions.SimpleAction" class="org.jetbrains.tutorials.actions.SimpleAction"
<!-- The <keyboard-shortcut> node specifies the keyboard shortcut for the action. An action can have several keyboard shortcuts. text="Simple Action" description="IntelliJ Action System Demo">
The mandatory "first-keystroke" attribute specifies the first keystroke of the action. The key strokes are specified according to the regular Swing rules. <!-- The <keyboard-shortcut> node specifies the keyboard shortcut for the action. An action can have several keyboard shortcuts.
The optional "second-keystroke" attribute specifies the second keystroke of the action. The mandatory "first-keystroke" attribute specifies the first keystroke of the action. The key strokes are specified according to the regular Swing rules.
The mandatory "keymap" attribute specifies the keymap for which the action is active. IDs of the standard keymaps are defined as The optional "second-keystroke" attribute specifies the second keystroke of the action.
constants in the com.intellij.openapi.keymap.KeymapManager class. --> The mandatory "keymap" attribute specifies the keymap for which the action is active. IDs of the standard keymaps are defined as
<keyboard-shortcut first-keystroke="control alt A" second-keystroke="C" keymap="$default"/> constants in the com.intellij.openapi.keymap.KeymapManager class. -->
<!-- The <mouse-shortcut> node specifies the mouse shortcut for the action. An action can have several mouse shortcuts. <keyboard-shortcut first-keystroke="control alt A" second-keystroke="C" keymap="$default"/>
The mandatory "keystroke" attribute specifies the clicks and modifiers for the action. It is defined as a sequence of words separated by spaces: <!-- The <mouse-shortcut> node specifies the mouse shortcut for the action. An action can have several mouse shortcuts.
"button1", "button2", "button3" for the mouse buttons; "shift", "control", "meta", "alt", "altGraph" for the modifier keys; The mandatory "keystroke" attribute specifies the clicks and modifiers for the action. It is defined as a sequence of words separated by spaces:
"doubleClick" if the action is activated by a double-click of the button. "button1", "button2", "button3" for the mouse buttons; "shift", "control", "meta", "alt", "altGraph" for the modifier keys;
The mandatory "keymap" attribute specifies the keymap for which the action is active. IDs of the standard keymaps are defined as "doubleClick" if the action is activated by a double-click of the button.
constants in the com.intellij.openapi.keymap.KeymapManager class. --> The mandatory "keymap" attribute specifies the keymap for which the action is active. IDs of the standard keymaps are defined as
<mouse-shortcut keystroke="control button3 doubleClick" keymap="$default"/> constants in the com.intellij.openapi.keymap.KeymapManager class. -->
<!-- The <add-to-group> node specifies that the action should be added to an existing group. An action can be added to several groups. <mouse-shortcut keystroke="control button3 doubleClick" keymap="$default"/>
The mandatory "group-id" attribute specifies the ID of the group to which the action is added. <!-- 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 group must be implemented by an instance of the DefaultActionGroup class. The mandatory "group-id" attribute specifies the ID of the group to which the action is added.
The mandatory "anchor" attribute specifies the position of the action in the group relative to other actions. It can have the values The group must be implemented by an instance of the DefaultActionGroup class.
"first", "last", "before" and "after". The mandatory "anchor" attribute specifies the position of the action in the group relative to other actions. It can have the values
The "relative-to-action" attribute is mandatory if the anchor is set to "before" and "after", and specifies the action before or after which "first", "last", "before" and "after".
the current action is inserted. --> The "relative-to-action" attribute is mandatory if the anchor is set to "before" and "after", and specifies the action before or after which
<add-to-group group-id="ToolsMenu" anchor="first"/> the current action is inserted. -->
</action> <add-to-group group-id="ToolsMenu" anchor="first"/>
</actions> </action>
</actions>
```
After performing the steps described above we need to compile and run the plugin to the the newly created action available as a Tools Menu item. After performing the steps described above we need to compile and run the plugin to the the newly created action available as a Tools Menu item.
!["Register action" quick fix](img/tools_menu_item_action.png) !["Register action" quick fix](img/tools_menu_item_action.png)
@ -113,13 +121,15 @@ After performing the steps described above we need to compile and run the plugin
In order to make the action do something we need to implement it's ```public void actionPerformed(AnActionEvent anActionEvent);``` method. In order to make the action do something we need to implement it's ```public void actionPerformed(AnActionEvent anActionEvent);``` method.
In the following example action invokes a dialog that shows information about a selected Project View Item and has no icon and any pre-selected default option: In the following example action invokes a dialog that shows information about a selected Project View Item and has no icon and any pre-selected default option:
@Override ```java
public void actionPerformed(AnActionEvent anActionEvent) { @Override
Object navigatable = anActionEvent.getData(CommonDataKeys.NAVIGATABLE); public void actionPerformed(AnActionEvent anActionEvent) {
if (navigatable != null) { Object navigatable = anActionEvent.getData(CommonDataKeys.NAVIGATABLE);
Messages.showDialog(navigatable.toString(), "Selected Element:", new String[]{"OK"}, -1, null); if (navigatable != null) {
} Messages.showDialog(navigatable.toString(), "Selected Element:", new String[]{"OK"}, -1, null);
} }
}
```
----------- -----------
@ -131,36 +141,40 @@ Default implementation of this method does nothing.
Override this method to provide the ability to dynamically change action's Override this method to provide the ability to dynamically change action's
state and(or) presentation depending on the context. state and(or) presentation depending on the context.
public class SimpleAction extends AnAction { ```java
@Override public class SimpleAction extends AnAction {
public void actionPerformed(AnActionEvent anActionEvent) { @Override
//... public void actionPerformed(AnActionEvent anActionEvent) {
} //...
@Override
public void update(AnActionEvent anActionEvent) {
}
} }
@Override
public void update(AnActionEvent anActionEvent) {
}
}
```
The following code sample illustrates how to make the action visible and available only when the following conditions are met: The following code sample illustrates how to make the action visible and available only when the following conditions are met:
there's a project available and there's an item you can navigate to selected in the project view pane: there's a project available and there's an item you can navigate to selected in the project view pane:
public class SimpleAction extends AnAction { ```java
@Override public class SimpleAction extends AnAction {
public void actionPerformed(AnActionEvent anActionEvent) { @Override
//... public void actionPerformed(AnActionEvent anActionEvent) {
} //...
@Override
public void update(AnActionEvent anActionEvent) {
final Project project = anActionEvent.getData(CommonDataKeys.PROJECT);
if (project == null)
return;
Object navigatable = anActionEvent.getData(CommonDataKeys.NAVIGATABLE);
anActionEvent.getPresentation().setEnabledAndVisible(navigatable != null);
}
} }
@Override
public void update(AnActionEvent anActionEvent) {
final Project project = anActionEvent.getData(CommonDataKeys.PROJECT);
if (project == null)
return;
Object navigatable = anActionEvent.getData(CommonDataKeys.NAVIGATABLE);
anActionEvent.getPresentation().setEnabledAndVisible(navigatable != null);
}
}
```
Parameter anActionEvent carries information on the invocation place and data available. Parameter anActionEvent carries information on the invocation place and data available.
**Note** This method can be called frequently, for instance, if an action is added to a toolbar, it will be updated twice a second. **Note** This method can be called frequently, for instance, if an action is added to a toolbar, it will be updated twice a second.
@ -188,47 +202,55 @@ Grouping can be done by extending adding *<group>* attribute to *<actions>*
[plugin.xml]() [plugin.xml]()
file. file.
<actions> ```xml
<group id="SimpleGroup" text="Custom Action Group" popup="true"> <actions>
</group> <group id="SimpleGroup" text="Custom Action Group" popup="true">
</actions> </group>
</actions>
```
##Binding action groups to UI component. ##Binding action groups to UI component.
The following sample shows how to place a custom action group on top of the editor popup menu: The following sample shows how to place a custom action group on top of the editor popup menu:
<actions> ```xml
<group id="SimpleGroup" text="Custom Action Group" popup="true"> <actions>
<add-to-group group-id="EditorPopupMenu" anchor="first"/> <group id="SimpleGroup" text="Custom Action Group" popup="true">
</group> <add-to-group group-id="EditorPopupMenu" anchor="first"/>
</actions> </group>
</actions>
```
##Adding actions to the group. ##Adding actions to the group.
To create an action we need to extend To create an action we need to extend
[AnAction.java]() [AnAction.java]()
class: class:
public class GroupedAction extends AnAction { ```java
@Override public class GroupedAction extends AnAction {
public void update(AnActionEvent event) { @Override
event.getPresentation().setEnabledAndVisible(true); public void update(AnActionEvent event) {
} event.getPresentation().setEnabledAndVisible(true);
@Override
public void actionPerformed(AnActionEvent event) {
//Does nothing
}
} }
@Override
public void actionPerformed(AnActionEvent event) {
//Does nothing
}
}
```
And then the actions needs to be registered in the newly created group: And then the actions needs to be registered in the newly created group:
<action> ```xml
<group id="SimpleGroup" text="Custom Action Group" popup="true"> <action>
<add-to-group group-id="EditorPopupMenu" anchor="first"/> <group id="SimpleGroup" text="Custom Action Group" popup="true">
<action class="org.jetbrains.tutorials.actions.GroupedAction" id="org.jetbrains.tutorials.actions.GroupedAction" <add-to-group group-id="EditorPopupMenu" anchor="first"/>
<action class="org.jetbrains.tutorials.actions.GroupedAction" id="org.jetbrains.tutorials.actions.GroupedAction"
text="Grouped Action" description="Grouped Action Demo"> text="Grouped Action" description="Grouped Action Demo">
</action> </action>
</group> </group>
</actions> </actions>
```
After performing the steps described above the action group nad it's content will be available in the editor popup menu: After performing the steps described above the action group nad it's content will be available in the editor popup menu:
@ -248,11 +270,13 @@ This class is used if a set of actions belonging to the group is fixed, which is
Firstly, [DefaultActionGroup.java] should be derived: Firstly, [DefaultActionGroup.java] should be derived:
public class CustomDefaultActionGroup extends DefaultActionGroup { ```java
@Override public class CustomDefaultActionGroup extends DefaultActionGroup {
public void update(AnActionEvent event) { @Override
} public void update(AnActionEvent event) {
} }
}
```
###Registering action group. ###Registering action group.
As in case with the simple action group, the inheritor of As in case with the simple action group, the inheritor of
@ -261,49 +285,59 @@ should be declared in
[plugin.xml]() [plugin.xml]()
file: file:
<actions> ```xml
<group id="CustomDefaultActionGroup" class="org.jetbrains.tutorials.actions.CustomDefaultActionGroup" popup="true" <actions>
text="DefaultActionGroup Inheritor" description="Default Action Group Demo"> <group id="CustomDefaultActionGroup" class="org.jetbrains.tutorials.actions.CustomDefaultActionGroup" popup="true"
<add-to-group group-id="ToolsMenu" anchor="last"/> text="DefaultActionGroup Inheritor" description="Default Action Group Demo">
</group> <add-to-group group-id="ToolsMenu" anchor="last"/>
</actions> </group>
</actions>
```
###Creating an action. ###Creating an action.
[AnAction.java]() [AnAction.java]()
needs to be extended: needs to be extended:
public class CustomGroupedAction extends AnAction {
@Override ```java
public void actionPerformed(AnActionEvent anActionEvent) { public class CustomGroupedAction extends AnAction {
//Does nothing @Override
} public void actionPerformed(AnActionEvent anActionEvent) {
//Does nothing
} }
}
```
###Adding actions to the group. ###Adding actions to the group.
Action's class should be registered in Action's class should be registered in
[plugin.xml]() [plugin.xml]()
: :
<group id="CustomDefaultActionGroup" class="org.jetbrains.tutorials.actions.CustomDefaultActionGroup" popup="true" ```xml
text="DefaultActionGroup Inheritor" description="Default Action Group Demo"> <actions>
<add-to-group group-id="ToolsMenu" anchor="last"/> <group id="CustomDefaultActionGroup" class="org.jetbrains.tutorials.actions.CustomDefaultActionGroup" popup="true"
<action class="org.jetbrains.tutorials.actions.CustomGroupedAction" id="CustomGroupedAction" text="DefaultActionGroup Inheritor" description="Default Action Group Demo">
text="Custom Grouped Action" description="Custom Grouped Action Demo"/> <add-to-group group-id="ToolsMenu" anchor="last"/>
</group> <action class="org.jetbrains.tutorials.actions.CustomGroupedAction" id="CustomGroupedAction"
</actions> text="Custom Grouped Action" description="Custom Grouped Action Demo"/>
</group>
</actions>
```
###Providing specific behaviour for the group. ###Providing specific behaviour for the group.
In this case we override ```public void update(AnActionEvent event);``` method to make the group visible as a *Tools* menu item, In this case we override ```public void update(AnActionEvent event);``` method to make the group visible as a *Tools* menu item,
however, it will be enabled only if there's an instance of the editor available. Also a custom icon is set up: however, it will be enabled only if there's an instance of the editor available. Also a custom icon is set up:
public class CustomDefaultActionGroup extends DefaultActionGroup { ```java
@Override public class CustomDefaultActionGroup extends DefaultActionGroup {
public void update(AnActionEvent event) { @Override
Editor editor = event.getData(CommonDataKeys.EDITOR); public void update(AnActionEvent event) {
event.getPresentation().setVisible(true); Editor editor = event.getData(CommonDataKeys.EDITOR);
event.getPresentation().setEnabled(editor != null); event.getPresentation().setVisible(true);
event.getPresentation().setIcon(AllIcons.General.Error); event.getPresentation().setEnabled(editor != null);
} event.getPresentation().setIcon(AllIcons.General.Error);
} }
}
```
After compiling and running the code sample above, *Tools* menu item should contain an extra group of action with a user-defined icon: After compiling and running the code sample above, *Tools* menu item should contain an extra group of action with a user-defined icon: