mirror of
https://gitflic.ru/project/openide/openide.git
synced 2026-09-27 10:03:11 +07:00
File Editor and related classes docs polishing and links fixes
GitOrigin-RevId: eb3ba7c0b665d69ac59d73afac27c4fd197d7a1d
This commit is contained in:
Karol Lewandowski
committed by
intellij-monorepo-bot
intellij-monorepo-bot
parent
42615cdffd
commit
f41e0fedfa
@@ -1,4 +1,4 @@
|
||||
// Copyright 2000-2021 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.
|
||||
// Copyright 2000-2022 JetBrains s.r.o. and contributors. Use of this source code is governed by the Apache 2.0 license.
|
||||
package com.intellij.openapi.fileEditor;
|
||||
|
||||
import com.intellij.openapi.Disposable;
|
||||
@@ -32,7 +32,6 @@ public abstract class FileEditorManager {
|
||||
*/
|
||||
public abstract FileEditor @NotNull [] openFile(@NotNull VirtualFile file, boolean focusEditor);
|
||||
|
||||
|
||||
/**
|
||||
* Opens a file.
|
||||
* Must be called from <a href="https://docs.oracle.com/javase/tutorial/uiswing/concurrency/dispatch.html">EDT</a>.
|
||||
@@ -46,7 +45,7 @@ public abstract class FileEditorManager {
|
||||
}
|
||||
|
||||
/**
|
||||
* Closes all editors opened for the file.
|
||||
* Closes all the editors opened for a given file.
|
||||
* Must be called from <a href="https://docs.oracle.com/javase/tutorial/uiswing/concurrency/dispatch.html">EDT</a>.
|
||||
*
|
||||
* @param file file to be closed.
|
||||
@@ -94,7 +93,7 @@ public abstract class FileEditorManager {
|
||||
public abstract boolean isFileOpen(@NotNull VirtualFile file);
|
||||
|
||||
/**
|
||||
* @return {@code true} if {@code file} is opened, {@code false} otherwise
|
||||
* @return {@code true} if {@code file} is opened, {@code false} otherwise.
|
||||
* Unlike {@link #isFileOpen(VirtualFile)} includes files which were opened by all guests during a collaborative development session.
|
||||
*/
|
||||
@ApiStatus.Experimental
|
||||
@@ -108,10 +107,10 @@ public abstract class FileEditorManager {
|
||||
public abstract VirtualFile @NotNull [] getOpenFiles();
|
||||
|
||||
/**
|
||||
* @return all opened files including ones which were opened by guests during a collaborative development session.
|
||||
* Order of files in the array corresponds to the order of host's editor tabs, order for guests isn't determined.
|
||||
* There are cases when only editors for of a particular user is needed (e.g. a search scope 'open files'),
|
||||
* but at the same time editor notifications should be shown to all users
|
||||
* @return all opened files, including ones which were opened by guests during a collaborative development session.
|
||||
* The order of files in the array corresponds to the order of host's editor tabs, order for guests isn't determined.
|
||||
* There are cases when only editors of a particular user are needed (e.g. a search scope 'open files'),
|
||||
* but at the same time editor notifications should be shown to all users.
|
||||
*/
|
||||
@ApiStatus.Experimental
|
||||
public VirtualFile @NotNull [] getOpenFilesWithRemotes() {
|
||||
@@ -123,18 +122,18 @@ public abstract class FileEditorManager {
|
||||
}
|
||||
|
||||
/**
|
||||
* @return files currently selected. The method returns empty array if there are no selected files.
|
||||
* If more than one file is selected (split), the file with most recent focused editor is returned first.
|
||||
* @return files currently selected. The method returns an empty array if there are no selected files.
|
||||
* If more than one file is selected (split), the file with the most recent focused editor is returned first.
|
||||
*/
|
||||
public abstract VirtualFile @NotNull [] getSelectedFiles();
|
||||
|
||||
/**
|
||||
* @return editors currently selected. The method returns empty array if no editors are open.
|
||||
* @return editors currently selected. The method returns an empty array if no editors are open.
|
||||
*/
|
||||
public abstract FileEditor @NotNull [] getSelectedEditors();
|
||||
|
||||
/**
|
||||
* @return editors currently selected including ones which were opened by guests during a collaborative development session
|
||||
* @return editors currently selected including ones which were opened by guests during a collaborative development session.
|
||||
* The method returns an empty array if no editors are open.
|
||||
*/
|
||||
@ApiStatus.Experimental
|
||||
@@ -151,7 +150,7 @@ public abstract class FileEditorManager {
|
||||
}
|
||||
|
||||
/**
|
||||
* @return editor which is currently selected for given file.
|
||||
* @return editor which is currently selected for a given file.
|
||||
* The method returns {@code null} if {@code file} is not opened.
|
||||
*/
|
||||
public abstract @Nullable FileEditor getSelectedEditor(@NotNull VirtualFile file);
|
||||
@@ -179,8 +178,8 @@ public abstract class FileEditorManager {
|
||||
* {@link com.intellij.openapi.editor.colors.EditorColors#SEPARATOR_ABOVE_COLOR SEPARATOR_ABOVE_COLOR} or
|
||||
* {@link com.intellij.openapi.editor.colors.EditorColors#TEARLINE_COLOR TEARLINE_COLOR} if it is not set.
|
||||
* <p>
|
||||
* This method allows to add several components above the editor.
|
||||
* To change an order of components the specified component may implement the
|
||||
* This method allows adding several components above the editor.
|
||||
* To change the order of components, the specified component may implement the
|
||||
* {@link com.intellij.openapi.util.Weighted Weighted} interface.
|
||||
*/
|
||||
public abstract void addTopComponent(final @NotNull FileEditor editor, final @NotNull JComponent component);
|
||||
@@ -195,8 +194,8 @@ public abstract class FileEditorManager {
|
||||
* {@link com.intellij.openapi.editor.colors.EditorColors#SEPARATOR_BELOW_COLOR SEPARATOR_BELOW_COLOR} or
|
||||
* {@link com.intellij.openapi.editor.colors.EditorColors#TEARLINE_COLOR TEARLINE_COLOR} if it is not set.
|
||||
* <p>
|
||||
* This method allows to add several components below the editor.
|
||||
* To change an order of components the specified component may implement the
|
||||
* This method allows adding several components below the editor.
|
||||
* To change the order of components, the specified component may implement the
|
||||
* {@link com.intellij.openapi.util.Weighted Weighted} interface.
|
||||
*/
|
||||
public abstract void addBottomComponent(final @NotNull FileEditor editor, final @NotNull JComponent component);
|
||||
@@ -208,7 +207,7 @@ public abstract class FileEditorManager {
|
||||
public static final Key<Color> SEPARATOR_COLOR = Key.create("FileEditorSeparatorColor");
|
||||
|
||||
/**
|
||||
* Adds specified {@code listener}
|
||||
* Adds specified {@code listener}.
|
||||
*
|
||||
* @param listener listener to be added
|
||||
* @deprecated Use {@link com.intellij.util.messages.MessageBus} instead: see {@link FileEditorManagerListener#FILE_EDITOR_MANAGER}
|
||||
@@ -218,7 +217,7 @@ public abstract class FileEditorManager {
|
||||
}
|
||||
|
||||
/**
|
||||
* Removes specified {@code listener}
|
||||
* Removes specified {@code listener}.
|
||||
*
|
||||
* @param listener listener to be removed
|
||||
* @deprecated Use {@link FileEditorManagerListener#FILE_EDITOR_MANAGER} instead
|
||||
@@ -239,9 +238,7 @@ public abstract class FileEditorManager {
|
||||
public abstract @NotNull List<FileEditor> openFileEditor(@NotNull FileEditorNavigatable descriptor, boolean focusEditor);
|
||||
|
||||
/**
|
||||
* Returns the project with which the file editor manager is associated.
|
||||
*
|
||||
* @return the project instance.
|
||||
* @return the project which the file editor manager is associated with.
|
||||
*/
|
||||
public abstract @NotNull Project getProject();
|
||||
|
||||
@@ -257,14 +254,13 @@ public abstract class FileEditorManager {
|
||||
* Selects a specified file editor tab for the specified editor.
|
||||
*
|
||||
* @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.
|
||||
* @param fileEditorProviderId the ID of the file editor to open; matches the return value of
|
||||
* {@link FileEditorProvider#getEditorTypeId()}
|
||||
* @param fileEditorProviderId the ID of the file editor to open; matches the return value of {@link FileEditorProvider#getEditorTypeId()}
|
||||
*/
|
||||
public abstract void setSelectedEditor(@NotNull VirtualFile file, @NotNull String fileEditorProviderId);
|
||||
|
||||
/**
|
||||
* {@link FileEditorManager} supports asynchronous opening of text editors, i.e. when one of 'openFile' methods returns, returned
|
||||
* editor might not be fully initialized yet. This method allows delaying (if needed) execution of given runnable until editor is
|
||||
* {@link FileEditorManager} supports asynchronous opening of text editors, i.e. when one of {@code openFile*} methods returns, returned
|
||||
* editor might not be fully initialized yet. This method allows delaying (if needed) execution of a given runnable until the editor is
|
||||
* fully loaded.
|
||||
*/
|
||||
public abstract void runWhenLoaded(@NotNull Editor editor, @NotNull Runnable runnable);
|
||||
@@ -272,7 +268,7 @@ public abstract class FileEditorManager {
|
||||
/**
|
||||
* Refreshes the text, colors and icon of the editor tabs representing the specified file.
|
||||
*
|
||||
* @param file the file to refresh.
|
||||
* @param file refreshed file
|
||||
*/
|
||||
public void updateFilePresentation(@NotNull VirtualFile file) { }
|
||||
}
|
||||
|
||||
+5
-5
@@ -20,7 +20,7 @@ public interface FileEditorManagerListener extends EventListener {
|
||||
Topic<FileEditorManagerListener> FILE_EDITOR_MANAGER = new Topic<>(FileEditorManagerListener.class, Topic.BroadcastDirection.TO_PARENT);
|
||||
|
||||
/**
|
||||
* This method is called synchronously (in the same EDT event), as the creation of FileEditor(s).
|
||||
* This method is called synchronously (in the same EDT event), as the creation of {@link FileEditor}s.
|
||||
*
|
||||
* @see #fileOpened(FileEditorManager, VirtualFile)
|
||||
* @deprecated use {@link #fileOpenedSync(FileEditorManager, VirtualFile, List)}
|
||||
@@ -31,7 +31,7 @@ public interface FileEditorManagerListener extends EventListener {
|
||||
}
|
||||
|
||||
/**
|
||||
* This method is called synchronously (in the same EDT event), as the creation of FileEditor(s).
|
||||
* This method is called synchronously (in the same EDT event), as the creation of {@link FileEditor}s.
|
||||
*
|
||||
* @see #fileOpened(FileEditorManager, VirtualFile)
|
||||
*/
|
||||
@@ -43,8 +43,8 @@ public interface FileEditorManagerListener extends EventListener {
|
||||
}
|
||||
|
||||
/**
|
||||
* This method is called after the focus settles down (if requested) in a newly created FileEditor.
|
||||
* Be aware though, that this isn't always true in case of editors loaded asynchronously, which, in general,
|
||||
* This method is called after the focus settles down (if requested) in a newly created {@link FileEditor}.
|
||||
* Be aware that this isn't always true in the case of asynchronously loaded editors, which, in general,
|
||||
* may happen with any text editor. In that case, the focus request is postponed until after the editor is fully loaded,
|
||||
* which means that it may gain the focus way after this method is called.
|
||||
* When necessary, use {@link FileEditorManager#runWhenLoaded(Editor, Runnable)}) to ensure the desired ordering.
|
||||
@@ -52,7 +52,7 @@ public interface FileEditorManagerListener extends EventListener {
|
||||
* {@link #fileOpenedSync(FileEditorManager, VirtualFile, List<FileEditorWithProvider>)} is always invoked before this method,
|
||||
* either in the same or the previous EDT event.
|
||||
*
|
||||
* @see #fileOpenedSync(FileEditorManager, VirtualFile, List<FileEditorWithProvider>)}
|
||||
* @see #fileOpenedSync(FileEditorManager, VirtualFile, List)
|
||||
*/
|
||||
default void fileOpened(@NotNull FileEditorManager source, @NotNull VirtualFile file) {
|
||||
}
|
||||
|
||||
@@ -4,11 +4,9 @@ package com.intellij.openapi.fileEditor;
|
||||
public enum FileEditorPolicy {
|
||||
|
||||
/**
|
||||
* Place created editor before default IDE editor (if any).
|
||||
*/
|
||||
/*
|
||||
* should be the first declaration
|
||||
* Place a created editor before the default IDE editor (if any).
|
||||
*/
|
||||
// should be the first declaration
|
||||
PLACE_BEFORE_DEFAULT_EDITOR,
|
||||
|
||||
/**
|
||||
@@ -24,8 +22,6 @@ public enum FileEditorPolicy {
|
||||
/**
|
||||
* Place created editor after the default IDE editor (if any).
|
||||
*/
|
||||
/*
|
||||
* should be the last declaration
|
||||
*/
|
||||
// should be the last declaration
|
||||
PLACE_AFTER_DEFAULT_EDITOR
|
||||
}
|
||||
|
||||
@@ -23,8 +23,9 @@ public interface FileEditorProvider {
|
||||
Key<FileEditorProvider> KEY = Key.create("com.intellij.fileEditorProvider");
|
||||
|
||||
FileEditorProvider[] EMPTY_ARRAY = {};
|
||||
|
||||
/**
|
||||
* Method is expected to run fast.
|
||||
* The method is expected to run fast.
|
||||
*
|
||||
* @param file file to be tested for acceptance.
|
||||
* @return {@code true} if provider can create valid editor for the specified {@code file}.
|
||||
@@ -54,7 +55,7 @@ public interface FileEditorProvider {
|
||||
}
|
||||
|
||||
/**
|
||||
* Deserialize state from the specified {@code sourceElement}.
|
||||
* Deserializes state from the specified {@code sourceElement}.
|
||||
*/
|
||||
@NotNull
|
||||
default FileEditorState readState(@NotNull Element sourceElement, @NotNull Project project, @NotNull VirtualFile file) {
|
||||
@@ -68,18 +69,19 @@ public interface FileEditorProvider {
|
||||
}
|
||||
|
||||
/**
|
||||
* @return id of type of the editors created with this FileEditorProvider. Each FileEditorProvider should have
|
||||
* unique nonnull id. The id is used for saving/loading of EditorStates.
|
||||
* @return editor type ID for the editors created with this FileEditorProvider. Each FileEditorProvider should have
|
||||
* a unique nonnull ID. The ID is used for saving/loading of EditorStates.
|
||||
*/
|
||||
@NotNull
|
||||
@NonNls
|
||||
String getEditorTypeId();
|
||||
|
||||
/**
|
||||
* @return policy that specifies how editor created via this provider should be opened.
|
||||
* @return a policy that specifies how an editor created via this provider should be opened.
|
||||
* @see FileEditorPolicy#NONE
|
||||
* @see FileEditorPolicy#HIDE_DEFAULT_EDITOR
|
||||
* @see FileEditorPolicy#PLACE_BEFORE_DEFAULT_EDITOR
|
||||
* @see FileEditorPolicy#PLACE_AFTER_DEFAULT_EDITOR
|
||||
*/
|
||||
@NotNull
|
||||
FileEditorPolicy getPolicy();
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
// 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.
|
||||
// Copyright 2000-2022 JetBrains s.r.o. and contributors. Use of this source code is governed by the Apache 2.0 license.
|
||||
package com.intellij.openapi.fileEditor;
|
||||
|
||||
import com.intellij.openapi.actionSystem.DataKey;
|
||||
@@ -13,8 +13,8 @@ import org.jetbrains.annotations.NotNull;
|
||||
*/
|
||||
public class OpenFileDescriptor implements FileEditorNavigatable, Comparable<OpenFileDescriptor> {
|
||||
/**
|
||||
* Tells descriptor to navigate in specific editor rather than file editor in main IDE window.
|
||||
* For example if you want to navigate in editor embedded into modal dialog, you should provide this data.
|
||||
* Tells descriptor to navigate in specific editor rather than file editor in the main IDE window.
|
||||
* For example, if you want to navigate in an editor embedded into modal dialog, you should provide this data.
|
||||
*/
|
||||
public static final DataKey<Editor> NAVIGATE_IN_EDITOR = DataKey.create("NAVIGATE_IN_EDITOR");
|
||||
|
||||
|
||||
+1
-1
@@ -6,7 +6,7 @@ import com.intellij.openapi.fileEditor.FileEditorProvider;
|
||||
import org.jetbrains.annotations.NotNull;
|
||||
|
||||
/**
|
||||
* A holder for both {@link FileEditor} and {@link FileEditorProvider}
|
||||
* A holder for both {@link FileEditor} and {@link FileEditorProvider}.
|
||||
* The package is suffixed with 'ex' for backward compatibility
|
||||
*/
|
||||
public final class FileEditorWithProvider {
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
// Copyright 2000-2021 JetBrains s.r.o. and contributors. Use of this source code is governed by the Apache 2.0 license that can be found in the LICENSE file.
|
||||
// Copyright 2000-2022 JetBrains s.r.o. and contributors. Use of this source code is governed by the Apache 2.0 license.
|
||||
package com.intellij.openapi.fileEditor;
|
||||
|
||||
import com.intellij.codeHighlighting.BackgroundEditorHighlighter;
|
||||
@@ -47,7 +47,7 @@ public interface FileEditor extends UserDataHolder, Disposable {
|
||||
|
||||
/**
|
||||
* Returns editor's name - a string that identifies the editor among others
|
||||
* (e.g.: "GUI Designer" for graphical editing and "Text" for textual representation of a GUI form editors).
|
||||
* (e.g.: "GUI Designer" for graphical editing and "Text" for textual representation of a GUI form editor).
|
||||
*/
|
||||
@Nls(capitalization = Nls.Capitalization.Title) @NotNull String getName();
|
||||
|
||||
@@ -59,14 +59,14 @@ public interface FileEditor extends UserDataHolder, Disposable {
|
||||
}
|
||||
|
||||
/**
|
||||
* Applies given state to the editor.
|
||||
* Applies a given state to the editor.
|
||||
*/
|
||||
void setState(@NotNull FileEditorState state);
|
||||
|
||||
/**
|
||||
* In some cases, it's desirable to set state exactly as requested (e.g. on tab splitting), in other cases different behaviour is
|
||||
* preferred, e.g. bringing caret into view on text editor opening. This method passes additional flag to FileEditor to indicate
|
||||
* the desired way to set state.
|
||||
* In some cases, it's desirable to set state exactly as requested (e.g. on tab splitting), while in other cases different behaviour is
|
||||
* preferred, e.g. bringing caret into view on text editor opening.
|
||||
* This method passes an additional flag to {@link FileEditor} to indicate the desired way to set state.
|
||||
*/
|
||||
default void setState(@NotNull FileEditorState state, boolean exactState) {
|
||||
setState(state);
|
||||
@@ -108,7 +108,7 @@ public interface FileEditor extends UserDataHolder, Disposable {
|
||||
|
||||
/**
|
||||
* A highlighter object to perform background analysis and highlighting activities on.
|
||||
* Return {@code null} if no background highlighting activity necessary for this file editor.
|
||||
* Returns {@code null} if no background highlighting activity is necessary for this file editor.
|
||||
*/
|
||||
default @Nullable BackgroundEditorHighlighter getBackgroundHighlighter() {
|
||||
return null;
|
||||
@@ -128,7 +128,7 @@ public interface FileEditor extends UserDataHolder, Disposable {
|
||||
Key<VirtualFile> FILE_KEY = Key.create("FILE_KEY");
|
||||
|
||||
/**
|
||||
* Returns the file for which {@link FileEditorProvider#createEditor)} was called.
|
||||
* Returns the file for which {@link FileEditorProvider#createEditor} was called.
|
||||
* The default implementation is temporary, and shall be dropped in the future.
|
||||
*/
|
||||
default VirtualFile getFile() {
|
||||
@@ -137,7 +137,7 @@ public interface FileEditor extends UserDataHolder, Disposable {
|
||||
}
|
||||
|
||||
/**
|
||||
* Returns the files for which {@link com.intellij.ide.SaveAndSyncHandler)} should be called on frame activation.
|
||||
* Returns the files for which {@link com.intellij.ide.SaveAndSyncHandler} should be called on frame activation.
|
||||
*/
|
||||
default @NotNull List<@NotNull VirtualFile> getFilesToRefresh() {
|
||||
VirtualFile file = getFile();
|
||||
|
||||
Reference in New Issue
Block a user