lang-api/src/com/intellij/find/FindManager.java

   1 /*
   2  * Copyright 2000-2007 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.find;
  17
  18 import com.intellij.openapi.components.ServiceManager;
  19 import com.intellij.openapi.editor.Editor;
  20 import com.intellij.openapi.fileEditor.FileEditor;
  21 import com.intellij.openapi.project.Project;
  22 import com.intellij.openapi.vfs.VirtualFile;
  23 import com.intellij.psi.PsiElement;
  24 import com.intellij.util.messages.Topic;
  25 import org.jetbrains.annotations.NotNull;
  26 import org.jetbrains.annotations.Nullable;
  27
  28 /**
  29  * Allows to invoke and control Find, Replace and Find Usages operations.
  30  */
  31 public abstract class FindManager {
  32   public static final Topic<FindModelListener> FIND_MODEL_TOPIC = new Topic<FindModelListener>("FindManager's model changes",
  33                                                                                                FindModelListener.class);
  34   /**
  35    * Returns the find manager instance for the specified project.
  36    *
  37    * @param project the project for which the manager is requested.
  38    * @return the manager instance.
  39    */
  40   public static FindManager getInstance(Project project) {
  41     return ServiceManager.getService(project, FindManager.class);
  42   }
  43
  44   /**
  45    * Shows the Find, Replace or Find Usages dialog initializing it from the specified
  46    * model and saves the settings entered by the user into the same model. Does not
  47    * perform the actual find or replace operation.
  48    *
  49    * @param model the model containing the settings of a find or replace operation.
  50    * @param okHandler Will be executed after doOkAction
  51    */
  52   public abstract void showFindDialog(@NotNull FindModel model, @NotNull Runnable okHandler);
  53
  54   /**
  55    * Shows a replace prompt dialog for the specfied replace operation.
  56    *
  57    * @param model the model containing the settings of the replace operation.
  58    * @param title the title of the dialog to show.
  59    * @return the exit code of the dialog, as defined by the {@link PromptResult}
  60    * interface.
  61    */
  62   public abstract int showPromptDialog(FindModel model, String title);
  63
  64   /**
  65    * Returns the settings of the last performed Find in File operation, or the
  66    * default Find in File settings if no such operation was performed by the user.
  67    *
  68    * @return the last Find in File settings.
  69    */
  70   @NotNull
  71   public abstract FindModel getFindInFileModel();
  72
  73   /**
  74    * Returns the settings of the last performed Find in Project operation, or the
  75    * default Find in Project settings if no such operation was performed by the user.
  76    *
  77    * @return the last Find in Project settings.
  78    */
  79   @NotNull
  80   public abstract FindModel getFindInProjectModel();
  81
  82   /**
  83    * Searches for the specified substring in the specified character sequence,
  84    * using the specified find settings. Supports case sensitive and insensitive
  85    * searches, forward and backward searches, regular expression searches and
  86    * searches for whole words.
  87    *
  88    * @param text   the text in which the search is performed.
  89    * @param offset the start offset for the search.
  90    * @param model  the settings for the search, including the string to find.
  91    * @return the result of the search.
  92    */
  93   @NotNull
  94   public abstract FindResult findString(@NotNull CharSequence text, int offset, @NotNull FindModel model);
  95
  96   /**
  97    * Searches for the specified substring in the specified character sequence,
  98    * using the specified find settings. Supports case sensitive and insensitive
  99    * searches, forward and backward searches, regular expression searches and
 100    * searches for whole words.
 101    *
 102    * @param text   the text in which the search is performed.
 103    * @param offset the start offset for the search.
 104    * @param model  the settings for the search, including the string to find.
 105    * @return the result of the search.
 106    */
 107   @NotNull
 108   public abstract FindResult findString(@NotNull CharSequence text, int offset, @NotNull FindModel model,
 109                                         @Nullable VirtualFile findContextFile);
 110
 111   /**
 112    * Gets the string to replace with, given the specified found string and find/replace
 113    * settings. Supports case-preserving and regular expression replaces.
 114    *
 115    * @param foundString the found string.
 116    * @param model       the search and replace settings, including the replace string.
 117    * @return the string to replace the specified found string.
 118    */
 119   public abstract String getStringToReplace(@NotNull String foundString, FindModel model);
 120
 121   /**
 122    * Gets the flag indicating whether the "Find Next" and "Find Previous" actions are
 123    * available to continue a previously started search operation. (The operations are
 124    * available if at least one search was performed in the current IDEA session.)
 125    *
 126    * @return true if the actions are available, false if there is no previous search
 127    *         operation to continue.
 128    */
 129   public abstract boolean findWasPerformed();
 130
 131   /**
 132    * Sets the flag indicating that the "Find Next" and "Find Previous" actions are
 133    * available to continue a previously started search operation.
 134    */
 135   public abstract void setFindWasPerformed();
 136
 137   /**
 138    * Sets the model containing the search settings to use for "Find Next" and
 139    * "Find Previous" operations.
 140    *
 141    * @param model the model to use for the operations.
 142    */
 143   public abstract void setFindNextModel(FindModel model);
 144
 145   /**
 146    * Gets the model containing the search settings to use for "Find Next" and
 147    * "Find Previous" operations.
 148    *
 149    * @return the model to use for the operations.
 150    */
 151   public abstract FindModel getFindNextModel();
 152
 153   /**
 154    * Gets the model containing the search settings to use for "Find Next" and
 155    * "Find Previous" operations specific for the editor given. It may be different than {@link #getFindNextModel()}
 156    * if there is find bar currently shown for the editor.
 157    *
 158    * @param editor editor, for which find model shall be retreived for
 159    * @return the model to use for the operations.
 160    */
 161   public abstract FindModel getFindNextModel(@NotNull Editor editor);
 162
 163   /**
 164    * Checks if the Find Usages action is available for the specified element.
 165    *
 166    * @param element the element to check the availability for.
 167    * @return true if Find Usages is available, false otherwise.
 168    * @see com.intellij.lang.findUsages.FindUsagesProvider#canFindUsagesFor(com.intellij.psi.PsiElement)
 169    */
 170   public abstract boolean canFindUsages(@NotNull PsiElement element);
 171
 172   /**
 173    * Shows the Find Usages dialog and performs the Find Usages operation for the
 174    * specified element.
 175    *
 176    * @param element the element to find the usages for.
 177    */
 178   public abstract void findUsages(@NotNull PsiElement element);
 179
 180   /**
 181    * Performs a "Find Usages in File" operation for the specified element.
 182    *
 183    * @param element the element for which the find is performed.
 184    * @param editor  the editor in which the find is performed.
 185    */
 186   public abstract void findUsagesInEditor(@NotNull PsiElement element, @NotNull FileEditor editor);
 187
 188   /**
 189    * Performs a "Find Next" operation after "Find Usages in File" or
 190    * "Highlight Usages in File".
 191    *
 192    * @param editor the editor in which the find is performed.
 193    * @return true if the operation was performed (not necessarily found anything),
 194    *         false if an error occurred during the operation.
 195    */
 196   public abstract boolean findNextUsageInEditor(@NotNull FileEditor editor);
 197
 198   /**
 199    * Performs a "Find Previous" operation after "Find Usages in File" or
 200    * "Highlight Usages in File".
 201    *
 202    * @param editor the editor in which the find is performed.
 203    * @return true if the operation was performed (not necessarily found anything),
 204    *         false if an error occurred during the operation.
 205    */
 206   public abstract boolean findPreviousUsageInEditor(@NotNull FileEditor editor);
 207
 208   /**
 209    * Possible return values for the {@link FindManager#showPromptDialog(FindModel, String)} method.
 210    *
 211    * @since 5.0.2
 212    */
 213   public interface PromptResult {
 214     int OK = 0;
 215     int CANCEL = 1;
 216     int SKIP = 2;
 217     int ALL = 3;
 218     int ALL_IN_THIS_FILE = 4;
 219     int ALL_FILES = 5;
 220   }
 221 }