Plugin

Name - The name of an action. You can give any name you want, the only obvious constraint is that the names must be unique in the scope of the model.

Mnemonic -  if mnemonic is specified, the action will be available via the alt+mnemonic shortcut when any group that contains this action is displayed. Note that the mnemonic (if specified) must be one of the chars in action's caption. Mnemonic is displayed as an underlined symbol in the action's caption.

Required access - specifies the access control that MPS should provide to the action:

• none - no access control will be provided, all eventual locking must be performed manually by the action. The action can perform UI operations without the risk of locking the UI.

• read - a read access is granted. The action can perform UI operations without the risk of locking the UI.

• command - all operations with MPS models are executed within commands. A command is an item in the undo list (you don't control it manually, MPS does it for you), so the user can undo changes brought into the model by action's execution. Also, all the code executed in a command, has read-write access to the model. The catch is that if you show visual dialogs to the user from inside of a command, it can cause a deadlock by blocking while holding the read/write locks. It is thus recommended to use this option, only if you are not using UI in your action.

• editor command - similarly to the option above, the action is performed in the context of a undoable command, read and write access is granted. The command is obtained from the editor context, so an editor context must be provided as one of the action's context parameters.

Execute outside command - (this option should be gradually abandoned in favour of required access, if set to true, it overrides any settings for the required access property) all operations with MPS models are executed within commands. A command is an item in the undo list (you don't control it manually, MPS does it for you), so the user can undo changes brought into the model by action's execution. Also, all the code executed in a command, has read-write access to the model. The catch is that if you show visual dialogs to the user from inside of a command, it can cause a deadlock by blocking while holding the read/write locks. It is thus recommended to have the execute outside command option set to false, only if you are not using UI in your action. Otherwise it should be set to true and proper read/write access locking should be performed manually with the read action and command statements within the action.

Also available in - currently, this can only be set to "everywhere", which means the action will not only be available in the context, where you can invoke it through the completion menu, but also in any other context. E.g. if some action is added to the editor context menu group, but the author wants it to be available when the focus is in the logical view, or just when all the editors are closed, "also available in" should be set to "everywhere".

Caption - the string representing the action in menus

Description - this string (if specified) will be displayed in the status bar when this action is active (selected in any menu)

Icon - this icon will be displayed near the action in all menus. You can select an icon file or describe the icon using a DSL. Note that the icon file must be placed near your language (because it's stored not as an image, but as a path relative to the language's root).

Each action can be parameterized at construction time using construction parameters. This can be any data determining action's behavior. Thus, a single action that uses construction parameters can represent multiple different behaviors. To manage actions and handle keymaps MPS needs a unique identifier for each concrete behavior represented by an action. So, the toString function was introduced for each construction parameter (can be seen in the inspector). For primitive types there is no need to specify this function explicitly - MPS can do it automatically. For more complex parameters, you need to write this function explicitly so that for each concrete behavior of an action there is a different set of values returned from the toString() functions.

Is always visible flag - if you want your action to be visible even in the disabled state (when the action is not applicable in the current context), set this to true, otherwise to false.

Context parameters - specifies which items must be present in the current context for the action to be able to execute. They are extracted from the context before any action's method is executed. Context parameters have conditions associated with them - required, custom andd id are the three most frequently used ones. If some required parameters were not extracted, the action state is set to disabled and the isApplicable/update/execute methods are not executed. If all required action parameters were extracted, you can use their values in all the action methods. Custom context parameters give you the option to decide whether the context parameter is mandatory on case-by-case basis using the supplied function. The is condition tests the obtained objact against a supplied class.

There are 2 types of action parameters - simple and complex action parameters.

• Simple action parameters (represented by ActionDataParameterDeclaration) allow to simply extract all available data from the current data context. The data is provided "by key", so you should specify the name and the key in the declaration. The type of the parameter will be set automatically.

• Complex action parameters (represented by ActionParameterDeclaration ) were introduced to perform some frequently used checks and typecasts. Now there are 3 types available for the context parameter of this type:

  • node<concept> - currently selected node, which is an instance of a specified concept. Action won't be enabled, if the selected node isn't an instance of this concept.

  • nlist<concept> - currently selected nodes. It is checked that all nodes are instances of the concept (if specified). As with node<concept>, the action won't be enabled if the check fails.

  • model - the current model holding the selected node

tip

The available keys that the user can type into the context parameters declaration are obtained automatically from all imported models. MPS searches the imported models for subclasses of the CommonDataKeys (com.intellij.openapi.actionSystem) class. Typical such subclasses are:

• PlatformDataKeys (com.intellij.openapi.actionSystem)

• MPSCommonDataKeys (jetbrains.mps.ide.actions)

• MPSEditorDataKeys (jetbrains.mps.ide.editor)

• MPSDataKeys (jetbrains.mps.workbench)

Be sure to import these models (Ctrl0M) in order to see them in the completion menu for context parameters.

Is Applicable / update - In cooperation with the context parameters, this method controls the enabled/disabled state of the action. You can pick either of the two options:

• The isApplicable method returns the new state of an action

• The update method is designed to update the state manually. You can also update any of your action's properties (caption, icon etc.) by accessing action's presentation via event.getPresentation() . Call the setEnabledState() method on an action to enable or disable it manually.

These methods are executed only if all required context parameters have been successfully extracted from the context.

Note: The this keyword refers to the current action, use action<...> to get hold of any visible action from your code.

tip

Do not use the isApplicable() method if you want to modify the presentation manually. Although no errors would be reported from within isApplicable(), it is not guaranteed to work in all cases properly. The update() method is a more suitable place for complex presentation manipulations.

Execute - this method is executed when the action is performed. It is guaranteed that it is executed only if the action's update method for the same event left the action in active state (or isApplicable returned true) and all the required context parameters are present in the current context and were filled in.

Methods - in this section you can declare utility methods.

Group describes a set of actions and provides the information about how to modify other groups with current group.

Name - The name of the group. You can give any name you want, the only obvious constraint is that the names must be unique in the scope of the model.

is popup - if this is true, the group represents a popup menu, otherwise it represents a list of actions.

• Caption - string that will be displayed as the name of the popup menu

• Mnemonic - if mnemonic is specified, the popup menu will be available via the alt+mnemonic shortcut when any group that contains it is displayed. Note that the mnemonic (if specified) must be one of the chars in caption. Mnemonic is displayed as an underlined symbol in the popup menu caption.

• Is invisible when disabled - if set to true, the group will not be shown in case it has no enabled actions or is disabled manually in the update() method. Call the enable()/disable() methods on an action group to enable or disable it manually.

There are 3 possibilities to describe group contents:

Element list - this is just a static list of actions, groups and labels (see modifications). The available elements are:

• ->name - an anchors. Anchors are used for modifying one group with another. For more information, refer to the Add statement section.

• <---> - separator

• ActionName[parameters] - an actions.

Build - this alternative should be used in groups, the contents of which is static, but depends on some initial conditions - the group is built once and is not updated ever after. Use the add statement to add elements inside build block.

Update - this goes for dynamically changing groups. Group is updated every time right before it is rendered.

tip

In the update/build blocks use the add statement to add group members.

Add to <group> at position <position> - this statement adds the current group to a <group> at the given position. Every group has a <default> position, which tells to add the current group to the end of the target group. Some groups can provide additional positions by adding so-called anchors into themselves. Adding anchors is described in the contents section. The anchor itself is invisible and represents a position, in which a group can be inserted.

tip

• You shouldn't care about the group creation order and modifications order - this statement is fully declarative.

• If A is added into B, B into C, C will contain A

There is a specific expression available in the jetbrains.mps.lang.plugin language to access any registered group - actionGroup< group > expression.

Registers groups, bootstrap groups and keymaps statically through a generated components.xml file as required by the IntelliJ platform.

Bootstrap groups are a way to work with action groups that have been defined outside of MPS (e.g. groups contributed by IDEA or some IDEA plugin).

In this case, a bootstrap group is defined in MPS and its internal ID is set to the ID of the external group. After having this done, you can work with the bootstrap group just like with a normal one - insert it into your groups and vice versa.

A regular user rarely needs to use bootstrap groups.

The register via plugin.xml option in the Inspector has the same meaning as for ordinary groups, and is described above.

tip

A quick and simple tutorial by Federico Tomassetti on how to create action and show it in a context menu is available here:

http://www.federico-tomassetti.it/tutorial-how-to-add-an-action-to-the-jetbrains-metaprogramming-system/

Please bear in mind that this tutorial uses an older version of MPS and the actual workings in MPS have changed since then, Especially we now recommend to use plugin solutions instead of the plugin aspect of a language to hold your actions. The tutorial may still give you some guidelines and useful insight.