From f71f4101d29138b568eb3bfed46bb0452d075ec0 Mon Sep 17 00:00:00 2001 From: Kirill Kalishev Date: Tue, 10 Jan 2012 20:04:41 +0300 Subject: [PATCH] javadocs for IdeFocusManager + removed unused method --- .../com/intellij/openapi/wm/FocusCommand.java | 4 + .../intellij/openapi/wm/FocusRequestor.java | 10 +- .../intellij/openapi/wm/IdeFocusManager.java | 127 +++++++++++++++--- .../wm/PassThroughtIdeFocusManager.java | 4 - .../wm/impl/IdeFocusManagerHeadless.java | 4 - .../openapi/wm/impl/IdeFocusManagerImpl.java | 5 - 6 files changed, 122 insertions(+), 32 deletions(-) diff --git a/platform/platform-api/src/com/intellij/openapi/wm/FocusCommand.java b/platform/platform-api/src/com/intellij/openapi/wm/FocusCommand.java index 54fec166d76c..61486df6009d 100644 --- a/platform/platform-api/src/com/intellij/openapi/wm/FocusCommand.java +++ b/platform/platform-api/src/com/intellij/openapi/wm/FocusCommand.java @@ -26,6 +26,10 @@ import javax.swing.*; import java.awt.*; import java.util.Arrays; +/** + * The container class for focus requests for IdeFocusManager + * @see IdeFocusManager + */ public abstract class FocusCommand extends ActiveRunnable implements Expirable { protected Component myDominationComponent; private Throwable myAllocation; diff --git a/platform/platform-api/src/com/intellij/openapi/wm/FocusRequestor.java b/platform/platform-api/src/com/intellij/openapi/wm/FocusRequestor.java index 6bb374835e6c..4ed45c85e17a 100644 --- a/platform/platform-api/src/com/intellij/openapi/wm/FocusRequestor.java +++ b/platform/platform-api/src/com/intellij/openapi/wm/FocusRequestor.java @@ -21,12 +21,15 @@ import org.jetbrains.annotations.NotNull; import java.awt.*; +/** + * Basic interface for requesting sending focus commands to IdeFocusManager + */ public interface FocusRequestor extends Disposable { /** * Requests focus on a component - * @param c - * @param forced + * @param c - component to reqiest focus to + * @param forced - if true - focus request is explicit, must be fulfilled, if false - can be dropped * @return action callback that either notifies when the focus was obtained or focus request was droppped */ @NotNull @@ -34,8 +37,7 @@ public interface FocusRequestor extends Disposable { /** * Runs a request focus command, actual focus request is defined by the user in the command itself - * @param command - * @param forced + * @param forced - if true - focus request is explicit, must be fulfilled, if false - can be dropped * @return action callback that either notifies when the focus was obtained or focus request was droppped */ @NotNull diff --git a/platform/platform-api/src/com/intellij/openapi/wm/IdeFocusManager.java b/platform/platform-api/src/com/intellij/openapi/wm/IdeFocusManager.java index 11d1c87d0385..7b30f53d51f6 100644 --- a/platform/platform-api/src/com/intellij/openapi/wm/IdeFocusManager.java +++ b/platform/platform-api/src/com/intellij/openapi/wm/IdeFocusManager.java @@ -31,6 +31,24 @@ import javax.swing.*; import java.awt.*; import java.awt.event.KeyEvent; +/** + * This class receives focus requests, manages the, and delegates to the awt focus subsystem. All focus requests + * should be done through this class. For example, to request focus on a component: + * 
+ *   IdeFocusManager.getInstance(project).requestFocus(comp, true);
+ *
+ * This is the preferred way to request focus on components to + * 
+ *   comp.requestFocus();
+ *
+ * + * This class is also responsible for delivering key events while focus tranferring is in progress. + *

+ * IdeFocusManager instance can be received per project or the global instance. The preferred way is + * to use instance IdeFocusManager.getInstance(project). If no project instance is available, then + * IdeFocusManager.getGlobalInstance() can be used. + */ + public abstract class IdeFocusManager implements FocusRequestor { /** @@ -43,36 +61,126 @@ public abstract class IdeFocusManager implements FocusRequestor { public abstract JComponent getFocusTargetFor(@NotNull final JComponent comp); + /** + * Executes given runnable after all focus activities are finished + * @param runnable + */ public abstract void doWhenFocusSettlesDown(@NotNull Runnable runnable); + /** + * Executes given runnable after all focus activities are finished + * @param runnable + */ public abstract void doWhenFocusSettlesDown(@NotNull ExpirableRunnable runnable); + /** + * Finds focused component among descendants of the given component. Descendants may be in child popups and windows + * @param comp + * @return + */ @Nullable public abstract Component getFocusedDescendantFor(final Component comp); + /** + * Dispatches given key event. This methods should not be called by the user code + * @param e + * @return true is the event was dispatched, false - otherwise. + */ public abstract boolean dispatch(KeyEvent e); + /** + * Aggregates all key events until given callback object is processed + * @param done + */ public abstract void typeAheadUntil(ActionCallback done); - @Deprecated - //todo to remove if no usages - public abstract void suspendKeyProcessingUntil(@NotNull ActionCallback done); - + /** + * Reports if any focus activity is being done + * @return + */ public abstract boolean isFocusBeingTransferred(); + /** + * Requests default focus. The method should not be called by the user code. + * @param forced + * @return + */ public abstract ActionCallback requestDefaultFocus(boolean forced); + /** + * Reports of focus transfer is enabled right now. It can be disabled if app is inactive. In this case + * all focus requests will be either postponed or executed only if FocusCommand can be executed on an inaactive app. + * @see com.intellij.openapi.wm.FocusCommand#canExecuteOnInactiveApp() + * @return + */ public abstract boolean isFocusTransferEnabled(); + /** + * Returns Expirable instance for the given counter of focus commands. As any new FocusCommand + * is emitted to execute, the counter increments thus making the returned Expirable objects expired. + * @param trackOnlyForcedCommands + * @return + */ public abstract Expirable getTimestamp(boolean trackOnlyForcedCommands); + /** + * Returns FocusRequestor object which will emit focus requests unless expired. + * @see #getTimestamp(boolean) + * @return + */ public abstract FocusRequestor getFurtherRequestor(); + /** + * Injects some procedure that will maybe do something with focus after all focus requests are fulfilled and + * before focus transfer is reported ready. + * @param runnable + */ public abstract void revalidateFocus(@NotNull ExpirableRunnable runnable); + /** + * Enables or disables typeahead + * @see #typeAheadUntil(com.intellij.openapi.util.ActionCallback) + * @param enabled + */ public abstract void setTypeaheadEnabled(boolean enabled); + /** + * Computes effective focus owner + * @return + */ + public abstract Component getFocusOwner(); + + /** + * Runs runnable for whicj DataContext will no be computed from the current focus owner, + * but used the given one + * @param context + * @param runnable + */ + public abstract void runOnOwnContext(DataContext context, Runnable runnable); + + /** + * Returns last focused component for the given IdeFrame + * @param frame + * @return + */ + @Nullable + public abstract Component getLastFocusedFor(@Nullable IdeFrame frame); + + /** + * Returns last focused IdeFrame + * @return + */ + @Nullable + public abstract IdeFrame getLastFocusedFrame(); + + /** + * Put the container window to front. May not execute of the app is inactive or under some other conditions. This + * is the preferred way to finding the container window and uncoditionally calling window.toFront() + * @param c + */ + public abstract void toFront(JComponent c); + public static IdeFocusManager getInstance(@Nullable Project project) { if (project == null) return getGlobalInstance(); @@ -143,15 +251,4 @@ public abstract class IdeFocusManager implements FocusRequestor { return fm; } - public abstract Component getFocusOwner(); - - public abstract void runOnOwnContext(DataContext context, Runnable runnable); - - @Nullable - public abstract Component getLastFocusedFor(@Nullable IdeFrame frame); - - @Nullable - public abstract IdeFrame getLastFocusedFrame(); - - public abstract void toFront(JComponent c); } diff --git a/platform/platform-api/src/com/intellij/openapi/wm/PassThroughtIdeFocusManager.java b/platform/platform-api/src/com/intellij/openapi/wm/PassThroughtIdeFocusManager.java index 9d896e01eb72..7524ab35b4f4 100644 --- a/platform/platform-api/src/com/intellij/openapi/wm/PassThroughtIdeFocusManager.java +++ b/platform/platform-api/src/com/intellij/openapi/wm/PassThroughtIdeFocusManager.java @@ -132,10 +132,6 @@ public class PassThroughtIdeFocusManager extends IdeFocusManager { public void toFront(JComponent c) { } - @Override - public void suspendKeyProcessingUntil(@NotNull ActionCallback done) { - } - @Override public boolean isFocusBeingTransferred() { return false; diff --git a/platform/platform-impl/src/com/intellij/openapi/wm/impl/IdeFocusManagerHeadless.java b/platform/platform-impl/src/com/intellij/openapi/wm/impl/IdeFocusManagerHeadless.java index 3556784e5cc0..f9302cfbe710 100644 --- a/platform/platform-impl/src/com/intellij/openapi/wm/impl/IdeFocusManagerHeadless.java +++ b/platform/platform-impl/src/com/intellij/openapi/wm/impl/IdeFocusManagerHeadless.java @@ -70,10 +70,6 @@ public class IdeFocusManagerHeadless extends IdeFocusManager { public void typeAheadUntil(ActionCallback done) { } - @Override - public void suspendKeyProcessingUntil(@NotNull ActionCallback done) { - } - @Override public boolean isFocusBeingTransferred() { return false; diff --git a/platform/platform-impl/src/com/intellij/openapi/wm/impl/IdeFocusManagerImpl.java b/platform/platform-impl/src/com/intellij/openapi/wm/impl/IdeFocusManagerImpl.java index db2739e5fe30..b0a302324eba 100644 --- a/platform/platform-impl/src/com/intellij/openapi/wm/impl/IdeFocusManagerImpl.java +++ b/platform/platform-impl/src/com/intellij/openapi/wm/impl/IdeFocusManagerImpl.java @@ -74,11 +74,6 @@ public class IdeFocusManagerImpl extends IdeFocusManager { getGlobalInstance().typeAheadUntil(done); } - @Override - public void suspendKeyProcessingUntil(@NotNull ActionCallback done) { - getGlobalInstance().suspendKeyProcessingUntil(done); - } - public ActionCallback requestDefaultFocus(boolean forced) { return myToolWindowManager.requestDefaultFocus(forced);