replaced <code></code> with more concise {@code}
[idea/community.git] / platform / editor-ui-api / src / com / intellij / openapi / editor / Caret.java
index 976dc1f1be40a475b914089b585728ce63fd0195..41b6329c05356283493d940c7d4bb828210a8395 100644 (file)
@@ -1,5 +1,5 @@
 /*
- * Copyright 2000-2014 JetBrains s.r.o.
+ * Copyright 2000-2015 JetBrains s.r.o.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -21,11 +21,19 @@ import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
 
 /**
- * Represents a specific caret instance in the editor when it support multiple carets (see {@link CaretModel#supportsMultipleCarets()}.
+ * Represents a specific caret instance in the editor.
  * Provides methods to query and modify caret position and caret's associated selection.
+ * <p>
+ * Instances of this interface are supposed to be obtained from {@link CaretModel} instance, and not created explicitly.
  */
 public interface Caret extends UserDataHolderEx, Disposable {
   /**
+   * Returns an instance of Editor, current caret belongs to.
+   */
+  @NotNull
+  Editor getEditor();
+
+  /**
    * Returns an instance of CaretModel, current caret is associated with.
    */
   @NotNull
@@ -35,8 +43,8 @@ public interface Caret extends UserDataHolderEx, Disposable {
    * Tells whether this caret is valid, i.e. recognized by the caret model currently. Caret is valid since its creation till its
    * removal from caret model.
    *
-   * @see com.intellij.openapi.editor.CaretModel#addCaret(VisualPosition)
-   * @see com.intellij.openapi.editor.CaretModel#removeCaret(Caret)
+   * @see CaretModel#addCaret(VisualPosition)
+   * @see CaretModel#removeCaret(Caret)
    */
   boolean isValid();
 
@@ -69,7 +77,7 @@ public interface Caret extends UserDataHolderEx, Disposable {
   void moveToVisualPosition(@NotNull VisualPosition pos);
 
   /**
-   * Short hand for calling {@link #moveToOffset(int, boolean)} with <code>'false'</code> as a second argument.
+   * Short hand for calling {@link #moveToOffset(int, boolean)} with {@code 'false'} as a second argument.
    *
    * @param offset      the offset to move to
    */
@@ -94,7 +102,7 @@ public interface Caret extends UserDataHolderEx, Disposable {
    * <p/>
    * Current method allows to check that.
    *
-   * @return    <code>true</code> if caret position is up-to-date for now; <code>false</code> otherwise
+   * @return    {@code true} if caret position is up-to-date for now; {@code false} otherwise
    */
   boolean isUpToDate();
 
@@ -115,9 +123,11 @@ public interface Caret extends UserDataHolderEx, Disposable {
   VisualPosition getVisualPosition();
 
   /**
-   * Returns the offset of the caret in the document.
+   * Returns the offset of the caret in the document. Returns 0 for a disposed (invalid) caret.
    *
    * @return the caret offset.
+   *
+   * @see #isValid()
    */
   int getOffset();
 
@@ -192,6 +202,8 @@ public interface Caret extends UserDataHolderEx, Disposable {
 
   /**
    * Selects the specified range of text.
+   * <p>
+   * System selection will be updated, if such feature is supported by current editor.
    *
    * @param startOffset the start offset of the text range to select.
    * @param endOffset   the end offset of the text range to select.
@@ -199,12 +211,25 @@ public interface Caret extends UserDataHolderEx, Disposable {
   void setSelection(int startOffset, int endOffset);
 
   /**
+   * Selects the specified range of text.
+   *
+   * @param startOffset the start offset of the text range to select.
+   * @param endOffset   the end offset of the text range to select.
+   * @param updateSystemSelection whether system selection should be updated (might not have any effect if current editor doesn't support such a feature)
+   */
+  void setSelection(int startOffset, int endOffset, boolean updateSystemSelection);
+
+  /**
    * Selects target range providing information about visual boundary of selection end.
    * <p/>
    * That is the case for soft wraps-aware processing where the whole soft wraps virtual space is matched to the same offset.
+   * <p/>
+   * Also, in column mode this method allows to create selection spanning virtual space after the line end.
+   * <p>
+   * System selection will be updated, if such feature is supported by current editor.
    *
    * @param startOffset     start selection offset
-   * @param endPosition     end visual position of the text range to select (<code>null</code> argument means that
+   * @param endPosition     end visual position of the text range to select ({@code null} argument means that
    *                        no specific visual position should be used)
    * @param endOffset       end selection offset
    */
@@ -214,10 +239,14 @@ public interface Caret extends UserDataHolderEx, Disposable {
    * Selects target range based on its visual boundaries.
    * <p/>
    * That is the case for soft wraps-aware processing where the whole soft wraps virtual space is matched to the same offset.
+   * <p/>
+   * Also, in column mode this method allows to create selection spanning virtual space after the line end.
+   * <p>
+   * System selection will be updated, if such feature is supported by current editor.
    *
-   * @param startPosition   start visual position of the text range to select (<code>null</code> argument means that
+   * @param startPosition   start visual position of the text range to select ({@code null} argument means that
    *                        no specific visual position should be used)
-   * @param endPosition     end visual position of the text range to select (<code>null</code> argument means that
+   * @param endPosition     end visual position of the text range to select ({@code null} argument means that
    *                        no specific visual position should be used)
    * @param startOffset     start selection offset
    * @param endOffset       end selection offset
@@ -225,6 +254,23 @@ public interface Caret extends UserDataHolderEx, Disposable {
   void setSelection(@Nullable VisualPosition startPosition, int startOffset, @Nullable VisualPosition endPosition, int endOffset);
 
   /**
+   * Selects target range based on its visual boundaries.
+   * <p/>
+   * That is the case for soft wraps-aware processing where the whole soft wraps virtual space is matched to the same offset.
+   * <p/>
+   * Also, in column mode this method allows to create selection spanning virtual space after the line end.
+   *
+   * @param startPosition   start visual position of the text range to select ({@code null} argument means that
+   *                        no specific visual position should be used)
+   * @param endPosition     end visual position of the text range to select ({@code null} argument means that
+   *                        no specific visual position should be used)
+   * @param startOffset     start selection offset
+   * @param endOffset       end selection offset
+   * @param updateSystemSelection whether system selection should be updated (might not have any effect if current editor doesn't support such a feature)
+   */
+  void setSelection(@Nullable VisualPosition startPosition, int startOffset, @Nullable VisualPosition endPosition, int endOffset, boolean updateSystemSelection);
+
+  /**
    * Removes the selection in the editor.
    */
   void removeSelection();
@@ -248,9 +294,40 @@ public interface Caret extends UserDataHolderEx, Disposable {
    * Clones the current caret and positions the new one right above or below the current one. If current caret has selection, corresponding
    * selection will be set for the new caret.
    *
-   * @param above if <code>true</code>, new caret will be created at the previous line, if <code>false</code> - on the next line
-   * @return newly created caret instance, or null if the caret cannot be created because it already exists at the new location
+   * @param above if {@code true}, new caret will be created at the previous line, if {@code false} - on the next line
+   * @return newly created caret instance, or {@code null} if the caret cannot be created because it already exists at the new location
+   * or caret model doesn't support multiple carets.
    */
   @Nullable
   Caret clone(boolean above);
+
+  /**
+   * Returns {@code true} if caret is located in RTL text fragment. In that case visual column number is inversely related
+   * to offset and logical column number in the vicinity of caret.
+   */
+  boolean isAtRtlLocation();
+
+  /**
+   * Returns {@code true} if caret is located at a boundary between different runs of bidirectional text.
+   * This means that text fragments at different sides of the boundary are non-adjacent in logical order.
+   * Caret can located at any side of the boundary, 
+   * exact location can be determined from directionality flags of caret's logical and visual position 
+   * ({@link LogicalPosition#leansForward} and {@link VisualPosition#leansRight}).
+   */
+  boolean isAtBidiRunBoundary();
+
+  /**
+   * Returns visual attributes currently set for the caret.
+   *
+   * @see #setVisualAttributes(CaretVisualAttributes)
+   */
+  @NotNull
+  CaretVisualAttributes getVisualAttributes();
+
+  /**
+   * Sets caret's current visual attributes. This can have no effect if editor doesn't support changing caret's visual appearance.
+   *
+   * @see #getVisualAttributes()
+   */
+  void setVisualAttributes(@NotNull CaretVisualAttributes attributes);
 }