The Find Usages action is a multi-step process, and each step of the process requires involvement from the custom language plugin.
The language plugin participates in the Find Usages process by registering an implementation of
FindUsagesProvider in the
com.intellij.lang.findUsagesProvider extension point, and through the PSI implementation using
The steps of the Find Usages action are the following:
* Before the Find Usages action can be invoked, the IDE builds an index of words present in every file in the custom language.
WordsScanner implementation returned from
FindUsagesProvider.getWordsScanner(), the contents of every file are loaded and passes it to the words scanner, along with the words consumer.
The words scanner breaks the text into words, defines the context for each word (code, comments, or literals), and passes the word to the consumer.
The simplest way to implement the words scanner is to use the
DefaultWordsScanner implementation, passing to it the sets of lexer token types which are treated as identifiers, literals, and comments.
The default words scanner will use the lexer to break the text into tokens and handle breaking the text of the comment and literal tokens into individual words.
* When the user invokes the Find Usages action, the IDE locates the PSI element the references to be searched.
The PSI element at the cursor (the direct tree parent of the token at the cursor position) must be either a
PsiNamedElement or a
PsiReference which resolves to a
The word cache will be used to search for the text returned from the
Also, if the text range of the
PsiNamedElement includes some other text besides the identifier returned from
getName() (for example, if the
function" keyword in addition to the name of the function), the method
getTextOffset() must be overridden for the
PsiNamedElement, and must return the start offset of the name identifier within the text range of the element.
* Once the element is located, the IDE calls
FindUsagesProvider.canFindUsagesFor() to ask the plugin if the Find Usages action applies to the specific element.
* When showing the Find Usages dialog to the user,
FindUsagesProvider.getDescriptiveName() are called to determine how the element should be presented to the user.
* For every file containing the searched words, the IDE builds the PSI tree and recursively descends it.
The text of each element is broken into words and then scanned.
If the element was indexed as an identifier, every word is checked to be a
PsiReference resolving to the element the usages of which are searched.
If the element was indexed as a comment or literal and the search in comments or literals is enabled, it checks if the word is equal to the searched element's name.
* After the usages are collected, results are shown in the usages pane.
The text shown for each found element is taken from the
To have the title of the found element be correctly displayed in the title of the Find Usages tool window, you need to provide an implementation of the
ElementDescriptionLocation passed to the provider in this case will be an instance of
TIP In cases like function parameters and local variables, consider overriding
PsiElement.getUseScope()to return a narrower scope. For instance, you might return just the scope of the nearest function definition. This optimization can significantly reduce the number of files that need to be parsed--and references that need to be resolved--when renaming a function parameter or local variable.