/* -*- Mode: IDL; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*-
 *
 * 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 the Mozilla browser.
 * 
 * The Initial Developer of the Original Code is Netscape
 * Communications, Inc.  Portions created by Netscape are
 * Copyright (C) 1999, Mozilla.  All Rights Reserved.
 * 
 * Contributor(s):
 *   Travis Bogard <travis@netscape.com>
 */

#include "nsISupports.idl"

interface nsIInterfaceRequestor;
interface nsIWebBrowserChrome;
interface nsIURIContentListener;

/**
 * The nsIWebBrowser
 */

[scriptable, uuid(69E5DF00-7B8B-11d3-AF61-00A024FFC08C)]
interface nsIWebBrowser : nsISupports
{
	/*
	Registers a webBrowserListener to receive queries for listener interfaces.
	This allows an embedding app to hook itself up to handle various listeners
	that nsWebBrowser supports throwing.  This process allows multiple people
	to register a listeners of the nsWebBrowser.  Each one has the option
	to handle only certain interfaces.  The callback process of
	nsIWebBrowserListener allows us to dynamically add new listener interfaces
	without having to add additional Add/RemoveFooListener().

	@param listener - The listener interface to be called when a specific 
		listener interface is needed.

	@return	NS_OK - Listener was registered successfully.
				NS_ERROR_INVALID_ARG - The listener passed in was either nsnull, 
						or was already registered with this listener interface.
	 */
	void addWebBrowserListener(in nsIInterfaceRequestor listener);

	/* 
	Removes a previously registered webBrowserListener.
		
	@param listener - The listener interface previously registered with 
			addListener() this may be nsnull if a valid cookie is provided.

	@return	NS_OK - Listener was successfully unregistered.
				NS_ERROR_INVALID_ARG - Neither the cookie nor the listener point
					to a previously registered listener.
	*/
	void removeWebBrowserListener(in nsIInterfaceRequestor listener);

	/*
	This is the top level window embedding the browser.  The object passed in
	will be QI'd and used for setting positioning, chrome elements, etc of the
	containing window.  This interface is implemented by the embedding app.
	The topLevelWindow object will be QId for nsIInterfaceRequestor, if it 
	is found, it will be quiried first before querying the objects in the 
	webBrowserListener list.  Implementations of this interface should
	not refcount the topLevelWindow as it is considered the owner of the browser
	window.  That therefore means that when the topLevelWindow goes away, it 
	must set topLevelWindow to nsnull.
	*/
	attribute nsIWebBrowserChrome containerWindow;

	/*
	URI content listener parent.  This is not refcounted and is assumed to be
	nulled out by the parent when the parent is going away.
	*/
	attribute nsIURIContentListener parentURIContentListener;
};