2. Editor Coordinates System. Positions and Offsets

Editor Basics Code Sample

In this tutorial, the editor_basics code sample is used to explore caret positions. In particular, the Caret Position action added by editor_basics to the editor context menu is used to retrieve information about the current caret position. A keyboard shortcut can also initiate the action.

The source code for the Java class behind the menu action is EditorAreaIllustration. The focus of discussion will be the EditorAreaIllustration.actionPerformed() method. For more information about creating action classes, see the Actions Tutorial, which covers the topic in depth.

Caret Positions from the `CaretModel` and `Caret` Objects

The properties of a caret can be accessed by obtaining an instance of the CaretModel object. As in the Working with Text tutorial, the AnActionEvent is used to get the Editor object. The Editor object provides access to the CaretModel object, as shown below:

public class EditorAreaIllustration extends AnAction {
  @Override
  public void actionPerformed(@NotNull AnActionEvent event) {
    // Get access to the editor and caret model. update() validated editor's existence.
    Editor editor = event.getRequiredData(CommonDataKeys.EDITOR);
    CaretModel caretModel = editor.getCaretModel();
  }
}

Editor Coordinate Systems

When a Document is opened, the Editor assigns an internal, zero-based coordinate system to lines and columns in the Document. The first line in a Document and the first character in each line are assigned the zero position. Every character in a Document is assigned an Offset, which is a zero-based count of the characters from the beginning of the file to that character. These LogicalPosition coordinates are used to describe the line and column number for a caret position. Note that the Logical Position coordinate system is different from the editor UI, which is one-based rather than zero-based.

Logical Position coordinates and other coordinate systems discussed in this tutorial can be used to characterize any location in an Editor, not just carets. Hints used for code insights are characterized in terms of these coordinates, for example HintManager.getHintPosition(). Custom visual elements displayed in an Editor, called Inlay objects, are also expressed in terms of these coordinate systems.

The Multiple Carets documentation covers the subject of more than one caret in an Editor. For this tutorial, be aware there may be more than one caret in an Editor at any given time. Consequently, examples use the Primary Caret in an Editor. If there is only one caret in an Editor, it is the Primary Caret. For the case of multiple carets in an Editor, the Primary Caret is the one on which query and update methods in the model operate at the moment.

Caret Visual Position

A caret's Visual Position differs from Logical Position in that it takes into account editor presentation settings such as Code Folding and Soft Line Wrap. In doing so, VisualPosition counts - zero-based - the lines of a Document that can be displayed in an Editor. Consequently, Visual Positions can't be uniquely mapped to Logical Positions or corresponding lines in the underlying Document.

public class EditorAreaIllustration extends AnAction {
  @Override
  public void actionPerformed(@NotNull AnActionEvent event) {
    // Get access to the editor and caret model.
    Editor editor = event.getRequiredData(CommonDataKeys.EDITOR);
    CaretModel caretModel = editor.getCaretModel();
    Caret primaryCaret = caretModel.getPrimaryCaret();
    LogicalPosition logicalPos = primaryCaret.getLogicalPosition();
    VisualPosition visualPos = primaryCaret.getVisualPosition();
  }
}

Caret Column Position

Examples of Caret Lean

Consider the Java snippet below, and use the editor_basics Caret Position action to report caret information at each step. Be sure to use the keyboard shortcut to invoke the action so that the caret position is not disturbed.

The line containing the String variable declaration contains bidirectional text. Starting on the left end of the line, and using the arrow key to advance a line-shaped cursor to between the (" characters reveals discontinuities in caret coordinate column positions.

public void showNow() {
//234567890123456789012345678901234567890123456789012345678901234567890
  String str = new String("تعطي يونيكود رقما فريدا لكل حرف".getBytes(), java.nio.charset.StandardCharsets.UTF_8);
  System.out.println(str);
}

Displaying Caret Positions

To display the values of caret Logical and Visual positions, and Offset, a Messages.showInfoMessage() method shows them in the form of notification as the action is performed.

public class EditorAreaIllustration extends AnAction {

  public void actionPerformed(@NotNull AnActionEvent event) {
    // Get access to the editor and caret model.
    Editor editor = event.getRequiredData(CommonDataKeys.EDITOR);
    CaretModel caretModel = editor.getCaretModel();

    // Getting the primary caret ensures we get the correct one of a possible many.
    Caret primaryCaret = caretModel.getPrimaryCaret();
    // Get the caret information
    LogicalPosition logicalPos = primaryCaret.getLogicalPosition();
    VisualPosition visualPos = primaryCaret.getVisualPosition();
    int caretOffset = primaryCaret.getOffset();

    // Build and display the caret report.
    String report = logicalPos.toString() + "\n" +
        visualPos.toString() + "\n" +
        "Offset: " + caretOffset;
    Messages.showInfoMessage(report, "Caret Parameters Inside The Editor");
  }

}

2. Editor Coordinates System. Positions and Offsets﻿

Editor Basics Code Sample﻿

Caret Positions from the CaretModel and Caret Objects﻿

Editor Coordinate Systems﻿

Caret Logical Position﻿

Caret Visual Position﻿

Caret Column Position﻿

Caret Lean﻿

Examples of Caret Lean﻿

Caret Offset﻿

Displaying Caret Positions﻿