hide non-dumb-aware intentions (EA-65004 - INRE: FileBasedIndexImpl.handleDumbMode)
[idea/community.git] / platform / analysis-api / src / com / intellij / codeInsight / intention / IntentionAction.java
1 /*
2  * Copyright 2000-2014 JetBrains s.r.o.
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 package com.intellij.codeInsight.intention;
17
18 import com.intellij.openapi.application.Application;
19 import com.intellij.openapi.editor.Editor;
20 import com.intellij.openapi.project.Project;
21 import com.intellij.openapi.util.Iconable;
22 import com.intellij.psi.PsiFile;
23 import com.intellij.util.IncorrectOperationException;
24 import org.jetbrains.annotations.Nls;
25 import org.jetbrains.annotations.NotNull;
26
27 /**
28  * Interface for intention actions. Intention actions are invoked by pressing
29  * Alt-Enter in the code editor at the location where an intention is available,
30  * and can be enabled or disabled in the "Intentions" settings dialog.
31  * <p/>
32  * Implement {@link Iconable Iconable} interface to
33  * change icon in intention popup menu.
34  * <p/>
35  * Implement {@link HighPriorityAction HighPriorityAction} or
36  * {@link LowPriorityAction LowPriorityAction} to change ordering.
37  * <p/>
38  * Can be {@link com.intellij.openapi.project.DumbAware}.
39  *
40  * @see IntentionManager#registerIntentionAndMetaData(IntentionAction, String...)
41  */
42 public interface IntentionAction {
43   IntentionAction[] EMPTY_ARRAY = new IntentionAction[0];
44   /**
45    * Returns text to be shown in the list of available actions, if this action
46    * is available.
47    *
48    * @see #isAvailable(Project,Editor,PsiFile)
49    * @return the text to show in the intention popup.
50    */
51   @Nls(capitalization = Nls.Capitalization.Sentence)
52   @NotNull String getText();
53
54   /**
55    * Returns the name of the family of intentions. It is used to externalize
56    * "auto-show" state of intentions. When user clicks on a lightbulb in intention list,
57    * all intentions with the same family name get enabled/disabled.
58    * The name is also shown in settings tree.
59    *
60    * @return the intention family name.
61    * @see IntentionManager#registerIntentionAndMetaData(IntentionAction, String...)
62    */
63   @NotNull
64   @Nls(capitalization = Nls.Capitalization.Sentence)
65   String getFamilyName();
66
67   /**
68    * Checks whether this intention is available at a caret offset in file.
69    * If this method returns true, a light bulb for this intention is shown.
70    *
71    * @param project the project in which the availability is checked.
72    * @param editor the editor in which the intention will be invoked.
73    * @param file the file open in the editor.
74    * @return true if the intention is available, false otherwise.
75    */
76   boolean isAvailable(@NotNull Project project, Editor editor, PsiFile file);
77
78   /**
79    * Called when user invokes intention. This method is called inside command.
80    * If {@link #startInWriteAction()} returns true, this method is also called
81    * inside write action.
82    *
83    * @param project the project in which the intention is invoked.
84    * @param editor the editor in which the intention is invoked.
85    * @param file the file open in the editor.
86    */
87   void invoke(@NotNull Project project, Editor editor, PsiFile file) throws IncorrectOperationException;
88
89   /**
90    * Indicate whether this action should be invoked inside write action.
91    * Should return false if e.g. modal dialog is shown inside the action.
92    * If false is returned the action itself is responsible for starting write action
93    * when needed, by calling {@link Application#runWriteAction(Runnable)}.
94    *
95    * @return true if the intention requires a write action, false otherwise.
96    */
97   boolean startInWriteAction();
98 }