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);