-
-
Notifications
You must be signed in to change notification settings - Fork 11
Actions API
The Actions API (:actions module) is used to show various actions in the IDE. It allows tools like LSP (and others) to add actions at various locations in the UI. For example, the Java LSP adds code actions like 'Go to definition', 'Find references', etc. in the code editor's text action window.
An action is defined by implementing the the ActionItem interface and registering it to the ActionsRegistry.
The ActionItem interface defines various properties and functions that can be overridden in order to achive a specific behavior. Every ActionItem must have a unique string ID and a valid location. The locations for the actions are defined in the ActionItem.Location enumeration.
For consistency, the IDs for the action item should have the following format :
ide.<subcomponent>[.<sub-subcomponents-or-category>...].<actionId>
For example, ide.editor.build.quickRun.
ActionData contains various parameters like Context, CodeEditor, etc that can be used by the action implementation. The same ActionData is provided to all the functions of the ActionItem i.e. the prepare, execAction and postExec are called with the same ActionData instance.
The data provided in the ActionData differs for each ActionItem.Location. However, a Context object is always provided with an ActionData instance.
The ActionItem.prepare(ActionData) method is called to prepare the action item. The action item can validate various conditions and update the properties of the action. For example, an action can check if a build is in progress and decide whether the action should be visible to the user or not.
The ActionItem.execAction(ActionData) method is called to execute the action. Based on the ActionItem.requiresUiThread property, the action is executed either on the UI thread or a background thread. The action should make sure NOT to perform long running operations when running on the UI thread.
This method could return a value which can later be accessed in the postExec function. If the action does not need to calculate and process a value, this should simply return Unit or false.
The ActionItem.postExec(ActionData) method is called to let the action process the result from ActionItem.execAction(). This method is ALWAYS called on the UI thread and hence, the action should not perform any long running operations here.
Usually, this method is used to show the result of the action to the user.
An action menu is a group of actions that are grouped together. Action menus are just queried and not executed. Hence, the execAction and postExec methods are never called for an action menu.
The ActionsRegistry provides various APIs to query the registered action. See ActionsRegistry for more details.