c7729e9aeb8e256415303871ddc5a47842078e0b
[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  * <p>
27  * Instances of this interface are supposed to be obtained from {@link CaretModel} instance, and not created explicitly.
28  */
29 public interface Caret extends UserDataHolderEx, Disposable {
30   /**
31    * Returns an instance of Editor, current caret belongs to.
32    */
33   @NotNull
34   Editor getEditor();
35
36   /**
37    * Returns an instance of CaretModel, current caret is associated with.
38    */
39   @NotNull
40   CaretModel getCaretModel();
41
42   /**
43    * Tells whether this caret is valid, i.e. recognized by the caret model currently. Caret is valid since its creation till its
44    * removal from caret model.
45    *
46    * @see CaretModel#addCaret(VisualPosition)
47    * @see CaretModel#removeCaret(Caret)
48    */
49   boolean isValid();
50
51   /**
52    * Moves the caret by the specified number of lines and/or columns.
53    *
54    * @param columnShift    the number of columns to move the caret by.
55    * @param lineShift      the number of lines to move the caret by.
56    * @param withSelection  if true, the caret move should extend the selection in the document.
57    * @param scrollToCaret  if true, the document should be scrolled so that the caret is visible after the move.
58    */
59   void moveCaretRelatively(int columnShift,
60                            int lineShift,
61                            boolean withSelection,
62                            boolean scrollToCaret);
63
64   /**
65    * Moves the caret to the specified logical position.
66    * If corresponding position is in the folded region currently, the region will be expanded.
67    *
68    * @param pos the position to move to.
69    */
70   void moveToLogicalPosition(@NotNull LogicalPosition pos);
71
72   /**
73    * Moves the caret to the specified visual position.
74    *
75    * @param pos the position to move to.
76    */
77   void moveToVisualPosition(@NotNull VisualPosition pos);
78
79   /**
80    * Short hand for calling {@link #moveToOffset(int, boolean)} with <code>'false'</code> as a second argument.
81    *
82    * @param offset      the offset to move to
83    */
84   void moveToOffset(int offset);
85
86   /**
87    * Moves the caret to the specified offset in the document.
88    * If corresponding position is in the folded region currently, the region will be expanded.
89    *
90    * @param offset                  the offset to move to.
91    * @param locateBeforeSoftWrap    there is a possible case that there is a soft wrap at the given offset, hence, the same offset
92    *                                corresponds to two different visual positions - just before soft wrap and just after soft wrap.
93    *                                We may want to clearly indicate where to put the caret then. Given parameter allows to do that.
94    *                                <b>Note:</b> it's ignored if there is no soft wrap at the given offset
95    */
96   void moveToOffset(int offset, boolean locateBeforeSoftWrap);
97
98   /**
99    * Caret position may be updated on document change (e.g. consider that user updates from VCS that causes addition of text
100    * before caret. Caret offset, visual and logical positions should be updated then). So, there is a possible case
101    * that caret model in in the process of caret position update now.
102    * <p/>
103    * Current method allows to check that.
104    *
105    * @return    <code>true</code> if caret position is up-to-date for now; <code>false</code> otherwise
106    */
107   boolean isUpToDate();
108
109   /**
110    * Returns the logical position of the caret.
111    *
112    * @return the caret position.
113    */
114   @NotNull
115   LogicalPosition getLogicalPosition();
116
117   /**
118    * Returns the visual position of the caret.
119    *
120    * @return the caret position.
121    */
122   @NotNull
123   VisualPosition getVisualPosition();
124
125   /**
126    * Returns the offset of the caret in the document. Returns 0 for a disposed (invalid) caret.
127    *
128    * @return the caret offset.
129    *
130    * @see #isValid()
131    */
132   int getOffset();
133
134   /**
135    * @return    document offset for the start of the logical line where caret is located
136    */
137   int getVisualLineStart();
138
139   /**
140    * @return    document offset that points to the first symbol shown at the next visual line after the one with caret on it
141    */
142   int getVisualLineEnd();
143
144   /**
145    * Returns the start offset in the document of the selected text range, or the caret
146    * position if there is currently no selection.
147    *
148    * @return the selection start offset.
149    */
150   int getSelectionStart();
151
152   /**
153    * @return    object that encapsulates information about visual position of selected text start if any
154    */
155   @NotNull
156   VisualPosition getSelectionStartPosition();
157
158   /**
159    * Returns the end offset in the document of the selected text range, or the caret
160    * position if there is currently no selection.
161    *
162    * @return the selection end offset.
163    */
164   int getSelectionEnd();
165
166   /**
167    * @return    object that encapsulates information about visual position of selected text end if any;
168    */
169   @NotNull
170   VisualPosition getSelectionEndPosition();
171
172   /**
173    * Returns the text selected in the editor.
174    *
175    * @return the selected text, or null if there is currently no selection.
176    */
177   @Nullable
178   String getSelectedText();
179
180   /**
181    * Returns the offset from which the user started to extend the selection (the selection start
182    * if the selection was extended in forward direction, or the selection end if it was
183    * extended backward).
184    *
185    * @return the offset from which the selection was started, or the caret offset if there is
186    *         currently no selection.
187    */
188   int getLeadSelectionOffset();
189
190   /**
191    * @return    object that encapsulates information about visual position from which the user started to extend the selection if any
192    */
193   @NotNull
194   VisualPosition getLeadSelectionPosition();
195
196   /**
197    * Checks if a range of text is currently selected.
198    *
199    * @return true if a range of text is selected, false otherwise.
200    */
201   boolean hasSelection();
202
203   /**
204    * Selects the specified range of text.
205    * <p>
206    * System selection will be updated, if such feature is supported by current editor.
207    *
208    * @param startOffset the start offset of the text range to select.
209    * @param endOffset   the end offset of the text range to select.
210    */
211   void setSelection(int startOffset, int endOffset);
212
213   /**
214    * Selects the specified range of text.
215    *
216    * @param startOffset the start offset of the text range to select.
217    * @param endOffset   the end offset of the text range to select.
218    * @param updateSystemSelection whether system selection should be updated (might not have any effect if current editor doesn't support such a feature)
219    */
220   void setSelection(int startOffset, int endOffset, boolean updateSystemSelection);
221
222   /**
223    * Selects target range providing information about visual boundary of selection end.
224    * <p/>
225    * That is the case for soft wraps-aware processing where the whole soft wraps virtual space is matched to the same offset.
226    * <p/>
227    * Also, in column mode this method allows to create selection spanning virtual space after the line end.
228    * <p>
229    * System selection will be updated, if such feature is supported by current editor.
230    *
231    * @param startOffset     start selection offset
232    * @param endPosition     end visual position of the text range to select (<code>null</code> argument means that
233    *                        no specific visual position should be used)
234    * @param endOffset       end selection offset
235    */
236   void setSelection(int startOffset, @Nullable VisualPosition endPosition, int endOffset);
237
238   /**
239    * Selects target range based on its visual boundaries.
240    * <p/>
241    * That is the case for soft wraps-aware processing where the whole soft wraps virtual space is matched to the same offset.
242    * <p/>
243    * Also, in column mode this method allows to create selection spanning virtual space after the line end.
244    * <p>
245    * System selection will be updated, if such feature is supported by current editor.
246    *
247    * @param startPosition   start visual position of the text range to select (<code>null</code> argument means that
248    *                        no specific visual position should be used)
249    * @param endPosition     end visual position of the text range to select (<code>null</code> argument means that
250    *                        no specific visual position should be used)
251    * @param startOffset     start selection offset
252    * @param endOffset       end selection offset
253    */
254   void setSelection(@Nullable VisualPosition startPosition, int startOffset, @Nullable VisualPosition endPosition, int endOffset);
255
256   /**
257    * Selects target range based on its visual boundaries.
258    * <p/>
259    * That is the case for soft wraps-aware processing where the whole soft wraps virtual space is matched to the same offset.
260    * <p/>
261    * Also, in column mode this method allows to create selection spanning virtual space after the line end.
262    *
263    * @param startPosition   start visual position of the text range to select (<code>null</code> argument means that
264    *                        no specific visual position should be used)
265    * @param endPosition     end visual position of the text range to select (<code>null</code> argument means that
266    *                        no specific visual position should be used)
267    * @param startOffset     start selection offset
268    * @param endOffset       end selection offset
269    * @param updateSystemSelection whether system selection should be updated (might not have any effect if current editor doesn't support such a feature)
270    */
271   void setSelection(@Nullable VisualPosition startPosition, int startOffset, @Nullable VisualPosition endPosition, int endOffset, boolean updateSystemSelection);
272
273   /**
274    * Removes the selection in the editor.
275    */
276   void removeSelection();
277
278   /**
279    * Selects the entire line of text at the caret position.
280    */
281   void selectLineAtCaret();
282
283   /**
284    * Selects the entire word at the caret position, optionally using camel-case rules to
285    * determine word boundaries.
286    *
287    * @param honorCamelWordsSettings if true and "Use CamelHumps words" is enabled,
288    *                                upper-case letters within the word are considered as
289    *                                boundaries for the range of text to select.
290    */
291   void selectWordAtCaret(boolean honorCamelWordsSettings);
292
293   /**
294    * Clones the current caret and positions the new one right above or below the current one. If current caret has selection, corresponding
295    * selection will be set for the new caret.
296    *
297    * @param above if <code>true</code>, new caret will be created at the previous line, if <code>false</code> - on the next line
298    * @return newly created caret instance, or <code>null</code> if the caret cannot be created because it already exists at the new location
299    * or caret model doesn't support multiple carets.
300    */
301   @Nullable
302   Caret clone(boolean above);
303
304   /**
305    * Returns <code>true</code> if caret is located in RTL text fragment. In that case visual column number is inversely related
306    * to offset and logical column number in the vicinity of caret.
307    */
308   boolean isAtRtlLocation();
309
310   /**
311    * Returns <code>true</code> if caret is located at a boundary between different runs of bidirectional text. 
312    * This means that text fragments at different sides of the boundary are non-adjacent in logical order.
313    * Caret can located at any side of the boundary, 
314    * exact location can be determined from directionality flags of caret's logical and visual position 
315    * ({@link LogicalPosition#leansForward} and {@link VisualPosition#leansRight}).
316    */
317   boolean isAtBidiRunBoundary();
318
319   /**
320    * Returns visual attributes currently set for the caret.
321    *
322    * @see #setVisualAttributes(CaretVisualAttributes)
323    */
324   @NotNull
325   CaretVisualAttributes getVisualAttributes();
326
327   /**
328    * Sets caret's current visual attributes. This can have no effect if editor doesn't support changing caret's visual appearance.
329    *
330    * @see #getVisualAttributes()
331    */
332   void setVisualAttributes(@NotNull CaretVisualAttributes attributes);
333 }