Version 1.8 of gecko-sdk. Downloaded from here:...

gecko-sdk/idl/nsIWindowWatcher.idl

+/* -*- 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 ***** */
+
+/**
+ * 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
+ */
+
+#include "nsISupports.idl"
+
+interface nsIDOMWindow;
+interface nsIObserver;
+interface nsIPrompt;
+interface nsIAuthPrompt;
+interface nsISimpleEnumerator;
+interface nsIWebBrowserChrome;
+interface nsIWindowCreator;
+
+[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.
+      @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
+  */
+  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"
+%}