win/sdk/idl/nsIWindowWatcher.idl - chromium/deps/xulrunner-sdk - Git at Google

 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*-
  *
  * ***** BEGIN LICENSE BLOCK *****
  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
  *
  * The contents of this file are subject to the Mozilla Public License Version
  * 1.1 (the "License"); you may not use this file except in compliance with
  * the License. You may obtain a copy of the License at
  * http://www.mozilla.org/MPL/
  *
  * Software distributed under the License is distributed on an "AS IS" basis,
  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  * for the specific language governing rights and limitations under the
  * License.
  *
  * The Original Code is mozilla.org code.
  *
  * The Initial Developer of the Original Code is
  * Netscape Communications, Inc.
  * Portions created by the Initial Developer are Copyright (C) 2001
  * the Initial Developer. All Rights Reserved.
  *
  * Contributor(s):
  *
  * Alternatively, the contents of this file may be used under the terms of
  * either the GNU General Public License Version 2 or later (the "GPL"), or
  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  * in which case the provisions of the GPL or the LGPL are applicable instead
  * of those above. If you wish to allow use of your version of this file only
  * under the terms of either the GPL or the LGPL, and not to allow others to
  * use your version of this file under the terms of the MPL, indicate your
  * decision by deleting the provisions above and replace them with the notice
  * and other provisions required by the GPL or the LGPL. If you do not delete
  * the provisions above, a recipient may use your version of this file under
  * the terms of any one of the MPL, the GPL or the LGPL.
  *
  * ***** END LICENSE BLOCK ***** */

 #include "nsISupports.idl"

 interface nsIDOMWindow;
 interface nsIObserver;
 interface nsIPrompt;
 interface nsIAuthPrompt;
 interface nsISimpleEnumerator;
 interface nsIWebBrowserChrome;
 interface nsIWindowCreator;


 /**
  * nsIWindowWatcher is the keeper of Gecko/DOM Windows. It maintains
  * a list of open top-level windows, and allows some operations on them.

  * Usage notes:

  *   This component has an |activeWindow| property. Clients may expect
  * this property to be always current, so to properly integrate this component
  * the application will need to keep it current by setting the property
  * as the active window changes.
  *   This component should not keep a (XPCOM) reference to any windows;
  * the implementation will claim no ownership. Windows must notify
  * this component when they are created or destroyed, so only a weak
  * reference is kept. Note that there is no interface for such notifications
  * (not a public one, anyway). This is taken care of both in Mozilla and
  * by common embedding code. Embedding clients need do nothing special
  * about that requirement.
  *   This component must be initialized at application startup by calling
  * setWindowCreator.
  *
  * @status FROZEN
  */
 [scriptable, uuid(002286a8-494b-43b3-8ddd-49e3fc50622b)]

 interface nsIWindowWatcher : nsISupports {

   /** Create a new window. It will automatically be added to our list
       (via addWindow()).
       @param aParent parent window, if any. Null if no parent.  If it is
              impossible to get to an nsIWebBrowserChrome from aParent, this
              method will effectively act as if aParent were null.
       @param aURL url to which to open the new window. Must already be
              escaped, if applicable. can be null.
       @param aName window name from JS window.open. can be null.  If a window
              with this name already exists, the openWindow call may just load
              aUrl in it (if aUrl is not null) and return it.
       @param aFeatures window features from JS window.open. can be null.
       @param aArguments extra argument(s) to the new window, to be attached
              as the |arguments| property. An nsISupportsArray will be
              unwound into multiple arguments (but not recursively!).
              can be null.
       @return the new window

       @note This method may examine the JS context stack for purposes of
             determining the security context to use for the search for a given
             window named aName.
       @note This method should try to set the default charset for the new
             window to the default charset of aParent.  This is not guaranteed,
             however.
       @note This method may dispatch a "toplevel-window-ready" notification
             via nsIObserverService if the window did not already exist.
   */
   nsIDOMWindow openWindow(in nsIDOMWindow aParent, in string aUrl,
                in string aName, in string aFeatures,
                in nsISupports aArguments);

   /** Clients of this service can register themselves to be notified
       when a window is opened or closed (added to or removed from this
       service). This method adds an aObserver to the list of objects
       to be notified.
       @param aObserver the object to be notified when windows are
                        opened or closed. Its Observe method will be
                        called with the following parameters:

       aObserver::Observe interprets its parameters so:
       aSubject the window being opened or closed, sent as an nsISupports
                which can be QIed to an nsIDOMWindow.
       aTopic   a wstring, either "domwindowopened" or "domwindowclosed".
       someData not used.
   */
   void registerNotification(in nsIObserver aObserver);

   /** Clients of this service can register themselves to be notified
       when a window is opened or closed (added to or removed from this
       service). This method removes an aObserver from the list of objects
       to be notified.
       @param aObserver the observer to be removed.
   */
   void unregisterNotification(in nsIObserver aObserver);

   /** Get an iterator for currently open windows in the order they were opened,
       guaranteeing that each will be visited exactly once.
       @return an enumerator which will itself return nsISupports objects which
               can be QIed to an nsIDOMWindow
   */

   nsISimpleEnumerator getWindowEnumerator();

   /** Return a newly created nsIPrompt implementation.
       @param aParent the parent window used for posing alerts. can be null.
       @return a new nsIPrompt object
   */

   nsIPrompt getNewPrompter(in nsIDOMWindow aParent);

   /** Return a newly created nsIAuthPrompt implementation.
       @param aParent the parent window used for posing alerts. can be null.
       @return a new nsIAuthPrompt object
   */

   nsIAuthPrompt getNewAuthPrompter(in nsIDOMWindow aParent);

   /** Set the window creator callback. It must be filled in by the app.
       openWindow will use it to create new windows.
       @param creator the callback. if null, the callback will be cleared
                      and window creation capabilities lost.
   */
   void setWindowCreator(in nsIWindowCreator creator);


   /** Retrieve the chrome window mapped to the given DOM window. Window
       Watcher keeps a list of all top-level DOM windows currently open,
       along with their corresponding chrome interfaces. Since DOM Windows
       lack a (public) means of retrieving their corresponding chrome,
       this method will do that.
       @param aWindow the DOM window whose chrome window the caller needs
       @return the corresponding chrome window
   */
   nsIWebBrowserChrome getChromeForWindow(in nsIDOMWindow aWindow);

   /**
       Retrieve an existing window (or frame).
       @param aTargetName the window name
       @param aCurrentWindow a starting point in the window hierarchy to
                             begin the search.  If null, each toplevel window
                             will be searched.

       Note: This method will search all open windows for any window or
       frame with the given window name. Make sure you understand the
       security implications of this before using this method!
   */
   nsIDOMWindow getWindowByName(in wstring aTargetName,
                                in nsIDOMWindow aCurrentWindow);

   /** The Watcher serves as a global storage facility for the current active
       (frontmost non-floating-palette-type) window, storing and returning
       it on demand. Users must keep this attribute current, including after
       the topmost window is closed. This attribute obviously can return null
       if no windows are open, but should otherwise always return a valid
       window.
   */
   attribute nsIDOMWindow activeWindow;

 };

 %{C++
 // {002286a8-494b-43b3-8ddd-49e3fc50622b}
 #define NS_WINDOWWATCHER_IID \
  {0x002286a8, 0x494b, 0x43b3, {0x8d, 0xdd, 0x49, 0xe3, 0xfc, 0x50, 0x62, 0x2b}}

 #define NS_WINDOWWATCHER_CONTRACTID "@mozilla.org/embedcomp/window-watcher;1"
 %}
	/* -- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 --
	*
	* *** BEGIN LICENSE BLOCK ***
	* Version: MPL 1.1/GPL 2.0/LGPL 2.1
	*
	* The contents of this file are subject to the Mozilla Public License Version
	* 1.1 (the "License"); you may not use this file except in compliance with
	* the License. You may obtain a copy of the License at
	* http://www.mozilla.org/MPL/
	*
	* Software distributed under the License is distributed on an "AS IS" basis,
	* WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
	* for the specific language governing rights and limitations under the
	* License.
	*
	* The Original Code is mozilla.org code.
	*
	* The Initial Developer of the Original Code is
	* Netscape Communications, Inc.
	* Portions created by the Initial Developer are Copyright (C) 2001
	* the Initial Developer. All Rights Reserved.
	*
	* Contributor(s):
	*
	* Alternatively, the contents of this file may be used under the terms of
	* either the GNU General Public License Version 2 or later (the "GPL"), or
	* the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
	* in which case the provisions of the GPL or the LGPL are applicable instead
	* of those above. If you wish to allow use of your version of this file only
	* under the terms of either the GPL or the LGPL, and not to allow others to
	* use your version of this file under the terms of the MPL, indicate your
	* decision by deleting the provisions above and replace them with the notice
	* and other provisions required by the GPL or the LGPL. If you do not delete
	* the provisions above, a recipient may use your version of this file under
	* the terms of any one of the MPL, the GPL or the LGPL.
	*
	* *** END LICENSE BLOCK *** */

	#include "nsISupports.idl"

	interface nsIDOMWindow;
	interface nsIObserver;
	interface nsIPrompt;
	interface nsIAuthPrompt;
	interface nsISimpleEnumerator;
	interface nsIWebBrowserChrome;
	interface nsIWindowCreator;



	/**
	* nsIWindowWatcher is the keeper of Gecko/DOM Windows. It maintains
	* a list of open top-level windows, and allows some operations on them.

	* Usage notes:

	* This component has an \|activeWindow\| property. Clients may expect
	* this property to be always current, so to properly integrate this component
	* the application will need to keep it current by setting the property
	* as the active window changes.
	* This component should not keep a (XPCOM) reference to any windows;
	* the implementation will claim no ownership. Windows must notify
	* this component when they are created or destroyed, so only a weak
	* reference is kept. Note that there is no interface for such notifications
	* (not a public one, anyway). This is taken care of both in Mozilla and
	* by common embedding code. Embedding clients need do nothing special
	* about that requirement.
	* This component must be initialized at application startup by calling
	* setWindowCreator.
	*
	* @status FROZEN
	*/
	[scriptable, uuid(002286a8-494b-43b3-8ddd-49e3fc50622b)]

	interface nsIWindowWatcher : nsISupports {

	/** Create a new window. It will automatically be added to our list
	(via addWindow()).
	@param aParent parent window, if any. Null if no parent. If it is
	impossible to get to an nsIWebBrowserChrome from aParent, this
	method will effectively act as if aParent were null.
	@param aURL url to which to open the new window. Must already be
	escaped, if applicable. can be null.
	@param aName window name from JS window.open. can be null. If a window
	with this name already exists, the openWindow call may just load
	aUrl in it (if aUrl is not null) and return it.
	@param aFeatures window features from JS window.open. can be null.
	@param aArguments extra argument(s) to the new window, to be attached
	as the \|arguments\| property. An nsISupportsArray will be
	unwound into multiple arguments (but not recursively!).
	can be null.
	@return the new window

	@note This method may examine the JS context stack for purposes of
	determining the security context to use for the search for a given
	window named aName.
	@note This method should try to set the default charset for the new
	window to the default charset of aParent. This is not guaranteed,
	however.
	@note This method may dispatch a "toplevel-window-ready" notification
	via nsIObserverService if the window did not already exist.
	*/
	nsIDOMWindow openWindow(in nsIDOMWindow aParent, in string aUrl,
	in string aName, in string aFeatures,
	in nsISupports aArguments);

	/** Clients of this service can register themselves to be notified
	when a window is opened or closed (added to or removed from this
	service). This method adds an aObserver to the list of objects
	to be notified.
	@param aObserver the object to be notified when windows are
	opened or closed. Its Observe method will be
	called with the following parameters:

	aObserver::Observe interprets its parameters so:
	aSubject the window being opened or closed, sent as an nsISupports
	which can be QIed to an nsIDOMWindow.
	aTopic a wstring, either "domwindowopened" or "domwindowclosed".
	someData not used.
	*/
	void registerNotification(in nsIObserver aObserver);

	/** Clients of this service can register themselves to be notified
	when a window is opened or closed (added to or removed from this
	service). This method removes an aObserver from the list of objects
	to be notified.
	@param aObserver the observer to be removed.
	*/
	void unregisterNotification(in nsIObserver aObserver);

	/** Get an iterator for currently open windows in the order they were opened,
	guaranteeing that each will be visited exactly once.
	@return an enumerator which will itself return nsISupports objects which
	can be QIed to an nsIDOMWindow
	*/

	nsISimpleEnumerator getWindowEnumerator();

	/** Return a newly created nsIPrompt implementation.
	@param aParent the parent window used for posing alerts. can be null.
	@return a new nsIPrompt object
	*/

	nsIPrompt getNewPrompter(in nsIDOMWindow aParent);

	/** Return a newly created nsIAuthPrompt implementation.
	@param aParent the parent window used for posing alerts. can be null.
	@return a new nsIAuthPrompt object
	*/

	nsIAuthPrompt getNewAuthPrompter(in nsIDOMWindow aParent);

	/** Set the window creator callback. It must be filled in by the app.
	openWindow will use it to create new windows.
	@param creator the callback. if null, the callback will be cleared
	and window creation capabilities lost.
	*/
	void setWindowCreator(in nsIWindowCreator creator);


	/** Retrieve the chrome window mapped to the given DOM window. Window
	Watcher keeps a list of all top-level DOM windows currently open,
	along with their corresponding chrome interfaces. Since DOM Windows
	lack a (public) means of retrieving their corresponding chrome,
	this method will do that.
	@param aWindow the DOM window whose chrome window the caller needs
	@return the corresponding chrome window
	*/
	nsIWebBrowserChrome getChromeForWindow(in nsIDOMWindow aWindow);

	/**
	Retrieve an existing window (or frame).
	@param aTargetName the window name
	@param aCurrentWindow a starting point in the window hierarchy to
	begin the search. If null, each toplevel window
	will be searched.

	Note: This method will search all open windows for any window or
	frame with the given window name. Make sure you understand the
	security implications of this before using this method!
	*/
	nsIDOMWindow getWindowByName(in wstring aTargetName,
	in nsIDOMWindow aCurrentWindow);

	/** The Watcher serves as a global storage facility for the current active
	(frontmost non-floating-palette-type) window, storing and returning
	it on demand. Users must keep this attribute current, including after
	the topmost window is closed. This attribute obviously can return null
	if no windows are open, but should otherwise always return a valid
	window.
	*/
	attribute nsIDOMWindow activeWindow;

	};

	%{C++
	// {002286a8-494b-43b3-8ddd-49e3fc50622b}
	#define NS_WINDOWWATCHER_IID \
	{0x002286a8, 0x494b, 0x43b3, {0x8d, 0xdd, 0x49, 0xe3, 0xfc, 0x50, 0x62, 0x2b}}

	#define NS_WINDOWWATCHER_CONTRACTID "@mozilla.org/embedcomp/window-watcher;1"
	%}