nsIWindowWatcher 编辑

 

embedding/components/windowwatcher/public/nsIWindowWatcher.idlScriptable This interface is the keeper of Gecko/DOM Windows. It maintains a list of open top-level windows, and allows some operations on them. Inherits from: nsISupports Last changed in Gecko 0.9.6

 

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().

Method overview

nsIWebBrowserChrome getChromeForWindow(in nsIDOMWindow aWindow);

nsIAuthPrompt getNewAuthPrompter(in nsIDOMWindow aParent);

nsIPrompt getNewPrompter(in nsIDOMWindow aParent);

nsIDOMWindow getWindowByName(in wstring aTargetName, in nsIDOMWindow aCurrentWindow);

nsISimpleEnumerator getWindowEnumerator();

nsIDOMWindow openWindow(in nsIDOMWindow aParent, in string aUrl, in string aName, in string aFeatures, in nsISupports aArguments);

void registerNotification(in nsIObserver aObserver);

void setWindowCreator(in nsIWindowCreator creator);

void unregisterNotification(in nsIObserver aObserver);

Attributes

Attribute	Type	Description
activeWindow	nsIDOMWindow	The Watcher serves as a global storage facility for the current active (front most 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 will be null if the active window is not an nsIDOMWindow; for example, if the active window is an alert.

Methods

getChromeForWindow()

Retrieve the chrome window mapped to the given DOM window. nsIWindowWatcher 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.

nsIWebBrowserChrome getChromeForWindow(
  in nsIDOMWindow aWindow
);

Parameters

aWindow

The nsIDOMWindow whose chrome window the caller needs.

Return value

An nsIWebBrowserChrome object for the corresponding chrome window

getNewAuthPrompter()

Return a newly created nsIAuthPrompt implementation.

nsIAuthPrompt getNewAuthPrompter(
  in nsIDOMWindow aParent
);

Parameters

aParent

The parent window used for posing alerts. can be null.

Return value

A new nsIAuthPrompt object.

getNewPrompter()

Return a newly created nsIPrompt implementation.

nsIPrompt getNewPrompter(
  in nsIDOMWindow aParent
);

Parameters

aParent

The parent nsIDOMWindow used for posing alerts. Can be null.

Return value

A new nsIPrompt object.

getWindowByName()

Retrieve an existing window (or frame).

 

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
);

Parameters

aTargetName

The window name.

aCurrentWindow

The nsIDOMWindow starting point in the window hierarchy to begin the search. If null, each top level window will be searched.

Return value

The nsIDOMWindow with the target name.

getWindowEnumerator()

Get an nsISimpleEnumerator for currently open windows in the order they were opened, guaranteeing that each will be visited exactly once.

nsISimpleEnumerator getWindowEnumerator();

Parameters

None.

Return value

An nsISimpleEnumerator which will itself return nsISupports objects which can be nsISupports.QueryInterface() (QueryInterfaced) to an nsIDOMWindow.

openWindow()

Creates a new window. It will automatically be added to our list.

 

Note: This method may examine the Javascript context stack for purposes of determining the security context to use for the search for a given window named aName.

 

 

Note: This method will 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.

 

 

Note: Supported nsISupportsPrimitive objects will be reflected into window.arguments as the base type, however ID, void and 64-bit primitive types are not currently supported and will reflect into window.arguments as null.

 

nsIDOMWindow openWindow(
  in nsIDOMWindow aParent,
  in string aUrl,
  in string aName,
  in string aFeatures,
  in nsISupports aArguments
);

Parameters

aParent

The 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.

aUrl

The url to open in the new window. Must already be escaped, if applicable. Can be null.

aName

A window name assigned using Window interface's open() method loads the specified resource into the browsing context (window, <iframe> or tab) with the specified name. If the name doesn't exist, then a new window is opened and the specified resource is loaded into its browsing context.">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.

aFeatures

Window features. See Window interface's open() method loads the specified resource into the browsing context (window, <iframe> or tab) with the specified name. If the name doesn't exist, then a new window is opened and the specified resource is loaded into its browsing context.">window.open for details. Can be null. List of Feature Options

aArguments

Extra argument(s) to be attached to the new window as the window.arguments property. An nsISupportsArray will be unwound into multiple arguments (but not recursively!). Can be null, in which case the window.arguments property will not be set on the new window. As of Gecko 1.9 alpha 1, can also be an nsIArray instead.

Return value

An nsIDOMWindow for the opened window.

Example

For example, in a XUL application or Mozilla extension, if the window object is unavailable (for example, when opening a window from XPCOM component code), you might want to use this interface for opening a new window:

 var ww = Components.classes["@mozilla.org/embedcomp/window-watcher;1"]
                    .getService(Components.interfaces.nsIWindowWatcher);
 var win = ww.openWindow(null, "chrome://myextension/content/about.xul",
                         "aboutMyExtension", "chrome,centerscreen", null);

Note: Versions of Gecko before Gecko 2.0 would ignore some of the chrome flags when opening a chrome window without an opener window, instead behaving as if the "all" flag was present. This was fixed in bug 509124.

registerNotification()

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 nsIObserver to the list of objects to be notified.

void registerNotification(
  in nsIObserver aObserver
);

Parameters

Note: Be careful about generating open/close window events inside nsIObserver.observe(). For example the following code will block the system because it will open windows continuously:

function MyWindowObserver() {
  this.observe=function(aSubject, aTopic, aData) {
    alert("window event: " + aTopic)
    //and this is where the bugs origins because opening this alert will cause a window-open
    //event and the call of this method again (forever)
  }
}
var ww = Components.classes["@mozilla.org/embedcomp/window-watcher;1"]
              .getService(Components.interfaces.nsIWindowWatcher);
ww.registerNotification(new MyWindowObserver())
alert("") //generate the first window-open event

aObserver

The nsIObserver to be notified when windows are opened or closed. aObserver should implement an observe method, which will be called with the following parameters:

• aSubject - the window being opened or closed, sent as an nsISupports which can be nsISupports.QueryInterface() (QueryInterfaced) to an nsIDOMWindow.
• aTopic - a wstring, either "domwindowopened" or "domwindowclosed".
• aData - not used.

setWindowCreator()

Set the window creator callback. It must be filled in by the app. openWindow() will use it to create new windows.

void setWindowCreator(
  in nsIWindowCreator creator
);

Parameters

creator

The nsIWindowCreator callback. If this is null the callback will be cleared and window creation capabilities lost.

unregisterNotification()

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 nsIObserver from the list of objects to be notified.

void unregisterNotification(
  in nsIObserver aObserver
);

Parameters

aObserver

the nsIObserver to be removed.