platform/lang-api/src/com/intellij/lang/findUsages/FindUsagesProvider.java

   1 /*
   2  * Copyright 2000-2009 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.lang.findUsages;
  17
  18 import com.intellij.lang.cacheBuilder.WordsScanner;
  19 import com.intellij.psi.PsiElement;
  20 import org.jetbrains.annotations.NotNull;
  21 import org.jetbrains.annotations.Nullable;
  22
  23 /**
  24  * Defines the support for the "Find Usages" feature in a custom language.
  25  *
  26  * @author max
  27  * @see com.intellij.lang.LanguageExtension#forLanguage(com.intellij.lang.Language)
  28  */
  29 public interface FindUsagesProvider {
  30   /**
  31    * Gets the word scanner for building a word index for the specified language.
  32    *
  33    * @return the word scanner implementation, or null if {@link com.intellij.lang.cacheBuilder.SimpleWordsScanner} is OK.
  34    */
  35   @Nullable
  36   WordsScanner getWordsScanner();
  37
  38   /**
  39    * Checks if it makes sense to search for usages of the specified element.
  40    *
  41    * @param psiElement the element for which usages are searched.
  42    * @return true if the search is allowed, false otherwise.
  43    * @see com.intellij.find.FindManager#canFindUsages(com.intellij.psi.PsiElement)
  44    */
  45   boolean canFindUsagesFor(@NotNull PsiElement psiElement);
  46
  47   /**
  48    * Returns the ID of the help topic which is shown when the specified element is selected
  49    * in the "Find Usages" dialog.
  50    *
  51    * @param psiElement the element for which the help topic is requested.
  52    * @return the help topic ID, or null if no help is available.
  53    */
  54   @Nullable
  55   String getHelpId(@NotNull PsiElement psiElement);
  56
  57   /**
  58    * Returns the user-visible type of the specified element, shown in the "Find Usages"
  59    * dialog (for example, "class" or "variable"). The type name should not be upper-cased.
  60    *
  61    * @param element the element for which the type is requested.
  62    * @return the type of the element.
  63    */
  64   @NotNull
  65   String getType(@NotNull PsiElement element);
  66
  67   /**
  68    * Returns an expanded user-visible name of the specified element, shown in the "Find Usages"
  69    * dialog. For classes, this can return a fully qualified name of the class; for methods -
  70    * a signature of the method with parameters.
  71    *
  72    * @param element the element for which the name is requested.
  73    * @return the user-visible name.
  74    */
  75   @NotNull
  76   String getDescriptiveName(@NotNull PsiElement element);
  77
  78   /**
  79    * Returns the text representing the specified PSI element in the Find Usages tree.
  80    *
  81    * @param element     the element for which the node text is requested.
  82    * @param useFullName if true, the returned text should use fully qualified names
  83    * @return the text representing the element.
  84    */
  85   @NotNull
  86   String getNodeText(@NotNull PsiElement element, boolean useFullName);
  87 }