# Text Selection

> For the complete documentation index, see [llms.txt](https://plugins.jetbrains.com/docs/intellij/llms.txt).

## Extending/Shrinking Text Selection

Implementing [ExtendWordSelectionHandler](https://github.com/JetBrains/intellij-community/tree/idea/263.7307.200/platform/lang-api/src/com/intellij/codeInsight/editorActions/ExtendWordSelectionHandler.java) and registering it in [com.intellij.extendWordSelectionHandler](https://jb.gg/ipe?extensions=com.intellij.extendWordSelectionHandler) extension point  in the `[plugin.xml](plugin-configuration-file.html)` provides additional text ranges to be used when extending or shrinking a selection. Return `true` from `canSelect(PsiElement)` for the PSI elements that need additional text ranges. The IntelliJ Platform will call `select(PsiElement, CharSequence, int, Editor)` for these elements; compute additional text ranges there and return them as `List<TextRange>`.

See also:

* [Surround With](surround-with.html)

* [Additional Minor Features](additional-minor-features.html)

### Implementation

The two actions [Extend Selection and Shrink Selection](https://www.jetbrains.com/help/idea/working-with-source-code.html#editor_code_selection) in IntelliJ Platform IDEs adjust selected text based on the structure of the source code. This makes it easy to select not only expressions, blocks, and function definitions, but also code like whole lines or tags in Javadoc comments.

When implementing a custom language, the IntelliJ Platform provides basic implementations of this EP, which select code based on the PSI structure, as well as whole lines. In many cases this is sufficient to provide a good user experience. However, sometimes it's advantageous to provide additional regions that the user may wish to be able to select when extending or shrinking a selection.

This EP has two methods that need to be implemented:

1. `canSelect(PsiElement)` is called on each PSI element, starting from the element at the cursor and walking up each of its parents. Return `true` for a particular element to indicate that further text-ranges should be included for the PSI element.

2. `select(PsiElement, CharSequence, int, Editor)` returns the text-ranges within the PSI element of interest are calculated and returned.

### Example Use-Case

A possible use-case for custom language developers is a function call `f(a, b)` where the function call node has its two arguments as children. If the cursor is located at argument `a`, extending the selection would first select argument `a` itself and in the next step grow to cover the whole function call. However, an intermediate step selecting the list of all arguments might be useful. This can be achieved by implementing this EP in the following way:

1. Create a class that implements `ExtendWordSelectionHandler` and register it in a [com.intellij.extendWordSelectionHandler](https://jb.gg/ipe?extensions=com.intellij.extendWordSelectionHandler) extension point  in the `plugin.xml`.

2. The `canSelect(PsiElement)` method should return `true` for the function call node. That indicates that `select(PsiElement, CharSequence, int, Editor)` will be called for the function-call node.

3. When the `select()` method is called, use the function call PSI element or the editor text to extract the text range that spans the arguments `a` and `b` and return it as `List<TextRange>` with one element.

### Further Insight and Debugging

Looking at other implementations can be an effective way to get a better understanding of how this EP works. For further insight into this EP, see [DocTagSelectioner](https://github.com/JetBrains/intellij-community/tree/idea/263.7307.200/java/java-frontback-impl/src/com/intellij/codeInsight/editorActions/wordSelection/DocTagSelectioner.java). It provides the ability to select tag names like `@param` in Javadoc comments. Browse the list of open-source plugins with implementations of the [com.intellij.extendWordSelectionHandler](https://jb.gg/ipe?extensions=com.intellij.extendWordSelectionHandler) extension point .

There are also some important places in the IntelliJ Platform to add breakpoints during debugging. When Extend Selection is called by the user, it is handled by [SelectWordHandler](https://github.com/JetBrains/intellij-community/tree/idea/263.7307.200/platform/lang-impl/src/com/intellij/codeInsight/editorActions/SelectWordHandler.java). The majority of the work, however, is then done inside [SelectWordUtil](https://github.com/JetBrains/intellij-community/tree/idea/263.7307.200/platform/lang-impl/src/com/intellij/codeInsight/editorActions/SelectWordUtil.java), where `processElement()` checks which implementations of this EP apply for the current PSI element. If one of them returns `true` from its `canSelect()` method, the additional text ranges are extracted in the `askSelectioner()` function. These places are good candidates to set breakpoints and investigate during debugging.