replaced <code></code> with more concise {@code}
[idea/community.git] / platform / editor-ui-api / src / com / intellij / openapi / editor / Caret.java
index 68ff8ce7f563aeb5c352ff30209d32977ac12d39..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.
@@ -23,6 +23,8 @@ import org.jetbrains.annotations.Nullable;
 /**
  * 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 {
   /**
@@ -75,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
    */
@@ -100,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();
 
@@ -121,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();
 
@@ -225,7 +229,7 @@ public interface Caret extends UserDataHolderEx, Disposable {
    * 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
    */
@@ -240,9 +244,9 @@ public interface Caret extends UserDataHolderEx, Disposable {
    * <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
@@ -256,9 +260,9 @@ public interface Caret extends UserDataHolderEx, Disposable {
    * <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</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
@@ -290,10 +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 <code>null</code> 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);
 }