/* -*- 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;
interface nsIDOMWindow;
interface nsIWeakReference;

/**
 * The nsIWebBrowser
 *
 * @status UNDER_REVIEW
 */

[scriptable, uuid(69E5DF00-7B8B-11d3-AF61-00A024FFC08C)]
interface nsIWebBrowser : nsISupports
{
	/* 
    Registers a listener to receive callbacks.

    @param aListener - The listener interface pointer who's methods will be
                       called as defined by the semantics of the listener 
                       interface itself (specified by the IID).

    @param aIID      - The IID that aListener will be registered as.
    
    @return          - NS_OK, successful registration.
                       NS_ERROR_INVALID_ARG, aIID is not supposed to be 
                         registered using this method.
                       NS_ERROR_FAILURE, either aListener could not be QI'd
                         for the specified IID, or some other internal error
                         occurred.
	*/
	void addWebBrowserListener(in nsIWeakReference aListener, in nsIIDRef aIID);

    /*
    Removes a previously registered listener.

    @param aListener - The listener interface pointer to be removed as a listener.

    @param aIID      - The IID that aListener should be removed as a listener
                       for.

    @return          - NS_OK, successful removal
                       NS_ERROR_INVALID_ARG, aIID is not supported for removal.
                       NS_ERROR_FAILURE, either aListener could not be QI'd
                         for the specified IID, or some other internal error
                         occurred.
    */
	void removeWebBrowserListener(in nsIWeakReference aListener, in nsIIDRef aIID);

	/*
	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;

   /*
   The top-level DOM window (nsIDOMWindow)
   */
   readonly attribute nsIDOMWindow contentDOMWindow;
};