incapsulate rtl context determination in Caret instance
[idea/community.git] / platform / editor-ui-api / src / com / intellij / openapi / editor / Caret.java
1 /*
2  * Copyright 2000-2015 JetBrains s.r.o.
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 package com.intellij.openapi.editor;
17
18 import com.intellij.openapi.Disposable;
19 import com.intellij.openapi.util.UserDataHolderEx;
20 import org.jetbrains.annotations.NotNull;
21 import org.jetbrains.annotations.Nullable;
22
23 /**
24  * Represents a specific caret instance in the editor.
25  * Provides methods to query and modify caret position and caret's associated selection.
26  */
27 public interface Caret extends UserDataHolderEx, Disposable {
28   /**
29    * Returns an instance of Editor, current caret belongs to.
30    */
31   @NotNull
32   Editor getEditor();
33
34   /**
35    * Returns an instance of CaretModel, current caret is associated with.
36    */
37   @NotNull
38   CaretModel getCaretModel();
39
40   /**
41    * Tells whether this caret is valid, i.e. recognized by the caret model currently. Caret is valid since its creation till its
42    * removal from caret model.
43    *
44    * @see CaretModel#addCaret(VisualPosition)
45    * @see CaretModel#removeCaret(Caret)
46    */
47   boolean isValid();
48
49   /**
50    * Moves the caret by the specified number of lines and/or columns.
51    *
52    * @param columnShift    the number of columns to move the caret by.
53    * @param lineShift      the number of lines to move the caret by.
54    * @param withSelection  if true, the caret move should extend the selection in the document.
55    * @param scrollToCaret  if true, the document should be scrolled so that the caret is visible after the move.
56    */
57   void moveCaretRelatively(int columnShift,
58                            int lineShift,
59                            boolean withSelection,
60                            boolean scrollToCaret);
61
62   /**
63    * Moves the caret to the specified logical position.
64    * If corresponding position is in the folded region currently, the region will be expanded.
65    *
66    * @param pos the position to move to.
67    */
68   void moveToLogicalPosition(@NotNull LogicalPosition pos);
69
70   /**
71    * Moves the caret to the specified visual position.
72    *
73    * @param pos the position to move to.
74    */
75   void moveToVisualPosition(@NotNull VisualPosition pos);
76
77   /**
78    * Short hand for calling {@link #moveToOffset(int, boolean)} with <code>'false'</code> as a second argument.
79    *
80    * @param offset      the offset to move to
81    */
82   void moveToOffset(int offset);
83
84   /**
85    * Moves the caret to the specified offset in the document.
86    * If corresponding position is in the folded region currently, the region will be expanded.
87    *
88    * @param offset                  the offset to move to.
89    * @param locateBeforeSoftWrap    there is a possible case that there is a soft wrap at the given offset, hence, the same offset
90    *                                corresponds to two different visual positions - just before soft wrap and just after soft wrap.
91    *                                We may want to clearly indicate where to put the caret then. Given parameter allows to do that.
92    *                                <b>Note:</b> it's ignored if there is no soft wrap at the given offset
93    */
94   void moveToOffset(int offset, boolean locateBeforeSoftWrap);
95
96   /**
97    * Caret position may be updated on document change (e.g. consider that user updates from VCS that causes addition of text
98    * before caret. Caret offset, visual and logical positions should be updated then). So, there is a possible case
99    * that caret model in in the process of caret position update now.
100    * <p/>
101    * Current method allows to check that.
102    *
103    * @return    <code>true</code> if caret position is up-to-date for now; <code>false</code> otherwise
104    */
105   boolean isUpToDate();
106
107   /**
108    * Returns the logical position of the caret.
109    *
110    * @return the caret position.
111    */
112   @NotNull
113   LogicalPosition getLogicalPosition();
114
115   /**
116    * Returns the visual position of the caret.
117    *
118    * @return the caret position.
119    */
120   @NotNull
121   VisualPosition getVisualPosition();
122
123   /**
124    * Returns the offset of the caret in the document.
125    *
126    * @return the caret offset.
127    */
128   int getOffset();
129
130   /**
131    * @return    document offset for the start of the logical line where caret is located
132    */
133   int getVisualLineStart();
134
135   /**
136    * @return    document offset that points to the first symbol shown at the next visual line after the one with caret on it
137    */
138   int getVisualLineEnd();
139
140   /**
141    * Returns the start offset in the document of the selected text range, or the caret
142    * position if there is currently no selection.
143    *
144    * @return the selection start offset.
145    */
146   int getSelectionStart();
147
148   /**
149    * @return    object that encapsulates information about visual position of selected text start if any
150    */
151   @NotNull
152   VisualPosition getSelectionStartPosition();
153
154   /**
155    * Returns the end offset in the document of the selected text range, or the caret
156    * position if there is currently no selection.
157    *
158    * @return the selection end offset.
159    */
160   int getSelectionEnd();
161
162   /**
163    * @return    object that encapsulates information about visual position of selected text end if any;
164    */
165   @NotNull
166   VisualPosition getSelectionEndPosition();
167
168   /**
169    * Returns the text selected in the editor.
170    *
171    * @return the selected text, or null if there is currently no selection.
172    */
173   @Nullable
174   String getSelectedText();
175
176   /**
177    * Returns the offset from which the user started to extend the selection (the selection start
178    * if the selection was extended in forward direction, or the selection end if it was
179    * extended backward).
180    *
181    * @return the offset from which the selection was started, or the caret offset if there is
182    *         currently no selection.
183    */
184   int getLeadSelectionOffset();
185
186   /**
187    * @return    object that encapsulates information about visual position from which the user started to extend the selection if any
188    */
189   @NotNull
190   VisualPosition getLeadSelectionPosition();
191
192   /**
193    * Checks if a range of text is currently selected.
194    *
195    * @return true if a range of text is selected, false otherwise.
196    */
197   boolean hasSelection();
198
199   /**
200    * Selects the specified range of text.
201    * <p>
202    * System selection will be updated, if such feature is supported by current editor.
203    *
204    * @param startOffset the start offset of the text range to select.
205    * @param endOffset   the end offset of the text range to select.
206    */
207   void setSelection(int startOffset, int endOffset);
208
209   /**
210    * Selects the specified range of text.
211    *
212    * @param startOffset the start offset of the text range to select.
213    * @param endOffset   the end offset of the text range to select.
214    * @param updateSystemSelection whether system selection should be updated (might not have any effect if current editor doesn't support such a feature)
215    */
216   void setSelection(int startOffset, int endOffset, boolean updateSystemSelection);
217
218   /**
219    * Selects target range providing information about visual boundary of selection end.
220    * <p/>
221    * That is the case for soft wraps-aware processing where the whole soft wraps virtual space is matched to the same offset.
222    * <p/>
223    * Also, in column mode this method allows to create selection spanning virtual space after the line end.
224    * <p>
225    * System selection will be updated, if such feature is supported by current editor.
226    *
227    * @param startOffset     start selection offset
228    * @param endPosition     end visual position of the text range to select (<code>null</code> argument means that
229    *                        no specific visual position should be used)
230    * @param endOffset       end selection offset
231    */
232   void setSelection(int startOffset, @Nullable VisualPosition endPosition, int endOffset);
233
234   /**
235    * Selects target range based on its visual boundaries.
236    * <p/>
237    * That is the case for soft wraps-aware processing where the whole soft wraps virtual space is matched to the same offset.
238    * <p/>
239    * Also, in column mode this method allows to create selection spanning virtual space after the line end.
240    * <p>
241    * System selection will be updated, if such feature is supported by current editor.
242    *
243    * @param startPosition   start visual position of the text range to select (<code>null</code> argument means that
244    *                        no specific visual position should be used)
245    * @param endPosition     end visual position of the text range to select (<code>null</code> argument means that
246    *                        no specific visual position should be used)
247    * @param startOffset     start selection offset
248    * @param endOffset       end selection offset
249    */
250   void setSelection(@Nullable VisualPosition startPosition, int startOffset, @Nullable VisualPosition endPosition, int endOffset);
251
252   /**
253    * Selects target range based on its visual boundaries.
254    * <p/>
255    * That is the case for soft wraps-aware processing where the whole soft wraps virtual space is matched to the same offset.
256    * <p/>
257    * Also, in column mode this method allows to create selection spanning virtual space after the line end.
258    *
259    * @param startPosition   start visual position of the text range to select (<code>null</code> argument means that
260    *                        no specific visual position should be used)
261    * @param endPosition     end visual position of the text range to select (<code>null</code> argument means that
262    *                        no specific visual position should be used)
263    * @param startOffset     start selection offset
264    * @param endOffset       end selection offset
265    * @param updateSystemSelection whether system selection should be updated (might not have any effect if current editor doesn't support such a feature)
266    */
267   void setSelection(@Nullable VisualPosition startPosition, int startOffset, @Nullable VisualPosition endPosition, int endOffset, boolean updateSystemSelection);
268
269   /**
270    * Removes the selection in the editor.
271    */
272   void removeSelection();
273
274   /**
275    * Selects the entire line of text at the caret position.
276    */
277   void selectLineAtCaret();
278
279   /**
280    * Selects the entire word at the caret position, optionally using camel-case rules to
281    * determine word boundaries.
282    *
283    * @param honorCamelWordsSettings if true and "Use CamelHumps words" is enabled,
284    *                                upper-case letters within the word are considered as
285    *                                boundaries for the range of text to select.
286    */
287   void selectWordAtCaret(boolean honorCamelWordsSettings);
288
289   /**
290    * Clones the current caret and positions the new one right above or below the current one. If current caret has selection, corresponding
291    * selection will be set for the new caret.
292    *
293    * @param above if <code>true</code>, new caret will be created at the previous line, if <code>false</code> - on the next line
294    * @return newly created caret instance, or <code>null</code> if the caret cannot be created because it already exists at the new location
295    * or caret model doesn't support multiple carets.
296    */
297   @Nullable
298   Caret clone(boolean above);
299
300   /**
301    * Returns <code>true</code> if caret is located in RTL text fragment. In that case visual column number is inversely related
302    * to offset and logical column number in the vicinity of caret.
303    */
304   boolean isAtRtlLocation();
305 }