The Tor Browser / file comparison

comparison: embedding/components/windowwatcher/public/nsIWindowWatcher.idl

embedding/components/windowwatcher/public/nsIWindowWatcher.idl

branch
TOR_BUG_9701
changeset 15
b8a032363ba2
equal deleted inserted replaced
-1:000000000000 0:9ef820c9eacb
1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*-
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 #include "nsISupports.idl"
8
9 interface nsIDOMWindow;
10 interface nsIObserver;
11 interface nsIPrompt;
12 interface nsIAuthPrompt;
13 interface nsISimpleEnumerator;
14 interface nsIWebBrowserChrome;
15 interface nsIWindowCreator;
16
17
18
19 /**
20 * nsIWindowWatcher is the keeper of Gecko/DOM Windows. It maintains
21 * a list of open top-level windows, and allows some operations on them.
22
23 * Usage notes:
24
25 * This component has an |activeWindow| property. Clients may expect
26 * this property to be always current, so to properly integrate this component
27 * the application will need to keep it current by setting the property
28 * as the active window changes.
29 * This component should not keep a (XPCOM) reference to any windows;
30 * the implementation will claim no ownership. Windows must notify
31 * this component when they are created or destroyed, so only a weak
32 * reference is kept. Note that there is no interface for such notifications
33 * (not a public one, anyway). This is taken care of both in Mozilla and
34 * by common embedding code. Embedding clients need do nothing special
35 * about that requirement.
36 * This component must be initialized at application startup by calling
37 * setWindowCreator.
38 */
39 [scriptable, uuid(67bc1691-fbaf-484a-a15b-c96212b45034)]
40 interface nsIWindowWatcher : nsISupports {
41
42 /** Create a new window. It will automatically be added to our list
43 (via addWindow()).
44 @param aParent parent window, if any. Null if no parent. If it is
45 impossible to get to an nsIWebBrowserChrome from aParent, this
46 method will effectively act as if aParent were null.
47 @param aURL url to which to open the new window. Must already be
48 escaped, if applicable. can be null.
49 @param aName window name from JS window.open. can be null. If a window
50 with this name already exists, the openWindow call may just load
51 aUrl in it (if aUrl is not null) and return it.
52 @param aFeatures window features from JS window.open. can be null.
53 @param aArguments extra argument(s) to the new window, to be attached
54 as the |arguments| property. An nsISupportsArray will be
55 unwound into multiple arguments (but not recursively!).
56 can be null.
57 @return the new window
58
59 @note This method may examine the JS context stack for purposes of
60 determining the security context to use for the search for a given
61 window named aName.
62 @note This method should try to set the default charset for the new
63 window to the default charset of aParent. This is not guaranteed,
64 however.
65 @note This method may dispatch a "toplevel-window-ready" notification
66 via nsIObserverService if the window did not already exist.
67 */
68 nsIDOMWindow openWindow(in nsIDOMWindow aParent, in string aUrl,
69 in string aName, in string aFeatures,
70 in nsISupports aArguments);
71
72 /** Clients of this service can register themselves to be notified
73 when a window is opened or closed (added to or removed from this
74 service). This method adds an aObserver to the list of objects
75 to be notified.
76 @param aObserver the object to be notified when windows are
77 opened or closed. Its Observe method will be
78 called with the following parameters:
79
80 aObserver::Observe interprets its parameters so:
81 aSubject the window being opened or closed, sent as an nsISupports
82 which can be QIed to an nsIDOMWindow.
83 aTopic a wstring, either "domwindowopened" or "domwindowclosed".
84 someData not used.
85 */
86 void registerNotification(in nsIObserver aObserver);
87
88 /** Clients of this service can register themselves to be notified
89 when a window is opened or closed (added to or removed from this
90 service). This method removes an aObserver from the list of objects
91 to be notified.
92 @param aObserver the observer to be removed.
93 */
94 void unregisterNotification(in nsIObserver aObserver);
95
96 /** Get an iterator for currently open windows in the order they were opened,
97 guaranteeing that each will be visited exactly once.
98 @return an enumerator which will itself return nsISupports objects which
99 can be QIed to an nsIDOMWindow
100 */
101
102 nsISimpleEnumerator getWindowEnumerator();
103
104 /** Return a newly created nsIPrompt implementation.
105 @param aParent the parent window used for posing alerts. can be null.
106 @return a new nsIPrompt object
107 */
108
109 nsIPrompt getNewPrompter(in nsIDOMWindow aParent);
110
111 /** Return a newly created nsIAuthPrompt implementation.
112 @param aParent the parent window used for posing alerts. can be null.
113 @return a new nsIAuthPrompt object
114 */
115
116 nsIAuthPrompt getNewAuthPrompter(in nsIDOMWindow aParent);
117
118 /** Set the window creator callback. It must be filled in by the app.
119 openWindow will use it to create new windows.
120 @param creator the callback. if null, the callback will be cleared
121 and window creation capabilities lost.
122 */
123 void setWindowCreator(in nsIWindowCreator creator);
124
125 /** Returns true if a window creator callback has been set, false otherwise.
126 */
127 boolean hasWindowCreator();
128
129
130 /** Retrieve the chrome window mapped to the given DOM window. Window
131 Watcher keeps a list of all top-level DOM windows currently open,
132 along with their corresponding chrome interfaces. Since DOM Windows
133 lack a (public) means of retrieving their corresponding chrome,
134 this method will do that.
135 @param aWindow the DOM window whose chrome window the caller needs
136 @return the corresponding chrome window
137 */
138 nsIWebBrowserChrome getChromeForWindow(in nsIDOMWindow aWindow);
139
140 /**
141 Retrieve an existing window (or frame).
142 @param aTargetName the window name
143 @param aCurrentWindow a starting point in the window hierarchy to
144 begin the search. If null, each toplevel window
145 will be searched.
146
147 Note: This method will search all open windows for any window or
148 frame with the given window name. Make sure you understand the
149 security implications of this before using this method!
150 */
151 nsIDOMWindow getWindowByName(in wstring aTargetName,
152 in nsIDOMWindow aCurrentWindow);
153
154 /** The Watcher serves as a global storage facility for the current active
155 (frontmost non-floating-palette-type) window, storing and returning
156 it on demand. Users must keep this attribute current, including after
157 the topmost window is closed. This attribute obviously can return null
158 if no windows are open, but should otherwise always return a valid
159 window.
160 */
161 attribute nsIDOMWindow activeWindow;
162
163 };
164
165 %{C++
166 #define NS_WINDOWWATCHER_CONTRACTID "@mozilla.org/embedcomp/window-watcher;1"
167 %}

Mercurial Repository: The Tor Browser

Europalab SCM Repository Server

mercurial