replaced <code></code> with more concise {@code}
[idea/community.git] / platform / editor-ui-api / src / com / intellij / openapi / editor / SelectionModel.java
1 /*
2  * Copyright 2000-2014 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.editor.event.SelectionListener;
19 import com.intellij.openapi.editor.markup.TextAttributes;
20 import org.jetbrains.annotations.NotNull;
21 import org.jetbrains.annotations.Nullable;
22
23 /**
24  * Provides services for selecting text in the IDEA text editor and retrieving information about the selection. 
25  * Most of the methods here exist for compatibility reasons, corresponding functionality is also provided by {@link CaretModel} now.
26  * <p>
27  * In editor supporting multiple carets, each caret has its own associated selection range. Unless mentioned explicitly, methods of this 
28  * interface operate on the current caret (see {@link CaretModel#runForEachCaret(CaretAction)}), or 'primary' caret if current caret 
29  * is not defined. 
30  *
31  * @see Editor#getSelectionModel()
32  * @see CaretModel
33  */
34 public interface SelectionModel {
35   /**
36    * Returns the start offset in the document of the selected text range, or the caret
37    * position if there is currently no selection.
38    *
39    * @return the selection start offset.
40    */
41   int getSelectionStart();
42
43   /**
44    * @return    object that encapsulates information about visual position of selected text start if any
45    */
46   @Nullable
47   VisualPosition getSelectionStartPosition();
48
49   /**
50    * Returns the end offset in the document of the selected text range, or the caret
51    * position if there is currently no selection.
52    *
53    * @return the selection end offset.
54    */
55   int getSelectionEnd();
56
57   /**
58    * @return    object that encapsulates information about visual position of selected text end if any;
59    */
60   @Nullable
61   VisualPosition getSelectionEndPosition();
62
63   /**
64    * Returns the text selected in the editor.
65    *
66    * @return the selected text, or null if there is currently no selection.
67    */
68   @Nullable
69   String getSelectedText();
70
71   /**
72    * If {@code allCarets} is {@code true}, returns the concatenation of selections for all carets, or {@code null} if there
73    * are no selections. If {@code allCarets} is {@code false}, works just like {@link #getSelectedText}.
74    */
75   @Nullable
76   String getSelectedText(boolean allCarets);
77
78   /**
79    * Returns the offset from which the user started to extend the selection (the selection start
80    * if the selection was extended in forward direction, or the selection end if it was
81    * extended backward).
82    *
83    * @return the offset from which the selection was started, or the caret offset if there is
84    *         currently no selection.
85    */
86   int getLeadSelectionOffset();
87
88   /**
89    * @return    object that encapsulates information about visual position from which the user started to extend the selection if any
90    */
91   @Nullable
92   VisualPosition getLeadSelectionPosition();
93
94   /**
95    * Checks if a range of text is currently selected.
96    *
97    * @return true if a range of text is selected, false otherwise.
98    */
99   boolean hasSelection();
100
101   /**
102    * Checks if a range of text is currently selected. If {@code anyCaret} is {@code true}, check all existing carets in
103    * the document, and returns {@code true} if any of them has selection, otherwise checks only the current caret.
104    *
105    * @return true if a range of text is selected, false otherwise.
106    */
107   boolean hasSelection(boolean anyCaret);
108
109   /**
110    * Selects the specified range of text.
111    *
112    * @param startOffset the start offset of the text range to select.
113    * @param endOffset   the end offset of the text range to select.
114    */
115   void setSelection(int startOffset, int endOffset);
116
117   /**
118    * Selects target range providing information about visual boundary of selection end.
119    * <p/>
120    * That is the case for soft wraps-aware processing where the whole soft wraps virtual space is matched to the same offset.
121    *
122    * @param startOffset     start selection offset
123    * @param endPosition     end visual position of the text range to select ({@code null} argument means that
124    *                        no specific visual position should be used)
125    * @param endOffset       end selection offset
126    */
127   void setSelection(int startOffset, @Nullable VisualPosition endPosition, int endOffset);
128
129   /**
130    * Selects target range based on its visual boundaries.
131    * <p/>
132    * That is the case for soft wraps-aware processing where the whole soft wraps virtual space is matched to the same offset.
133    *
134    * @param startPosition   start visual position of the text range to select ({@code null} argument means that
135    *                        no specific visual position should be used)
136    * @param endPosition     end visual position of the text range to select ({@code null} argument means that
137    *                        no specific visual position should be used)
138    * @param startOffset     start selection offset
139    * @param endOffset       end selection offset
140    */
141   void setSelection(@Nullable VisualPosition startPosition, int startOffset, @Nullable VisualPosition endPosition, int endOffset);
142
143   /**
144    * Removes the selection in the editor.
145    */
146   void removeSelection();
147
148   /**
149    * Removes the selection in the editor. If {@code allCarets} is {@code true}, removes selections from all carets in the
150    * editor, otherwise, does this just for the current caret.
151    */
152   void removeSelection(boolean allCarets);
153
154   /**
155    * Adds a listener for receiving information about selection changes.
156    *
157    * @param listener the listener instance.
158    */
159   void addSelectionListener(SelectionListener listener);
160
161   /**
162    * Removes a listener for receiving information about selection changes.
163    *
164    * @param listener the listener instance.
165    */
166   void removeSelectionListener(SelectionListener listener);
167
168   /**
169    * Selects the entire line of text at the caret position.
170    */
171   void selectLineAtCaret();
172
173   /**
174    * Selects the entire word at the caret position, optionally using camel-case rules to
175    * determine word boundaries.
176    *
177    * @param honorCamelWordsSettings if true and "Use CamelHumps words" is enabled,
178    *                                upper-case letters within the word are considered as
179    *                                boundaries for the range of text to select.
180    */
181   void selectWordAtCaret(boolean honorCamelWordsSettings);
182
183   /**
184    * Copies the currently selected text to the clipboard.
185    *
186    * When multiple selections exist in the document, all of them are copied, as a single piece of text.
187    */
188   void copySelectionToClipboard();
189
190   /**
191    * Creates a multi-caret selection for the rectangular block of text with specified start and end positions.
192    *
193    * @param blockStart the start of the rectangle to select.
194    * @param blockEnd   the end of the rectangle to select.
195    * @see #setSelection(int, int)
196    */
197   void setBlockSelection(@NotNull LogicalPosition blockStart, @NotNull LogicalPosition blockEnd);
198
199   /**
200    * Returns an array of start offsets in the document for ranges selected in the document currently. Works both for a single-caret and
201    * a multiple-caret selection (for carets not having a selection, caret position is returned).
202    *
203    * @return an array of start offsets, array size is equal to the number of carets existing in the editor currently.
204    */
205   @NotNull
206   int[] getBlockSelectionStarts();
207
208   /**
209    * Returns an array of end offsets in the document for ranges selected in the document currently. Works both for a single-caret and
210    * a multiple-caret selection (for carets not having a selection, caret position is returned).
211    *
212    * @return an array of start offsets, array size is equal to the number of carets existing in the editor currently.
213    */
214   @NotNull
215   int[] getBlockSelectionEnds();
216
217   /**
218    * Returns visual representation of selection.
219    *
220    * @return Selection attributes.
221    */
222   TextAttributes getTextAttributes();
223 }