javadocs for IdeFocusManager + removed unused method

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 <code>IdeFocusManager</code>
+ * @see IdeFocusManager
+ */
 public abstract class FocusCommand extends ActiveRunnable implements Expirable {
   protected Component myDominationComponent;
   private Throwable myAllocation;

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 <code>IdeFocusManager</code>
+ */
 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

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:
+ * <pre>
+ *   IdeFocusManager.getInstance(project).requestFocus(comp, true);
+ * </pre>
+ * This is the preferred way to request focus on components to
+ * <pre>
+ *   comp.requestFocus();
+ * </pre>
+ *
+ * This class is also responsible for delivering key events while focus tranferring is in progress.
+ * <p>
+ * <code>IdeFocusManager</code> instance can be received per project or the global instance. The preferred way is
+ * to use instance <code>IdeFocusManager.getInstance(project)</code>. If no project instance is available, then
+ * <code>IdeFocusManager.getGlobalInstance()</code> 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 <code>FocusCommand</code> can be executed on an inaactive app.
+   * @see com.intellij.openapi.wm.FocusCommand#canExecuteOnInactiveApp()
+   * @return
+   */
   public abstract boolean isFocusTransferEnabled();
 
+  /**
+   * Returns <code>Expirable</code> instance for the given counter of focus commands. As any new <code>FocusCommand</code>
+   * is emitted to execute, the counter increments thus making the returned <code>Expirable</code> objects expired.
+   * @param trackOnlyForcedCommands
+   * @return
+   */
   public abstract Expirable getTimestamp(boolean trackOnlyForcedCommands);
 
+  /**
+   * Returns <code>FocusRequestor</code> 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 <code>DataContext</code> 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 <code>IdeFrame</code>
+   * @param frame
+   * @return
+   */
+  @Nullable
+  public abstract Component getLastFocusedFor(@Nullable IdeFrame frame);
+
+  /**
+   * Returns last focused <code>IdeFrame</code>
+   * @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 <code>window.toFront()</code>
+   * @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);
 }

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;

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;

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