8e85f25ca51a34c5c2a8612e8c7762a76783a350
[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. Returns 0 for a disposed (invalid) caret.
125    *
126    * @return the caret offset.
127    *
128    * @see #isValid()
129    */
130   int getOffset();
131
132   /**
133    * @return    document offset for the start of the logical line where caret is located
134    */
135   int getVisualLineStart();
136
137   /**
138    * @return    document offset that points to the first symbol shown at the next visual line after the one with caret on it
139    */
140   int getVisualLineEnd();
141
142   /**
143    * Returns the start offset in the document of the selected text range, or the caret
144    * position if there is currently no selection.
145    *
146    * @return the selection start offset.
147    */
148   int getSelectionStart();
149
150   /**
151    * @return    object that encapsulates information about visual position of selected text start if any
152    */
153   @NotNull
154   VisualPosition getSelectionStartPosition();
155
156   /**
157    * Returns the end offset in the document of the selected text range, or the caret
158    * position if there is currently no selection.
159    *
160    * @return the selection end offset.
161    */
162   int getSelectionEnd();
163
164   /**
165    * @return    object that encapsulates information about visual position of selected text end if any;
166    */
167   @NotNull
168   VisualPosition getSelectionEndPosition();
169
170   /**
171    * Returns the text selected in the editor.
172    *
173    * @return the selected text, or null if there is currently no selection.
174    */
175   @Nullable
176   String getSelectedText();
177
178   /**
179    * Returns the offset from which the user started to extend the selection (the selection start
180    * if the selection was extended in forward direction, or the selection end if it was
181    * extended backward).
182    *
183    * @return the offset from which the selection was started, or the caret offset if there is
184    *         currently no selection.
185    */
186   int getLeadSelectionOffset();
187
188   /**
189    * @return    object that encapsulates information about visual position from which the user started to extend the selection if any
190    */
191   @NotNull
192   VisualPosition getLeadSelectionPosition();
193
194   /**
195    * Checks if a range of text is currently selected.
196    *
197    * @return true if a range of text is selected, false otherwise.
198    */
199   boolean hasSelection();
200
201   /**
202    * Selects the specified range of text.
203    * <p>
204    * System selection will be updated, if such feature is supported by current editor.
205    *
206    * @param startOffset the start offset of the text range to select.
207    * @param endOffset   the end offset of the text range to select.
208    */
209   void setSelection(int startOffset, int endOffset);
210
211   /**
212    * Selects the specified range of text.
213    *
214    * @param startOffset the start offset of the text range to select.
215    * @param endOffset   the end offset of the text range to select.
216    * @param updateSystemSelection whether system selection should be updated (might not have any effect if current editor doesn't support such a feature)
217    */
218   void setSelection(int startOffset, int endOffset, boolean updateSystemSelection);
219
220   /**
221    * Selects target range providing information about visual boundary of selection end.
222    * <p/>
223    * That is the case for soft wraps-aware processing where the whole soft wraps virtual space is matched to the same offset.
224    * <p/>
225    * Also, in column mode this method allows to create selection spanning virtual space after the line end.
226    * <p>
227    * System selection will be updated, if such feature is supported by current editor.
228    *
229    * @param startOffset     start selection offset
230    * @param endPosition     end visual position of the text range to select (<code>null</code> argument means that
231    *                        no specific visual position should be used)
232    * @param endOffset       end selection offset
233    */
234   void setSelection(int startOffset, @Nullable VisualPosition endPosition, int endOffset);
235
236   /**
237    * Selects target range based on its visual boundaries.
238    * <p/>
239    * That is the case for soft wraps-aware processing where the whole soft wraps virtual space is matched to the same offset.
240    * <p/>
241    * Also, in column mode this method allows to create selection spanning virtual space after the line end.
242    * <p>
243    * System selection will be updated, if such feature is supported by current editor.
244    *
245    * @param startPosition   start visual position of the text range to select (<code>null</code> argument means that
246    *                        no specific visual position should be used)
247    * @param endPosition     end visual position of the text range to select (<code>null</code> argument means that
248    *                        no specific visual position should be used)
249    * @param startOffset     start selection offset
250    * @param endOffset       end selection offset
251    */
252   void setSelection(@Nullable VisualPosition startPosition, int startOffset, @Nullable VisualPosition endPosition, int endOffset);
253
254   /**
255    * Selects target range based on its visual boundaries.
256    * <p/>
257    * That is the case for soft wraps-aware processing where the whole soft wraps virtual space is matched to the same offset.
258    * <p/>
259    * Also, in column mode this method allows to create selection spanning virtual space after the line end.
260    *
261    * @param startPosition   start visual position of the text range to select (<code>null</code> argument means that
262    *                        no specific visual position should be used)
263    * @param endPosition     end visual position of the text range to select (<code>null</code> argument means that
264    *                        no specific visual position should be used)
265    * @param startOffset     start selection offset
266    * @param endOffset       end selection offset
267    * @param updateSystemSelection whether system selection should be updated (might not have any effect if current editor doesn't support such a feature)
268    */
269   void setSelection(@Nullable VisualPosition startPosition, int startOffset, @Nullable VisualPosition endPosition, int endOffset, boolean updateSystemSelection);
270
271   /**
272    * Removes the selection in the editor.
273    */
274   void removeSelection();
275
276   /**
277    * Selects the entire line of text at the caret position.
278    */
279   void selectLineAtCaret();
280
281   /**
282    * Selects the entire word at the caret position, optionally using camel-case rules to
283    * determine word boundaries.
284    *
285    * @param honorCamelWordsSettings if true and "Use CamelHumps words" is enabled,
286    *                                upper-case letters within the word are considered as
287    *                                boundaries for the range of text to select.
288    */
289   void selectWordAtCaret(boolean honorCamelWordsSettings);
290
291   /**
292    * Clones the current caret and positions the new one right above or below the current one. If current caret has selection, corresponding
293    * selection will be set for the new caret.
294    *
295    * @param above if <code>true</code>, new caret will be created at the previous line, if <code>false</code> - on the next line
296    * @return newly created caret instance, or <code>null</code> if the caret cannot be created because it already exists at the new location
297    * or caret model doesn't support multiple carets.
298    */
299   @Nullable
300   Caret clone(boolean above);
301
302   /**
303    * Returns <code>true</code> if caret is located in RTL text fragment. In that case visual column number is inversely related
304    * to offset and logical column number in the vicinity of caret.
305    */
306   boolean isAtRtlLocation();
307
308   /**
309    * Returns <code>true</code> if caret is located at a boundary between different runs of bidirectional text. 
310    * This means that text fragments at different sides of the boundary are non-adjacent in logical order.
311    * Caret can located at any side of the boundary, 
312    * exact location can be determined from directionality flags of caret's logical and visual position 
313    * ({@link LogicalPosition#leansForward} and {@link VisualPosition#leansRight}).
314    */
315   boolean isAtBidiRunBoundary();
316 }