From fe0c978747e149ab2dc4d6ee5513e8e1e8a24230 Mon Sep 17 00:00:00 2001
From: "bryner%netscape.com" <bryner%netscape.com>
Date: Thu, 20 Feb 2003 23:11:07 +0000
Subject: [PATCH] Freeze nsIWebBrowserFocus and nsIWebBrowserChromeFocus (bug
 191236). r=saari, sr=alecf, a=asa.

---
 .../webBrowser/nsIWebBrowserChromeFocus.idl   |  6 +-
 .../browser/webBrowser/nsIWebBrowserFocus.idl | 62 +++++++++++++------
 2 files changed, 45 insertions(+), 23 deletions(-)

diff --git a/embedding/browser/webBrowser/nsIWebBrowserChromeFocus.idl b/embedding/browser/webBrowser/nsIWebBrowserChromeFocus.idl
index b3a95c0fc33d..4078fbc07f70 100644
--- a/embedding/browser/webBrowser/nsIWebBrowserChromeFocus.idl
+++ b/embedding/browser/webBrowser/nsIWebBrowserChromeFocus.idl
@@ -29,20 +29,20 @@
  * nsIWebBrowserSiteWindow. It represents the focus up-calls from mozilla
  * to the embedding chrome. See mozilla bug #70224 for gratuitous info.
  *
- * @status UNDER_REVIEW
+ * @status FROZEN
  */
 
 [scriptable, uuid(d2206418-1dd1-11b2-8e55-acddcd2bcfb8)]
 interface nsIWebBrowserChromeFocus : nsISupports
 {
     /**
-     * Set the focus at the next focusable element in the chrome
+     * Set the focus at the next focusable element in the chrome.
      */
 
     void focusNextElement();
 
     /**
-     * Set the focus at the previous focusable element in the chrome
+     * Set the focus at the previous focusable element in the chrome.
      */
 
     void focusPrevElement();
diff --git a/embedding/browser/webBrowser/nsIWebBrowserFocus.idl b/embedding/browser/webBrowser/nsIWebBrowserFocus.idl
index fc08815d447e..c711e0d48240 100644
--- a/embedding/browser/webBrowser/nsIWebBrowserFocus.idl
+++ b/embedding/browser/webBrowser/nsIWebBrowserFocus.idl
@@ -30,43 +30,65 @@ interface nsIDOMElement;
  * Interface that embedders use for controlling and interacting
  * with the browser focus management. The embedded browser can be focused by
  * clicking in it or tabbing into it. If the browser is currently focused and
- * embedding application's top level window is disabled, deactivate() must
+ * the embedding application's top level window is disabled, deactivate() must
  * be called, and activate() called again when the top level window is
  * reactivated for the browser's focus memory to work correctly.
  *
- * @status UNDER_REVIEW
+ * @status FROZEN
  */
 
 [scriptable, uuid(9c5d3c58-1dd1-11b2-a1c9-f3699284657a)]
 interface nsIWebBrowserFocus : nsISupports
 {
-  // MANDATORY
-  // activate() is a mandatory call that must be made to the browser
-  // when the embedding applications window is activated *and* the 
-  // browser area was the last thing in focus. If you fail
-  // to make this call mozilla focus memory will not work correctly.
+  /**
+   * MANDATORY
+   * activate() is a mandatory call that must be made to the browser
+   * when the embedding application's window is activated *and* the 
+   * browser area was the last thing in focus.  This method can also be called
+   * if the embedding application wishes to give the browser area focus,
+   * without affecting the currently focused element within the browser.
+   *
+   * @note
+   * If you fail to make this call, mozilla focus memory will not work
+   * correctly.
+   */
   void activate();
 
-  // MANDATORY
-  // decactivate() is a mandatory call that must be made to the browser
-  // when the embedding applications window is deactivated *and* the
-  // browser area was the last thing in focus. If you fail
-  // to make this call mozilla focus memory will not work correctly.
+  /**
+   * MANDATORY
+   * deactivate() is a mandatory call that must be made to the browser
+   * when the embedding application's window is deactivated *and* the
+   * browser area was the last thing in focus.  On non-windows platforms,
+   * deactivate() should also be called when focus moves from the browser
+   * to the embedding chrome.
+   *
+   * @note
+   * If you fail to make this call, mozilla focus memory will not work
+   * correctly.
+   */
   void deactivate();
 
-  // Give the first element focus within mozilla
-  // (ie. TAB was pressed and focus should enter mozilla)
+  /**
+   * Give the first element focus within mozilla
+   * (i.e. TAB was pressed and focus should enter mozilla)
+   */
   void setFocusAtFirstElement();
 
-  // Give the last element focus within mozilla
-  // (ie. ALT-TAB was pressed and focus should enter mozilla)
+  /**
+   * Give the last element focus within mozilla
+   * (i.e. SHIFT-TAB was pressed and focus should enter mozilla)
+   */
   void setFocusAtLastElement();
   
-  // The currently focused nsDOMWindow when the browser is active
-  // or the last focused nsDOMWindow when the broser is inactive.
+  /**
+   * The currently focused nsDOMWindow when the browser is active,
+   * or the last focused nsDOMWindow when the browser is inactive.
+   */
   attribute nsIDOMWindow focusedWindow;
   
-  // The currently focused nsDOMElement when the browser is active
-  // or the last focused nsDOMElement when the broser is inactive.
+  /**
+   * The currently focused nsDOMElement when the browser is active,
+   * or the last focused nsDOMElement when the browser is inactive.
+   */
   attribute nsIDOMElement focusedElement;
 };