michael@0: /* -*- Mode: IDL; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*-
michael@0:  *
michael@0:  * This Source Code Form is subject to the terms of the Mozilla Public
michael@0:  * License, v. 2.0. If a copy of the MPL was not distributed with this
michael@0:  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
michael@0: 
michael@0: interface nsIDOMWindow;
michael@0: interface nsIDOMElement;
michael@0: 
michael@0: #include "nsISupports.idl"
michael@0: 
michael@0: /**
michael@0:  * nsIWebBrowserFocus
michael@0:  * Interface that embedders use for controlling and interacting
michael@0:  * with the browser focus management. The embedded browser can be focused by
michael@0:  * clicking in it or tabbing into it. If the browser is currently focused and
michael@0:  * the embedding application's top level window is disabled, deactivate() must
michael@0:  * be called, and activate() called again when the top level window is
michael@0:  * reactivated for the browser's focus memory to work correctly.
michael@0:  */
michael@0: 
michael@0: [scriptable, uuid(9c5d3c58-1dd1-11b2-a1c9-f3699284657a)]
michael@0: interface nsIWebBrowserFocus : nsISupports
michael@0: {
michael@0:   /**
michael@0:    * MANDATORY
michael@0:    * activate() is a mandatory call that must be made to the browser
michael@0:    * when the embedding application's window is activated *and* the 
michael@0:    * browser area was the last thing in focus.  This method can also be called
michael@0:    * if the embedding application wishes to give the browser area focus,
michael@0:    * without affecting the currently focused element within the browser.
michael@0:    *
michael@0:    * @note
michael@0:    * If you fail to make this call, mozilla focus memory will not work
michael@0:    * correctly.
michael@0:    */
michael@0:   void activate();
michael@0: 
michael@0:   /**
michael@0:    * MANDATORY
michael@0:    * deactivate() is a mandatory call that must be made to the browser
michael@0:    * when the embedding application's window is deactivated *and* the
michael@0:    * browser area was the last thing in focus.  On non-windows platforms,
michael@0:    * deactivate() should also be called when focus moves from the browser
michael@0:    * to the embedding chrome.
michael@0:    *
michael@0:    * @note
michael@0:    * If you fail to make this call, mozilla focus memory will not work
michael@0:    * correctly.
michael@0:    */
michael@0:   void deactivate();
michael@0: 
michael@0:   /**
michael@0:    * Give the first element focus within mozilla
michael@0:    * (i.e. TAB was pressed and focus should enter mozilla)
michael@0:    */
michael@0:   void setFocusAtFirstElement();
michael@0: 
michael@0:   /**
michael@0:    * Give the last element focus within mozilla
michael@0:    * (i.e. SHIFT-TAB was pressed and focus should enter mozilla)
michael@0:    */
michael@0:   void setFocusAtLastElement();
michael@0:   
michael@0:   /**
michael@0:    * The currently focused nsDOMWindow when the browser is active,
michael@0:    * or the last focused nsDOMWindow when the browser is inactive.
michael@0:    */
michael@0:   attribute nsIDOMWindow focusedWindow;
michael@0:   
michael@0:   /**
michael@0:    * The currently focused nsDOMElement when the browser is active,
michael@0:    * or the last focused nsDOMElement when the browser is inactive.
michael@0:    */
michael@0:   attribute nsIDOMElement focusedElement;
michael@0: };