embedding/browser/nsIWebBrowserFocus.idl

   1 /* -*- Mode: IDL; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*-
   2  *
   3  * This Source Code Form is subject to the terms of the Mozilla Public
   4  * License, v. 2.0. If a copy of the MPL was not distributed with this
   5  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   6
   7 interface nsIDOMWindow;
   8 interface nsIDOMElement;
   9
  10 #include "nsISupports.idl"
  11
  12 /**
  13  * nsIWebBrowserFocus
  14  * Interface that embedders use for controlling and interacting
  15  * with the browser focus management. The embedded browser can be focused by
  16  * clicking in it or tabbing into it. If the browser is currently focused and
  17  * the embedding application's top level window is disabled, deactivate() must
  18  * be called, and activate() called again when the top level window is
  19  * reactivated for the browser's focus memory to work correctly.
  20  */
  21
  22 [scriptable, uuid(9c5d3c58-1dd1-11b2-a1c9-f3699284657a)]
  23 interface nsIWebBrowserFocus : nsISupports
  24 {
  25   /**
  26    * MANDATORY
  27    * activate() is a mandatory call that must be made to the browser
  28    * when the embedding application's window is activated *and* the
  29    * browser area was the last thing in focus.  This method can also be called
  30    * if the embedding application wishes to give the browser area focus,
  31    * without affecting the currently focused element within the browser.
  32    *
  33    * @note
  34    * If you fail to make this call, mozilla focus memory will not work
  35    * correctly.
  36    */
  37   void activate();
  38
  39   /**
  40    * MANDATORY
  41    * deactivate() is a mandatory call that must be made to the browser
  42    * when the embedding application's window is deactivated *and* the
  43    * browser area was the last thing in focus.  On non-windows platforms,
  44    * deactivate() should also be called when focus moves from the browser
  45    * to the embedding chrome.
  46    *
  47    * @note
  48    * If you fail to make this call, mozilla focus memory will not work
  49    * correctly.
  50    */
  51   void deactivate();
  52
  53   /**
  54    * Give the first element focus within mozilla
  55    * (i.e. TAB was pressed and focus should enter mozilla)
  56    */
  57   void setFocusAtFirstElement();
  58
  59   /**
  60    * Give the last element focus within mozilla
  61    * (i.e. SHIFT-TAB was pressed and focus should enter mozilla)
  62    */
  63   void setFocusAtLastElement();
  64
  65   /**
  66    * The currently focused nsDOMWindow when the browser is active,
  67    * or the last focused nsDOMWindow when the browser is inactive.
  68    */
  69   attribute nsIDOMWindow focusedWindow;
  70
  71   /**
  72    * The currently focused nsDOMElement when the browser is active,
  73    * or the last focused nsDOMElement when the browser is inactive.
  74    */
  75   attribute nsIDOMElement focusedElement;
  76 };