hxuanyu/intellij-sdk-code-samples
1
0
Fork 0
mirror of https://github.com/JetBrains/intellij-sdk-code-samples.git synced 2025-07-28 01:07:49 +08:00
Code Issues Packages Projects Releases Wiki Activity

multiple_carets.md: update, cleanup, links

Browse Source
This commit is contained in:
Yann Cébron 2022-09-21 13:26:14 +02:00
parent ab3ace219e
commit e03661b24c
1 changed files with 19 additions and 26 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

45
topics/reference_guide/multiple_carets.md
View File

@ -2,36 +2,29 @@
<!-- Copyright 2000-2022 JetBrains s.r.o. and other contributors. Use of this source code is governed by the Apache 2.0 license that can be found in the LICENSE file. --> <!-- Copyright 2000-2022 JetBrains s.r.o. and other contributors. Use of this source code is governed by the Apache 2.0 license that can be found in the LICENSE file. -->
## Introduction
Support for multiple independent carets has been added to editor implementation in IDEA 13.1.
Most editor actions (keyboard navigation, text insertion and deletion, etc.) will be applied to each caret independently. Most editor actions (keyboard navigation, text insertion and deletion, etc.) will be applied to each caret independently.
Each caret has its own associated selection, which is a continuous range of document characters (can be empty). Each caret has its own associated selection, which is a continuous range of document characters (can be empty).
When after some action two or more carets end up in the same visual position, they are merged into a single caret with their associated selections merged into a single one. When after some action two or more carets end up in the same visual position, they are merged into a single caret with their associated selections merged into a single one.
A similar thing will happen when selections for several carets become overlapped: only one of the carets will remain, and the selections will be merged. A similar thing will happen when selections for several carets become overlapped: only one of the carets will remain, and the selections will be merged.
There's a concept of 'primary' caret — the one on which non-multi-caret-aware actions and the actions which need a single-point document context (like code completion) will operate.
There's a concept of _primary_ caret — the one on which non-multi-caret-aware actions and the actions which need a single-point document context (like code completion) will operate.
Currently, the most recent caret is considered the primary one. Currently, the most recent caret is considered the primary one.
## Core Functionality ## Core Functionality
Core logic related to multi-caret implementation such as accessing currently existing carets, adding and removing carets, is available via [`CaretModel`](%gh-ic%/platform/editor-ui-api/src/com/intellij/openapi/editor/CaretModel.java) interface, some changes also have been made in [`SelectionModel`](%gh-ic%/platform/editor-ui-api/src/com/intellij/openapi/editor/SelectionModel.java) interface. Core logic related to multi-caret implementation such as accessing currently existing carets, adding and removing carets, is available via [`CaretModel`](%gh-ic%/platform/editor-ui-api/src/com/intellij/openapi/editor/CaretModel.java).
Check Javadoc of those interfaces for details. For text selection, see [`SelectionModel`](%gh-ic%/platform/editor-ui-api/src/com/intellij/openapi/editor/SelectionModel.java).
Notable changes from old behaviour: Methods in `CaretModel` and `SelectionModel` to query and modify caret and selection positions work by default on the primary caret.
In the context of `CaretModel.runForEachCaret()` method though, they operate on the current caret.
* Previously existing methods in `CaretModel` and `SelectionModel` to query and modify caret and selection positions work by default on the primary caret now. `SelectionModel.getBlockSelectionStarts()` and `getBlockSelectionEnds()` work in multi-caret state, returning all selected regions.
In the context of `CaretModel.runForEachCaret` method though, they operate on the current caret.
So the behaviour of legacy code (not using Caret interface) will depend on the context of its invocation.
* Block selection doesn't exist as a separate concept anymore.
Correspondingly, block-selection-related methods in SelectionModel interface have changed behaviour — `hasBlockSelection()` will always return false, `setBlockSelection()` will create a multi-caret selection equivalent to the requested block selection.
`getBlockSelectionStarts()` and `getBlockSelectionEnds()` methods work in multi-caret state, returning all selected regions.
## Editor Actions ## Editor Actions
### EditorAction and EditorActionHandler ### EditorAction and EditorActionHandler
When [`EditorActionHandler`](%gh-ic%/platform/platform-api/src/com/intellij/openapi/editor/actionSystem/EditorActionHandler.java) is invoked, an additional parameter will be passed to it — a caret instance on which it should operate, or `null` if it's invoked without any caret context. When [`EditorActionHandler`](%gh-ic%/platform/platform-api/src/com/intellij/openapi/editor/actionSystem/EditorActionHandler.java) is invoked, an additional parameter will be passed to it: a caret instance on which it should operate, or `null` if it's invoked without any caret context.
If the handler invokes another handler (delegate handler for the same `actionId` or a completely unrelated handler), that parameter should normally be passed to the delegate unchanged (unless no context caret has been provided to the handler, but it needs to invoke another handler on a specific caret). If the handler invokes another handler (delegate handler for the same `actionId` or a completely unrelated handler), that parameter should normally be passed to the delegate unchanged (unless no context caret has been provided to the handler, but it needs to invoke another handler on a specific caret).
Of course, the handler can just ignore the caret parameter if its functionality is not related to caret/selection position. Of course, the handler can just ignore the caret parameter if its functionality is not related to caret/selection position.
@ -41,16 +34,16 @@ If the handler needs to implement multi-caret functionality it can do so explici
The following delegates are available: The following delegates are available:
* `EnterHandlerDelegate` * [`EnterHandlerDelegate`](%gh-ic%/platform/lang-impl/src/com/intellij/codeInsight/editorActions/enter/EnterHandlerDelegate.java)
* `BackspaceHandlerDelegate` * [`BackspaceHandlerDelegate`](%gh-ic%/platform/lang-api/src/com/intellij/codeInsight/editorActions/BackspaceHandlerDelegate.java)
* `JoinLinesHandlerDelegate` * [`JoinLinesHandlerDelegate`](%gh-ic%/platform/lang-api/src/com/intellij/codeInsight/editorActions/JoinLinesHandlerDelegate.java)
* `EditorNavigationDelegate` * [`EditorNavigationDelegate`](%gh-ic%/platform/platform-api/src/com/intellij/openapi/editor/EditorNavigationDelegate.java)
* `SmartEnterProcessor` * [`SmartEnterProcessor`](%gh-ic%/platform/lang-api/src/com/intellij/codeInsight/editorActions/smartEnter/SmartEnterProcessor.java)
* `CommentCompleteHandler` * [`CommentCompleteHandler`](%gh-ic%/platform/lang-impl/src/com/intellij/codeInsight/editorActions/CommentCompleteHandler.java)
* `StatementUpDownMover` * [`StatementUpDownMover`](%gh-ic%/platform/lang-api/src/com/intellij/codeInsight/editorActions/moveUpDown/StatementUpDownMover.java)
* `CodeBlockProvider` * [`CodeBlockProvider`](%gh-ic%/platform/lang-impl/src/com/intellij/codeInsight/editorActions/CodeBlockProvider.java)
At the moment there's no need to make any changes in the handlers to support multiple carets — they are already invoked for each caret. There is no need to make any changes in the handlers to support multiple carets — they are already invoked for each caret.
## Typing Actions ## Typing Actions
@ -60,13 +53,13 @@ At the moment there's no need to make any changes in the handlers to support mul
If those handlers need to support multiple carets, they will need to implement that explicitly. If those handlers need to support multiple carets, they will need to implement that explicitly.
[`EditorModificationUtil`](%gh-ic%/platform/platform-api/src/com/intellij/openapi/editor/EditorModificationUtil.java). [`EditorModificationUtil`](%gh-ic%/platform/platform-api/src/com/intellij/openapi/editor/EditorModificationUtil.java).
`typeInStringAtCaretHonorMultipleCarets()` method is available to do the most common task in this case — inserting the same text into all caret positions and/or moving all carets relatively to their current position. `typeInStringAtCaretHonorMultipleCarets()` method is available to do the most common task in this case: inserting the same text into all caret positions and/or moving all carets relatively to their current position.
Examples of its usage: Examples of its usage:
* [`TypedAction`](%gh-ic%/platform/platform-api/src/com/intellij/openapi/editor/actionSystem/TypedAction.java). * [`TypedAction`](%gh-ic%/platform/platform-api/src/com/intellij/openapi/editor/actionSystem/TypedAction.java).
* [`XmlGtTypedHandler`](%gh-ic%/xml/impl/src/com/intellij/codeInsight/editorActions/XmlGtTypedHandler.java). * [`XmlGtTypedHandler`](%gh-ic%/xml/impl/src/com/intellij/codeInsight/editorActions/XmlGtTypedHandler.java).
> Starting from version 14, [`TypedHandlerDelegate`](%gh-ic%/platform/lang-api/src/com/intellij/codeInsight/editorActions/TypedHandlerDelegate.java) implementations are invoked automatically for each caret. > [`TypedHandlerDelegate`](%gh-ic%/platform/lang-api/src/com/intellij/codeInsight/editorActions/TypedHandlerDelegate.java) implementations are invoked automatically for each caret.
> If one wants to implement custom multicaret behaviour on typing, [`TypedActionHandler`](%gh-ic%/platform/platform-api/src/com/intellij/openapi/editor/actionSystem/TypedActionHandler.java) needs to be provided instead. > If one wants to implement custom multicaret behaviour on typing, [`TypedActionHandler`](%gh-ic%/platform/platform-api/src/com/intellij/openapi/editor/actionSystem/TypedActionHandler.java) needs to be provided instead.
> >
{type="note"} {type="note"}