1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/embedding/browser/webBrowser/nsIWebBrowser.idl Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,146 @@
1.4 +/* -*- Mode: IDL; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*-
1.5 + *
1.6 + * This Source Code Form is subject to the terms of the Mozilla Public
1.7 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.8 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.9 +
1.10 +#include "nsISupports.idl"
1.11 +
1.12 +interface nsIInterfaceRequestor;
1.13 +interface nsIWebBrowserChrome;
1.14 +interface nsIURIContentListener;
1.15 +interface nsIDOMWindow;
1.16 +interface nsIWeakReference;
1.17 +
1.18 +/**
1.19 + * The nsIWebBrowser interface is implemented by web browser objects.
1.20 + * Embedders use this interface during initialisation to associate
1.21 + * the new web browser instance with the embedders chrome and
1.22 + * to register any listeners. The interface may also be used at runtime
1.23 + * to obtain the content DOM window and from that the rest of the DOM.
1.24 + */
1.25 +[scriptable, uuid(33e9d001-caab-4ba9-8961-54902f197202)]
1.26 +interface nsIWebBrowser : nsISupports
1.27 +{
1.28 + /**
1.29 + * Registers a listener of the type specified by the iid to receive
1.30 + * callbacks. The browser stores a weak reference to the listener
1.31 + * to avoid any circular dependencies.
1.32 + * Typically this method will be called to register an object
1.33 + * to receive <CODE>nsIWebProgressListener</CODE> or
1.34 + * <CODE>nsISHistoryListener</CODE> notifications in which case the
1.35 + * the IID is that of the interface.
1.36 + *
1.37 + * @param aListener The listener to be added.
1.38 + * @param aIID The IID of the interface that will be called
1.39 + * on the listener as appropriate.
1.40 + * @return <CODE>NS_OK</CODE> for successful registration;
1.41 + * <CODE>NS_ERROR_INVALID_ARG</CODE> if aIID is not
1.42 + * supposed to be registered using this method;
1.43 + * <CODE>NS_ERROR_FAILURE</CODE> either aListener did not
1.44 + * expose the interface specified by the IID, or some
1.45 + * other internal error occurred.
1.46 + *
1.47 + * @see removeWebBrowserListener
1.48 + * @see nsIWeakReference
1.49 + * @see nsIWebProgressListener
1.50 + * @see nsISHistoryListener
1.51 + *
1.52 + * @return <CODE>NS_OK</CODE>, listener was successfully added;
1.53 + * <CODE>NS_ERROR_INVALID_ARG</CODE>, one of the arguments was
1.54 + * invalid or the object did not implement the interface
1.55 + * specified by the IID.
1.56 + */
1.57 + void addWebBrowserListener(in nsIWeakReference aListener, in nsIIDRef aIID);
1.58 +
1.59 + /**
1.60 + * Removes a previously registered listener.
1.61 + *
1.62 + * @param aListener The listener to be removed.
1.63 + * @param aIID The IID of the interface on the listener that will
1.64 + * no longer be called.
1.65 + *
1.66 + * @return <CODE>NS_OK</CODE>, listener was successfully removed;
1.67 + * <CODE>NS_ERROR_INVALID_ARG</CODE> arguments was invalid or
1.68 + * the object did not implement the interface specified by the IID.
1.69 + *
1.70 + * @see addWebBrowserListener
1.71 + * @see nsIWeakReference
1.72 + */
1.73 + void removeWebBrowserListener(in nsIWeakReference aListener, in nsIIDRef aIID);
1.74 +
1.75 + /**
1.76 + * The chrome object associated with the browser instance. The embedder
1.77 + * must create one chrome object for <I>each</I> browser object
1.78 + * that is instantiated. The embedder must associate the two by setting
1.79 + * this property to point to the chrome object before creating the browser
1.80 + * window via the browser's <CODE>nsIBaseWindow</CODE> interface.
1.81 + *
1.82 + * The chrome object must also implement <CODE>nsIEmbeddingSiteWindow</CODE>.
1.83 + *
1.84 + * The chrome may optionally implement <CODE>nsIInterfaceRequestor</CODE>,
1.85 + * <CODE>nsIWebBrowserChromeFocus</CODE>,
1.86 + * <CODE>nsIContextMenuListener</CODE> and
1.87 + * <CODE>nsITooltipListener</CODE> to receive additional notifications
1.88 + * from the browser object.
1.89 + *
1.90 + * The chrome object may optionally implement <CODE>nsIWebProgressListener</CODE>
1.91 + * instead of explicitly calling <CODE>addWebBrowserListener</CODE> and
1.92 + * <CODE>removeWebBrowserListener</CODE> to register a progress listener
1.93 + * object. If the implementation does this, it must also implement
1.94 + * <CODE>nsIWeakReference</CODE>.
1.95 + *
1.96 + * @note The implementation should not refcount the supplied chrome
1.97 + * object; it should assume that a non <CODE>nullptr</CODE> value is
1.98 + * always valid. The embedder must explicitly set this value back
1.99 + * to nullptr if the chrome object is destroyed before the browser
1.100 + * object.
1.101 + *
1.102 + * @see nsIBaseWindow
1.103 + * @see nsIWebBrowserChrome
1.104 + * @see nsIEmbeddingSiteWindow
1.105 + * @see nsIInterfaceRequestor
1.106 + * @see nsIWebBrowserChromeFocus
1.107 + * @see nsIContextMenuListener
1.108 + * @see nsITooltipListener
1.109 + * @see nsIWeakReference
1.110 + * @see nsIWebProgressListener
1.111 + */
1.112 + attribute nsIWebBrowserChrome containerWindow;
1.113 +
1.114 + /**
1.115 + * URI content listener parent. The embedder may set this property to
1.116 + * their own implementation if they intend to override or prevent
1.117 + * how certain kinds of content are loaded.
1.118 + *
1.119 + * @note If this attribute is set to an object that implements
1.120 + * nsISupportsWeakReference, the implementation should get the
1.121 + * nsIWeakReference and hold that. Otherwise, the implementation
1.122 + * should not refcount this interface; it should assume that a non
1.123 + * null value is always valid. In that case, the embedder should
1.124 + * explicitly set this value back to null if the parent content
1.125 + * listener is destroyed before the browser object.
1.126 + *
1.127 + * @see nsIURIContentListener
1.128 + */
1.129 + attribute nsIURIContentListener parentURIContentListener;
1.130 +
1.131 + /**
1.132 + * The top-level DOM window. The embedder may walk the entire
1.133 + * DOM starting from this value.
1.134 + *
1.135 + * @see nsIDOMWindow
1.136 + */
1.137 + readonly attribute nsIDOMWindow contentDOMWindow;
1.138 +
1.139 + /**
1.140 + * Whether this web browser is active. Active means that it's visible
1.141 + * enough that we want to avoid certain optimizations like discarding
1.142 + * decoded image data and throttling the refresh driver. In Firefox,
1.143 + * this corresponds to the visible tab.
1.144 + *
1.145 + * Defaults to true. For optimal performance, set it to false when
1.146 + * appropriate.
1.147 + */
1.148 + attribute boolean isActive;
1.149 +};
