166 lines
6.7 KiB
Plaintext
166 lines
6.7 KiB
Plaintext
/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*-
|
|
*
|
|
* 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 Netscape are
|
|
* Copyright (C) 2001, Mozilla. All Rights Reserved.
|
|
|
|
* Contributor(s):
|
|
*/
|
|
|
|
/*
|
|
nsIWindowWatcher is the keeper of Gecko/DOM Windows. It maintains
|
|
maintains a traversable 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 does automatically keep an accurate list of extant
|
|
windows; windows need not be added or removed by hand (and there's no
|
|
interface for doing so).
|
|
Windows referenced will not be refcounted; the implementation will
|
|
claim no ownership. Since it's the nature of this service to always
|
|
hold a ("weak") reference to an open window, this requirement removes
|
|
a potential reference loop. It should be safe because it's a
|
|
design requirement that clients explicitly maintain |activeWindow|,
|
|
and that windows remove themselves from the service when they are closed.
|
|
*/
|
|
|
|
#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. null if not.
|
|
@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:
|
|
@param aSubject (parameter to aObserver::Observe) the window being
|
|
opened or closed, sent as an nsISupports
|
|
which can be QIed to an nsIDOMWindow.
|
|
@param aTopic (parameter to aObserver::Observe) a wstring, either
|
|
"domwindowopened" or "domwindowclosed".
|
|
@param someData (parameter to aObserver::Observe) 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.
|
|
*/
|
|
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}}
|
|
%}
|
|
|