import FIREFOX_52_6_0esr_RELEASE from mozilla-esr52 hg repo

embedding/browser/nsIWebBrowserFocus.idl

@@ -0,0 +1,76 @@
+/* -*- Mode: IDL; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*-
+ *
+ * This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
+
+interface mozIDOMWindowProxy;
+interface nsIDOMElement;
+
+#include "nsISupports.idl"
+
+/**
+ * nsIWebBrowserFocus
+ * 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
+ * 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.
+ */
+
+[scriptable, uuid(7f8c754e-5b36-44be-bc96-191b49f08ea6)]
+interface nsIWebBrowserFocus : nsISupports
+{
+  /**
+   * 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
+   * 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
+   * (i.e. TAB was pressed and focus should enter mozilla)
+   */
+  void setFocusAtFirstElement();
+
+  /**
+   * 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 browser is inactive.
+   */
+  attribute mozIDOMWindowProxy focusedWindow;
+  
+  /**
+   * The currently focused nsDOMElement when the browser is active,
+   * or the last focused nsDOMElement when the browser is inactive.
+   */
+  attribute nsIDOMElement focusedElement;
+};