cleanup
[idea/community.git] / platform / platform-api / src / com / intellij / openapi / fileEditor / FileEditorManager.java
1 // Copyright 2000-2020 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license that can be found in the LICENSE file.
2 package com.intellij.openapi.fileEditor;
3
4 import com.intellij.openapi.Disposable;
5 import com.intellij.openapi.editor.Caret;
6 import com.intellij.openapi.editor.Editor;
7 import com.intellij.openapi.project.Project;
8 import com.intellij.openapi.util.Key;
9 import com.intellij.openapi.vfs.VirtualFile;
10 import org.jetbrains.annotations.ApiStatus;
11 import org.jetbrains.annotations.NotNull;
12 import org.jetbrains.annotations.Nullable;
13
14 import javax.swing.*;
15 import java.util.List;
16
17 public abstract class FileEditorManager {
18   public static final Key<Boolean> USE_CURRENT_WINDOW = Key.create("OpenFile.searchForOpen");
19
20   public static FileEditorManager getInstance(@NotNull Project project) {
21     return project.getComponent(FileEditorManager.class);
22   }
23
24   /**
25    * @param file file to open. File should be valid.
26    *             Must be called from <a href="https://docs.oracle.com/javase/tutorial/uiswing/concurrency/dispatch.html">EDT</a>.
27    * @return array of opened editors
28    */
29   public abstract FileEditor @NotNull [] openFile(@NotNull VirtualFile file, boolean focusEditor);
30
31
32   /**
33    * Opens a file.
34    * Must be called from <a href="https://docs.oracle.com/javase/tutorial/uiswing/concurrency/dispatch.html">EDT</a>.
35    *
36    * @param file        file to open
37    * @param focusEditor {@code true} if need to focus
38    * @return array of opened editors
39    */
40   public FileEditor @NotNull [] openFile(@NotNull VirtualFile file, boolean focusEditor, boolean searchForOpen) {
41     throw new UnsupportedOperationException("Not implemented");
42   }
43
44   /**
45    * Closes all editors opened for the file.
46    * Must be called from <a href="https://docs.oracle.com/javase/tutorial/uiswing/concurrency/dispatch.html">EDT</a>.
47    *
48    * @param file file to be closed.
49    */
50   public abstract void closeFile(@NotNull VirtualFile file);
51
52   /**
53    * Works as {@link #openFile(VirtualFile, boolean)} but forces opening of text editor (see {@link TextEditor}).
54    * If several text editors are opened, including the default one, default text editor is focused (if requested) and returned.
55    * Must be called from <a href="https://docs.oracle.com/javase/tutorial/uiswing/concurrency/dispatch.html">EDT</a>.
56    *
57    * @return opened text editor. The method returns {@code null} in case if text editor wasn't opened.
58    */
59   public abstract @Nullable Editor openTextEditor(@NotNull OpenFileDescriptor descriptor, boolean focusEditor);
60
61   /**
62    * @deprecated use {@link #openTextEditor(OpenFileDescriptor, boolean)}
63    */
64   @Deprecated
65   public void navigateToTextEditor(@NotNull OpenFileDescriptor descriptor, boolean focusEditor) {
66     openTextEditor(descriptor, focusEditor);
67   }
68
69   /**
70    * @return currently selected text editor. The method returns {@code null} in case
71    * there is no selected editor at all or selected editor is not a text one.
72    * Must be called from <a href="https://docs.oracle.com/javase/tutorial/uiswing/concurrency/dispatch.html">EDT</a>.
73    */
74   public abstract @Nullable Editor getSelectedTextEditor();
75
76   /**
77    * @return currently selected TEXT editors including ones which were opened by guests during a collaborative development session
78    * The method returns an empty array in case there are no selected editors or none of them is a text one.
79    * Must be called from <a href="https://docs.oracle.com/javase/tutorial/uiswing/concurrency/dispatch.html">EDT</a>.
80    */
81   @ApiStatus.Experimental
82   public Editor @NotNull [] getSelectedTextEditorWithRemotes() {
83     Editor editor = getSelectedTextEditor();
84     return editor != null ? new Editor[]{editor} : Editor.EMPTY_ARRAY;
85   }
86
87   /**
88    * @return {@code true} if {@code file} is opened, {@code false} otherwise
89    */
90   public abstract boolean isFileOpen(@NotNull VirtualFile file);
91
92   /**
93    * @return all opened files. Order of files in the array corresponds to the order of editor tabs.
94    */
95   public abstract VirtualFile @NotNull [] getOpenFiles();
96
97   public boolean hasOpenFiles() {
98     return getOpenFiles().length > 0;
99   }
100
101   /**
102    * @return files currently selected. The method returns empty array if there are no selected files.
103    * If more than one file is selected (split), the file with most recent focused editor is returned first.
104    */
105   public abstract VirtualFile @NotNull [] getSelectedFiles();
106
107   /**
108    * @return editors currently selected. The method returns empty array if no editors are open.
109    */
110   public abstract FileEditor @NotNull [] getSelectedEditors();
111
112   /**
113    * @return editors currently selected including ones which were opened by guests during a collaborative development session
114    * The method returns an empty array if no editors are open.
115    */
116   @ApiStatus.Experimental
117   public FileEditor @NotNull [] getSelectedEditorWithRemotes() {
118     return getSelectedEditors();
119   }
120
121   /**
122    * @return currently selected file editor or {@code null} if there is no selected editor at all.
123    */
124   public @Nullable FileEditor getSelectedEditor() {
125     VirtualFile[] files = getSelectedFiles();
126     return files.length == 0 ? null : getSelectedEditor(files[0]);
127   }
128
129   /**
130    * @return editor which is currently selected for given file.
131    * The method returns {@code null} if {@code file} is not opened.
132    */
133   public abstract @Nullable FileEditor getSelectedEditor(@NotNull VirtualFile file);
134
135   /**
136    * @return current editors for the specified {@code file}
137    */
138   public abstract FileEditor @NotNull [] getEditors(@NotNull VirtualFile file);
139
140   /**
141    * @return all editors for the specified {@code file}
142    */
143   public abstract FileEditor @NotNull [] getAllEditors(@NotNull VirtualFile file);
144
145   /**
146    * @return all open editors
147    */
148   public abstract FileEditor @NotNull [] getAllEditors();
149
150   /**
151    * Adds the specified component above the editor and paints a separator line below it.
152    * If a separator line is not needed, set the client property to {@code true}:
153    * <pre>    component.putClientProperty(SEPARATOR_DISABLED, true);    </pre>
154    * Otherwise, a separator line will be painted by a
155    * {@link com.intellij.openapi.editor.colors.EditorColors#SEPARATOR_ABOVE_COLOR SEPARATOR_ABOVE_COLOR} or
156    * {@link com.intellij.openapi.editor.colors.EditorColors#TEARLINE_COLOR TEARLINE_COLOR} if it is not set.
157    * <p>
158    * This method allows to add several components above the editor.
159    * To change an order of components the specified component may implement the
160    * {@link com.intellij.openapi.util.Weighted Weighted} interface.
161    */
162   public abstract void addTopComponent(final @NotNull FileEditor editor, final @NotNull JComponent component);
163
164   public abstract void removeTopComponent(final @NotNull FileEditor editor, final @NotNull JComponent component);
165
166   /**
167    * Adds the specified component below the editor and paints a separator line above it.
168    * If a separator line is not needed, set the client property to {@code true}:
169    * <pre>    component.putClientProperty(SEPARATOR_DISABLED, true);    </pre>
170    * Otherwise, a separator line will be painted by a
171    * {@link com.intellij.openapi.editor.colors.EditorColors#SEPARATOR_BELOW_COLOR SEPARATOR_BELOW_COLOR} or
172    * {@link com.intellij.openapi.editor.colors.EditorColors#TEARLINE_COLOR TEARLINE_COLOR} if it is not set.
173    * <p>
174    * This method allows to add several components below the editor.
175    * To change an order of components the specified component may implement the
176    * {@link com.intellij.openapi.util.Weighted Weighted} interface.
177    */
178   public abstract void addBottomComponent(final @NotNull FileEditor editor, final @NotNull JComponent component);
179
180   public abstract void removeBottomComponent(final @NotNull FileEditor editor, final @NotNull JComponent component);
181
182   public static final Key<Boolean> SEPARATOR_DISABLED = Key.create("FileEditorSeparatorDisabled");
183
184   /**
185    * Adds specified {@code listener}
186    *
187    * @param listener listener to be added
188    * @deprecated Use {@link com.intellij.util.messages.MessageBus} instead: see {@link FileEditorManagerListener#FILE_EDITOR_MANAGER}
189    */
190   @Deprecated
191   public void addFileEditorManagerListener(@NotNull FileEditorManagerListener listener) {
192   }
193
194   /**
195    * @deprecated Use {@link FileEditorManagerListener#FILE_EDITOR_MANAGER} instead
196    */
197   @Deprecated
198   public void addFileEditorManagerListener(@NotNull FileEditorManagerListener listener, @NotNull Disposable parentDisposable) {
199   }
200
201   /**
202    * Removes specified {@code listener}
203    *
204    * @param listener listener to be removed
205    * @deprecated Use {@link FileEditorManagerListener#FILE_EDITOR_MANAGER} instead
206    */
207   @Deprecated
208   public void removeFileEditorManagerListener(@NotNull FileEditorManagerListener listener) {
209   }
210
211   /**
212    * Must be called from <a href="https://docs.oracle.com/javase/tutorial/uiswing/concurrency/dispatch.html">EDT</a>.
213    *
214    * @return opened file editors
215    */
216   public abstract @NotNull List<FileEditor> openEditor(@NotNull OpenFileDescriptor descriptor, boolean focusEditor);
217
218   /**
219    * Returns the project with which the file editor manager is associated.
220    *
221    * @return the project instance.
222    */
223   public abstract @NotNull Project getProject();
224
225   public abstract void registerExtraEditorDataProvider(@NotNull EditorDataProvider provider, Disposable parentDisposable);
226
227   /**
228    * Returns data associated with given editor/caret context. Data providers are registered via
229    * {@link #registerExtraEditorDataProvider(EditorDataProvider, Disposable)} method.
230    */
231   public abstract @Nullable Object getData(@NotNull String dataId, @NotNull Editor editor, @NotNull Caret caret);
232
233   /**
234    * Selects a specified file editor tab for the specified editor.
235    *
236    * @param file                 a file to switch the file editor tab for. The function does nothing if the file is not currently open in the editor.
237    * @param fileEditorProviderId the ID of the file editor to open; matches the return value of
238    *                             {@link FileEditorProvider#getEditorTypeId()}
239    */
240   public abstract void setSelectedEditor(@NotNull VirtualFile file, @NotNull String fileEditorProviderId);
241
242   /**
243    * {@link FileEditorManager} supports asynchronous opening of text editors, i.e. when one of 'openFile' methods returns, returned
244    * editor might not be fully initialized yet. This method allows to delay (if needed) execution of given runnable until editor is
245    * fully loaded.
246    */
247   public abstract void runWhenLoaded(@NotNull Editor editor, @NotNull Runnable runnable);
248 }