/* -*- Mode: IDL; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*-
 *
 * This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */

#include "nsISupports.idl"

interface nsIInterfaceRequestor;
interface nsIWebBrowserChrome;
interface nsIURIContentListener;
interface mozIDOMWindowProxy;
interface nsIWeakReference;

%{C++
namespace mozilla {
class OriginAttributes;
}
%}

[ref] native const_OriginAttributesRef(const mozilla::OriginAttributes);

/**
 * The nsIWebBrowser interface is implemented by web browser objects.
 * Embedders use this interface during initialisation to associate
 * the new web browser instance with the embedders chrome and
 * to register any listeners. The interface may also be used at runtime
 * to obtain the content DOM window and from that the rest of the DOM.
 */
[scriptable, builtinclass, uuid(4052b6da-4faa-4646-b3a1-7e16a01c2dc2)]
interface nsIWebBrowser : nsISupports
{
    /**
     * The chrome object associated with the browser instance. The embedder
     * must create one chrome object for <I>each</I> browser object
     * that is instantiated. The embedder must associate the two by setting
     * this property to point to the chrome object before creating the browser
     * window via the browser's <CODE>nsIBaseWindow</CODE> interface.
     *
     * The chrome may optionally implement <CODE>nsIInterfaceRequestor</CODE>,
     * <CODE>nsIWebBrowserChromeFocus</CODE>,
     * <CODE>nsIContextMenuListener</CODE> and
     * <CODE>nsITooltipListener</CODE> to receive additional notifications
     * from the browser object.
     *
     * The chrome object may optionally implement
     * <CODE>nsIWebProgressListener</CODE> to register a progress listener
     * object. If the implementation does this, it must also implement
     * <CODE>nsIWeakReference</CODE>.
     *
     * @note The implementation should not refcount the supplied chrome
     *       object; it should assume that a non <CODE>nullptr</CODE> value is
     *       always valid. The embedder must explicitly set this value back
     *       to nullptr if the chrome object is destroyed before the browser
     *       object.
     *
     * @see nsIBaseWindow
     * @see nsIWebBrowserChrome
     * @see nsIInterfaceRequestor
     * @see nsIWebBrowserChromeFocus
     * @see nsIContextMenuListener
     * @see nsITooltipListener
     * @see nsIWeakReference
     * @see nsIWebProgressListener
     */
    attribute nsIWebBrowserChrome containerWindow;

    /**
     * The top-level DOM window. The embedder may walk the entire
     * DOM starting from this value.
     */
    readonly attribute mozIDOMWindowProxy contentDOMWindow;

    /**
     * Set Origin Attributes on the nsIWebBrowser.
     * The Origin Attributes will be passed to the docshell once it has been
     * created
     */
    [noscript, notxpcom, nostdcall, binaryname(SetOriginAttributes)]
    void binarySetOriginAttributes(in const_OriginAttributesRef aOriginAttrs);
};