da846e50b9888c6b0d37d3ee77a37610b3e65a37
[idea/community.git] / platform / editor-ui-api / src / com / intellij / openapi / editor / Editor.java
1 /*
2  * Copyright 2000-2017 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.actionSystem.DataProvider;
19 import com.intellij.openapi.editor.colors.EditorColorsScheme;
20 import com.intellij.openapi.editor.event.EditorMouseEventArea;
21 import com.intellij.openapi.editor.event.EditorMouseListener;
22 import com.intellij.openapi.editor.event.EditorMouseMotionListener;
23 import com.intellij.openapi.editor.markup.MarkupModel;
24 import com.intellij.openapi.project.Project;
25 import com.intellij.openapi.util.UserDataHolder;
26 import org.jetbrains.annotations.NotNull;
27 import org.jetbrains.annotations.Nullable;
28
29 import javax.swing.*;
30 import javax.swing.border.Border;
31 import java.awt.*;
32 import java.awt.event.MouseEvent;
33 import java.awt.geom.Point2D;
34
35 /**
36  * Represents an instance of the IDEA text editor.
37  *
38  * @see EditorFactory#createEditor(Document)
39  * @see EditorFactory#createViewer(Document)
40  */
41 public interface Editor extends UserDataHolder {
42   Editor[] EMPTY_ARRAY = new Editor[0];
43
44   /**
45    * Returns the document edited or viewed in the editor.
46    *
47    * @return the document instance.
48    */
49   @NotNull
50   Document getDocument();
51
52   /**
53    * Returns the value indicating whether the editor operates in viewer mode, with
54    * all modification actions disabled.
55    *
56    * @return true if the editor works as a viewer, false otherwise
57    */
58   boolean isViewer();
59
60   /**
61    * Returns the component for the entire editor including the scrollbars, error stripe, gutter
62    * and other decorations. The component can be used, for example, for converting logical to
63    * screen coordinates.
64    *
65    * @return the component instance.
66    */
67   @NotNull
68   JComponent getComponent();
69
70   /**
71    * Returns the component for the content area of the editor (the area displaying the document text).
72    * The component can be used, for example, for converting logical to screen coordinates.
73    * The instance is implementing {@link DataProvider}
74    *
75    * @return the component instance.
76    */
77   @NotNull
78   JComponent getContentComponent();
79
80   void setBorder(@Nullable Border border);
81
82   Insets getInsets();
83
84   /**
85    * Returns the selection model for the editor, which can be used to select ranges of text in
86    * the document and retrieve information about the selection.
87    * <p>
88    * To query or change selections for specific carets, {@link CaretModel} interface should be used.
89    *
90    * @see #getCaretModel()
91    * 
92    * @return the selection model instance.
93    */
94   @NotNull
95   SelectionModel getSelectionModel();
96
97   /**
98    * Returns the markup model for the editor. This model contains editor-specific highlighters
99    * (for example, highlighters added by "Highlight usages in file"), which are painted in addition
100    * to the highlighters contained in the markup model for the document.
101    * <p>
102    * See also {@link com.intellij.openapi.editor.impl.DocumentMarkupModel.forDocument(Document, Project, boolean)}
103    *          {@link com.intellij.openapi.editor.ex.EditorEx#getFilteredDocumentMarkupModel()}.
104    *
105    * @return the markup model instance.
106    */
107   @NotNull
108   MarkupModel getMarkupModel();
109
110   /**
111    * Returns the folding model for the document, which can be used to add, remove, expand
112    * or collapse folded regions in the document.
113    *
114    * @return the folding model instance.
115    */
116   @NotNull
117   FoldingModel getFoldingModel();
118
119   /**
120    * Returns the scrolling model for the document, which can be used to scroll the document
121    * and retrieve information about the current position of the scrollbars.
122    *
123    * @return the scrolling model instance.
124    */
125   @NotNull
126   ScrollingModel getScrollingModel();
127
128   /**
129    * Returns the caret model for the document, which can be used to add and remove carets to the editor, as well as to query and update 
130    * carets' and corresponding selections' positions.
131    *
132    * @return the caret model instance.
133    */
134   @NotNull
135   CaretModel getCaretModel();
136
137   /**
138    * Returns the soft wrap model for the document, which can be used to get information about soft wraps registered
139    * for the editor document at the moment and provides basic management functions for them.
140    *
141    * @return the soft wrap model instance
142    */
143   @NotNull
144   SoftWrapModel getSoftWrapModel();
145
146   /**
147    * Returns the editor settings for this editor instance. Changes to these settings affect
148    * only the current editor instance.
149    *
150    * @return the settings instance.
151    */
152   @NotNull
153   EditorSettings getSettings();
154
155   /**
156    * Returns the editor color scheme for this editor instance. Changes to the scheme affect
157    * only the current editor instance.
158    *
159    * @return the color scheme instance.
160    */
161   @NotNull
162   EditorColorsScheme getColorsScheme();
163
164   /**
165    * Returns the height of a single line of text in the current editor font.
166    *
167    * @return the line height in pixels.
168    */
169   int getLineHeight();
170
171   /**
172    * Maps a logical position in the editor to pixel coordinates.
173    *
174    * @param pos the logical position.
175    * @return the coordinates relative to the top left corner of the {@link #getContentComponent() content component}.
176    */
177   @NotNull
178   Point logicalPositionToXY(@NotNull LogicalPosition pos);
179
180   /**
181    * Maps a logical position in the editor to the offset in the document.
182    *
183    * @param pos the logical position.
184    * @return the corresponding offset in the document.
185    */
186   int logicalPositionToOffset(@NotNull LogicalPosition pos);
187
188   /**
189    * Maps a logical position in the editor (the line and column ignoring folding) to
190    * a visual position (with folded lines and columns not included in the line and column count).
191    *
192    * @param logicalPos the logical position.
193    * @return the corresponding visual position.
194    */
195   @NotNull
196   VisualPosition logicalToVisualPosition(@NotNull LogicalPosition logicalPos);
197
198   /**
199    * Maps a visual position in the editor to pixel coordinates.
200    *
201    * @param visible the visual position.
202    * @return the coordinates relative to the top left corner of the {@link #getContentComponent() content component}.
203    */
204   @NotNull
205   Point visualPositionToXY(@NotNull VisualPosition visible);
206
207   /**
208    * Same as {@link #visualPositionToXY(VisualPosition)}, but returns potentially more precise result.
209    */
210   @NotNull
211   Point2D visualPositionToPoint2D(@NotNull VisualPosition pos);
212
213   /**
214    * Maps a visual position in the editor (with folded lines and columns not included in the line and column count) to
215    * a logical position (the line and column ignoring folding).
216    *
217    * @param visiblePos the visual position.
218    * @return the corresponding logical position.
219    */
220   @NotNull
221   LogicalPosition visualToLogicalPosition(@NotNull VisualPosition visiblePos);
222
223   /**
224    * Maps an offset in the document to a logical position.
225    * <p>
226    * It's assumed that original position is associated with character immediately preceding given offset, so target logical position will 
227    * have {@link LogicalPosition#leansForward leansForward} value set to <code>false</code>.
228    *
229    * @param offset the offset in the document.
230    * @return the corresponding logical position.
231    */
232   @NotNull
233   LogicalPosition offsetToLogicalPosition(int offset);
234
235   /**
236    * Maps an offset in the document to a visual position.
237    * <p>
238    * It's assumed that original position is associated with character immediately preceding given offset, 
239    * {@link VisualPosition#leansRight leansRight} value for visual position will be determined correspondingly.
240    * <p>
241    * If there's a soft wrap at given offset, visual position on a line following the wrap will be returned.
242    *
243    * @param offset the offset in the document.
244    * @return the corresponding visual position.
245    */
246   @NotNull
247   VisualPosition offsetToVisualPosition(int offset);
248
249   /**
250    * Maps an offset in the document to a visual position.
251    *
252    * @param offset the offset in the document.
253    * @param leanForward if <code>true</code>, original position is associated with character after given offset, if <code>false</code> - 
254    *                    with character before given offset. This can make a difference in bidirectional text (see {@link LogicalPosition},
255    *                    {@link VisualPosition})
256    * @param beforeSoftWrap if <code>true</code>, visual position at line preceeding the wrap will be returned, otherwise - visual position
257    *                       at line following the wrap.
258    * @return the corresponding visual position.
259    */
260   @NotNull
261   VisualPosition offsetToVisualPosition(int offset, boolean leanForward, boolean beforeSoftWrap);
262
263   /**
264    * Maps the pixel coordinates in the editor to a logical position.
265    *
266    * @param p the coordinates relative to the top left corner of the {@link #getContentComponent() content component}.
267    * @return the corresponding logical position.
268    */
269   @NotNull
270   LogicalPosition xyToLogicalPosition(@NotNull Point p);
271
272   /**
273    * Maps the pixel coordinates in the editor to a visual position.
274    *
275    * @param p the coordinates relative to the top left corner of the {@link #getContentComponent() content component}.
276    * @return the corresponding visual position.
277    */
278   @NotNull
279   VisualPosition xyToVisualPosition(@NotNull Point p);
280
281   /**
282    * Same as {{@link #xyToVisualPosition(Point)}}, but allows to specify target point with higher precision.
283    */
284   @NotNull
285   VisualPosition xyToVisualPosition(@NotNull Point2D p);
286
287   /**
288    * @since 2017.2
289    */
290   @NotNull
291   default Point offsetToXY(int offset) {
292     return offsetToXY(offset, false, false);
293   }
294
295   /**
296    * @see #offsetToVisualPosition(int, boolean, boolean)
297    * @since 2017.2
298    */
299   @NotNull
300   default Point offsetToXY(int offset, boolean leanForward, boolean beforeSoftWrap) {
301     VisualPosition visualPosition = offsetToVisualPosition(offset, leanForward, beforeSoftWrap);
302     return visualPositionToXY(visualPosition);
303   }
304
305   /**
306    * @since 2017.2
307    */
308   @NotNull
309   default Point2D offsetToPoint2D(int offset) {
310     return offsetToPoint2D(offset, false, false);
311   }
312
313   /**
314    * @see #offsetToVisualPosition(int, boolean, boolean)
315    * @since 2017.2
316    */
317   @NotNull
318   default Point2D offsetToPoint2D(int offset, boolean leanForward, boolean beforeSoftWrap) {
319     VisualPosition visualPosition = offsetToVisualPosition(offset, leanForward, beforeSoftWrap);
320     return visualPositionToPoint2D(visualPosition);
321   }
322
323   /**
324    * Adds a listener for receiving notifications about mouse clicks in the editor and
325    * the mouse entering/exiting the editor.
326    *
327    * @param listener the listener instance.
328    */
329   void addEditorMouseListener(@NotNull EditorMouseListener listener);
330
331   /**
332    * Removes a listener for receiving notifications about mouse clicks in the editor and
333    * the mouse entering/exiting the editor.
334    *
335    * @param listener the listener instance.
336    */
337   void removeEditorMouseListener(@NotNull EditorMouseListener listener);
338
339   /**
340    * Adds a listener for receiving notifications about mouse movement in the editor.
341    *
342    * @param listener the listener instance.
343    */
344   void addEditorMouseMotionListener(@NotNull EditorMouseMotionListener listener);
345
346   /**
347    * Removes a listener for receiving notifications about mouse movement in the editor.
348    *
349    * @param listener the listener instance.
350    */
351   void removeEditorMouseMotionListener(@NotNull EditorMouseMotionListener listener);
352
353   /**
354    * Checks if this editor instance has been disposed.
355    *
356    * @return true if the editor has been disposed, false otherwise.
357    */
358   boolean isDisposed();
359
360   /**
361    * Returns the project to which the editor is related.
362    *
363    * @return the project instance, or null if the editor is not related to any project.
364    */
365   @Nullable
366   Project getProject();
367
368   /**
369    * Returns the insert/overwrite mode for the editor.
370    *
371    * @return true if the editor is in insert mode, false otherwise.
372    */
373   boolean isInsertMode();
374
375   /**
376    * Returns the block selection mode for the editor.
377    *
378    * @return true if the editor uses column selection, false if it uses regular selection.
379    */
380   boolean isColumnMode();
381
382   /**
383    * Checks if the current editor instance is a one-line editor (used in a dialog control, for example).
384    *
385    * @return true if the editor is one-line, false otherwise.
386    */
387   boolean isOneLineMode();
388
389   /**
390    * Returns the gutter instance for the editor, which can be used to draw custom text annotations
391    * in the gutter.
392    *
393    * @return the gutter instance.
394    */
395   @NotNull
396   EditorGutter getGutter();
397
398   /**
399    * Returns the editor area (text, gutter, folding outline and so on) in which the specified
400    * mouse event occurred.
401    *
402    * @param e the mouse event for which the area is requested.
403    * @return the editor area, or null if the event occurred over an unknown area.
404    */
405   @Nullable
406   EditorMouseEventArea getMouseEventArea(@NotNull MouseEvent e);
407
408   /**
409    * Set up a header component for this text editor. Please note this is used for textual find feature so your component will most
410    * probably will be reset once the user presses Ctrl+F.
411    *
412    * @param header a component to setup as header for this text editor or <code>null</code> to remove one.
413    */
414   void setHeaderComponent(@Nullable JComponent header);
415
416   /**
417    * @return <code>true</code> if this editor has active header component set up by {@link #setHeaderComponent(JComponent)}
418    */
419   boolean hasHeaderComponent();
420
421   /**
422    * @return a component set by {@link #setHeaderComponent(JComponent)} or <code>null</code> if no header currently installed.
423    */
424   @Nullable
425   JComponent getHeaderComponent();
426
427   @NotNull
428   IndentsModel getIndentsModel();
429
430   @NotNull
431   InlayModel getInlayModel();
432
433   @NotNull
434   EditorKind getEditorKind();
435 }