src/macosx/classes/sun/lwawt/macosx/CEmbeddedFrame.java

*** 117,126 ****
--- 117,137 ----
          if (parentWindowActive) {
              responder.handleWindowFocusEvent(focused, null);
          }
      }
  
+     /**
+      * When the window is activated and had focus before the deactivation
+      * calling this method triggers focus events in the following order:
+      *  1. WINDOW_ACTIVATED for this EmbeddedFrame
+      *  2. WINDOW_GAINED_FOCUS for this EmbeddedFrame
+      *  3. FOCUS_GAINED for the most recent focus owner in this EmbeddedFrame
+      *
+      * The caller must not requestFocus on the EmbeddedFrame together with calling this method.
+      *
+      * @param parentWindowActive true if the window is activated, false otherwise
+      */
      public void handleWindowFocusEvent(boolean parentWindowActive) {
          this.parentWindowActive = parentWindowActive;
          // ignore focus "lost" native request as it may mistakenly
          // deactivate active window (see 8001161)
          if (focused && parentWindowActive) {