Find Usages

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 PsiNamedElement and PsiReference interfaces.

Examples: - Implementation of FindUsagesProvider in Properties language plugin - Custom Language Support Tutorial: Find Usages

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. Using the 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 PsiNamedElement. The word cache will be used to search for the text returned from the PsiNamedElement.getName() method. Also, if the text range of the PsiNamedElement includes some other text besides the identifier returned from getName() (for example, if the PsiNamedElement represents a JavaScript function and its text range includes 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.getType() and 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 FindUsagesProvider.getNodeText() method.

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 ElementDescriptionProvider interface. The ElementDescriptionLocation passed to the provider in this case will be an instance of UsageViewLongNameLocation.

Example: ElementDescriptionProvider for Properties language plugin

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.