PageRenderTime 8ms CodeModel.GetById 2ms app.highlight 3ms RepoModel.GetById 1ms app.codeStats 0ms

/gecko_sdk/idl/nsIWindowWatcher.idl

http://firefox-mac-pdf.googlecode.com/
IDL | 202 lines | 29 code | 23 blank | 150 comment | 0 complexity | 5f82f220d24c7b500ab92de0bbc58e9f MD5 | raw file
  1/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*-
  2 *
  3 * ***** BEGIN LICENSE BLOCK *****
  4 * Version: MPL 1.1/GPL 2.0/LGPL 2.1
  5 *
  6 * The contents of this file are subject to the Mozilla Public License Version
  7 * 1.1 (the "License"); you may not use this file except in compliance with
  8 * the License. You may obtain a copy of the License at
  9 * http://www.mozilla.org/MPL/
 10 *
 11 * Software distributed under the License is distributed on an "AS IS" basis,
 12 * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
 13 * for the specific language governing rights and limitations under the
 14 * License.
 15 *
 16 * The Original Code is mozilla.org code.
 17 *
 18 * The Initial Developer of the Original Code is
 19 * Netscape Communications, Inc.
 20 * Portions created by the Initial Developer are Copyright (C) 2001
 21 * the Initial Developer. All Rights Reserved.
 22 *
 23 * Contributor(s):
 24 *
 25 * Alternatively, the contents of this file may be used under the terms of
 26 * either the GNU General Public License Version 2 or later (the "GPL"), or
 27 * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
 28 * in which case the provisions of the GPL or the LGPL are applicable instead
 29 * of those above. If you wish to allow use of your version of this file only
 30 * under the terms of either the GPL or the LGPL, and not to allow others to
 31 * use your version of this file under the terms of the MPL, indicate your
 32 * decision by deleting the provisions above and replace them with the notice
 33 * and other provisions required by the GPL or the LGPL. If you do not delete
 34 * the provisions above, a recipient may use your version of this file under
 35 * the terms of any one of the MPL, the GPL or the LGPL.
 36 *
 37 * ***** END LICENSE BLOCK ***** */
 38
 39#include "nsISupports.idl"
 40
 41interface nsIDOMWindow;
 42interface nsIObserver;
 43interface nsIPrompt;
 44interface nsIAuthPrompt;
 45interface nsISimpleEnumerator;
 46interface nsIWebBrowserChrome;
 47interface nsIWindowCreator;
 48
 49
 50
 51/**
 52 * nsIWindowWatcher is the keeper of Gecko/DOM Windows. It maintains
 53 * a list of open top-level windows, and allows some operations on them.
 54
 55 * Usage notes:
 56
 57 *   This component has an |activeWindow| property. Clients may expect
 58 * this property to be always current, so to properly integrate this component
 59 * the application will need to keep it current by setting the property
 60 * as the active window changes.
 61 *   This component should not keep a (XPCOM) reference to any windows;
 62 * the implementation will claim no ownership. Windows must notify
 63 * this component when they are created or destroyed, so only a weak
 64 * reference is kept. Note that there is no interface for such notifications
 65 * (not a public one, anyway). This is taken care of both in Mozilla and
 66 * by common embedding code. Embedding clients need do nothing special
 67 * about that requirement.
 68 *   This component must be initialized at application startup by calling
 69 * setWindowCreator.
 70 *
 71 * @status FROZEN
 72 */
 73[scriptable, uuid(002286a8-494b-43b3-8ddd-49e3fc50622b)]
 74
 75interface nsIWindowWatcher : nsISupports {
 76
 77  /** Create a new window. It will automatically be added to our list
 78      (via addWindow()).
 79      @param aParent parent window, if any. Null if no parent.  If it is
 80             impossible to get to an nsIWebBrowserChrome from aParent, this
 81             method will effectively act as if aParent were null.
 82      @param aURL url to which to open the new window. Must already be
 83             escaped, if applicable. can be null.
 84      @param aName window name from JS window.open. can be null.  If a window
 85             with this name already exists, the openWindow call may just load
 86             aUrl in it (if aUrl is not null) and return it.
 87      @param aFeatures window features from JS window.open. can be null.
 88      @param aArguments extra argument(s) to the new window, to be attached
 89             as the |arguments| property. An nsISupportsArray will be
 90             unwound into multiple arguments (but not recursively!).
 91             can be null.
 92      @return the new window
 93
 94      @note This method may examine the JS context stack for purposes of
 95            determining the security context to use for the search for a given
 96            window named aName.
 97      @note This method should try to set the default charset for the new
 98            window to the default charset of aParent.  This is not guaranteed,
 99            however.
100      @note This method may dispatch a "toplevel-window-ready" notification
101            via nsIObserverService if the window did not already exist.
102  */
103  nsIDOMWindow openWindow(in nsIDOMWindow aParent, in string aUrl,
104               in string aName, in string aFeatures,
105               in nsISupports aArguments);
106
107  /** Clients of this service can register themselves to be notified
108      when a window is opened or closed (added to or removed from this
109      service). This method adds an aObserver to the list of objects
110      to be notified.
111      @param aObserver the object to be notified when windows are
112                       opened or closed. Its Observe method will be
113                       called with the following parameters:
114
115      aObserver::Observe interprets its parameters so:
116      aSubject the window being opened or closed, sent as an nsISupports
117               which can be QIed to an nsIDOMWindow.
118      aTopic   a wstring, either "domwindowopened" or "domwindowclosed".
119      someData not used.
120  */
121  void registerNotification(in nsIObserver aObserver);
122
123  /** Clients of this service can register themselves to be notified
124      when a window is opened or closed (added to or removed from this
125      service). This method removes an aObserver from the list of objects
126      to be notified.
127      @param aObserver the observer to be removed.
128  */
129  void unregisterNotification(in nsIObserver aObserver);
130
131  /** Get an iterator for currently open windows in the order they were opened,
132      guaranteeing that each will be visited exactly once.
133      @return an enumerator which will itself return nsISupports objects which
134              can be QIed to an nsIDOMWindow
135  */
136
137  nsISimpleEnumerator getWindowEnumerator();
138
139  /** Return a newly created nsIPrompt implementation.
140      @param aParent the parent window used for posing alerts. can be null.
141      @return a new nsIPrompt object
142  */
143
144  nsIPrompt getNewPrompter(in nsIDOMWindow aParent);
145
146  /** Return a newly created nsIAuthPrompt implementation.
147      @param aParent the parent window used for posing alerts. can be null.
148      @return a new nsIAuthPrompt object
149  */
150
151  nsIAuthPrompt getNewAuthPrompter(in nsIDOMWindow aParent);
152
153  /** Set the window creator callback. It must be filled in by the app.
154      openWindow will use it to create new windows.
155      @param creator the callback. if null, the callback will be cleared
156                     and window creation capabilities lost.
157  */
158  void setWindowCreator(in nsIWindowCreator creator);
159
160
161  /** Retrieve the chrome window mapped to the given DOM window. Window
162      Watcher keeps a list of all top-level DOM windows currently open,
163      along with their corresponding chrome interfaces. Since DOM Windows
164      lack a (public) means of retrieving their corresponding chrome,
165      this method will do that.
166      @param aWindow the DOM window whose chrome window the caller needs
167      @return the corresponding chrome window
168  */
169  nsIWebBrowserChrome getChromeForWindow(in nsIDOMWindow aWindow);
170
171  /**
172      Retrieve an existing window (or frame).
173      @param aTargetName the window name
174      @param aCurrentWindow a starting point in the window hierarchy to
175                            begin the search.  If null, each toplevel window
176                            will be searched.
177
178      Note: This method will search all open windows for any window or
179      frame with the given window name. Make sure you understand the
180      security implications of this before using this method!
181  */
182  nsIDOMWindow getWindowByName(in wstring aTargetName,
183                               in nsIDOMWindow aCurrentWindow);
184
185  /** The Watcher serves as a global storage facility for the current active
186      (frontmost non-floating-palette-type) window, storing and returning
187      it on demand. Users must keep this attribute current, including after
188      the topmost window is closed. This attribute obviously can return null
189      if no windows are open, but should otherwise always return a valid
190      window.
191  */
192  attribute nsIDOMWindow activeWindow;
193
194};
195
196%{C++
197// {002286a8-494b-43b3-8ddd-49e3fc50622b}
198#define NS_WINDOWWATCHER_IID \
199 {0x002286a8, 0x494b, 0x43b3, {0x8d, 0xdd, 0x49, 0xe3, 0xfc, 0x50, 0x62, 0x2b}}
200
201#define NS_WINDOWWATCHER_CONTRACTID "@mozilla.org/embedcomp/window-watcher;1"
202%}