The Tor Browser / file comparison

comparison: embedding/browser/webBrowser/nsIWebBrowser.idl

embedding/browser/webBrowser/nsIWebBrowser.idl

branch
TOR_BUG_9701
changeset 15
b8a032363ba2
equal deleted inserted replaced
-1:000000000000 0:0bd5705bc6c5
1 /* -*- Mode: IDL; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*-
2 *
3 * This Source Code Form is subject to the terms of the Mozilla Public
4 * License, v. 2.0. If a copy of the MPL was not distributed with this
5 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
6
7 #include "nsISupports.idl"
8
9 interface nsIInterfaceRequestor;
10 interface nsIWebBrowserChrome;
11 interface nsIURIContentListener;
12 interface nsIDOMWindow;
13 interface nsIWeakReference;
14
15 /**
16 * The nsIWebBrowser interface is implemented by web browser objects.
17 * Embedders use this interface during initialisation to associate
18 * the new web browser instance with the embedders chrome and
19 * to register any listeners. The interface may also be used at runtime
20 * to obtain the content DOM window and from that the rest of the DOM.
21 */
22 [scriptable, uuid(33e9d001-caab-4ba9-8961-54902f197202)]
23 interface nsIWebBrowser : nsISupports
24 {
25 /**
26 * Registers a listener of the type specified by the iid to receive
27 * callbacks. The browser stores a weak reference to the listener
28 * to avoid any circular dependencies.
29 * Typically this method will be called to register an object
30 * to receive <CODE>nsIWebProgressListener</CODE> or
31 * <CODE>nsISHistoryListener</CODE> notifications in which case the
32 * the IID is that of the interface.
33 *
34 * @param aListener The listener to be added.
35 * @param aIID The IID of the interface that will be called
36 * on the listener as appropriate.
37 * @return <CODE>NS_OK</CODE> for successful registration;
38 * <CODE>NS_ERROR_INVALID_ARG</CODE> if aIID is not
39 * supposed to be registered using this method;
40 * <CODE>NS_ERROR_FAILURE</CODE> either aListener did not
41 * expose the interface specified by the IID, or some
42 * other internal error occurred.
43 *
44 * @see removeWebBrowserListener
45 * @see nsIWeakReference
46 * @see nsIWebProgressListener
47 * @see nsISHistoryListener
48 *
49 * @return <CODE>NS_OK</CODE>, listener was successfully added;
50 * <CODE>NS_ERROR_INVALID_ARG</CODE>, one of the arguments was
51 * invalid or the object did not implement the interface
52 * specified by the IID.
53 */
54 void addWebBrowserListener(in nsIWeakReference aListener, in nsIIDRef aIID);
55
56 /**
57 * Removes a previously registered listener.
58 *
59 * @param aListener The listener to be removed.
60 * @param aIID The IID of the interface on the listener that will
61 * no longer be called.
62 *
63 * @return <CODE>NS_OK</CODE>, listener was successfully removed;
64 * <CODE>NS_ERROR_INVALID_ARG</CODE> arguments was invalid or
65 * the object did not implement the interface specified by the IID.
66 *
67 * @see addWebBrowserListener
68 * @see nsIWeakReference
69 */
70 void removeWebBrowserListener(in nsIWeakReference aListener, in nsIIDRef aIID);
71
72 /**
73 * The chrome object associated with the browser instance. The embedder
74 * must create one chrome object for <I>each</I> browser object
75 * that is instantiated. The embedder must associate the two by setting
76 * this property to point to the chrome object before creating the browser
77 * window via the browser's <CODE>nsIBaseWindow</CODE> interface.
78 *
79 * The chrome object must also implement <CODE>nsIEmbeddingSiteWindow</CODE>.
80 *
81 * The chrome may optionally implement <CODE>nsIInterfaceRequestor</CODE>,
82 * <CODE>nsIWebBrowserChromeFocus</CODE>,
83 * <CODE>nsIContextMenuListener</CODE> and
84 * <CODE>nsITooltipListener</CODE> to receive additional notifications
85 * from the browser object.
86 *
87 * The chrome object may optionally implement <CODE>nsIWebProgressListener</CODE>
88 * instead of explicitly calling <CODE>addWebBrowserListener</CODE> and
89 * <CODE>removeWebBrowserListener</CODE> to register a progress listener
90 * object. If the implementation does this, it must also implement
91 * <CODE>nsIWeakReference</CODE>.
92 *
93 * @note The implementation should not refcount the supplied chrome
94 * object; it should assume that a non <CODE>nullptr</CODE> value is
95 * always valid. The embedder must explicitly set this value back
96 * to nullptr if the chrome object is destroyed before the browser
97 * object.
98 *
99 * @see nsIBaseWindow
100 * @see nsIWebBrowserChrome
101 * @see nsIEmbeddingSiteWindow
102 * @see nsIInterfaceRequestor
103 * @see nsIWebBrowserChromeFocus
104 * @see nsIContextMenuListener
105 * @see nsITooltipListener
106 * @see nsIWeakReference
107 * @see nsIWebProgressListener
108 */
109 attribute nsIWebBrowserChrome containerWindow;
110
111 /**
112 * URI content listener parent. The embedder may set this property to
113 * their own implementation if they intend to override or prevent
114 * how certain kinds of content are loaded.
115 *
116 * @note If this attribute is set to an object that implements
117 * nsISupportsWeakReference, the implementation should get the
118 * nsIWeakReference and hold that. Otherwise, the implementation
119 * should not refcount this interface; it should assume that a non
120 * null value is always valid. In that case, the embedder should
121 * explicitly set this value back to null if the parent content
122 * listener is destroyed before the browser object.
123 *
124 * @see nsIURIContentListener
125 */
126 attribute nsIURIContentListener parentURIContentListener;
127
128 /**
129 * The top-level DOM window. The embedder may walk the entire
130 * DOM starting from this value.
131 *
132 * @see nsIDOMWindow
133 */
134 readonly attribute nsIDOMWindow contentDOMWindow;
135
136 /**
137 * Whether this web browser is active. Active means that it's visible
138 * enough that we want to avoid certain optimizations like discarding
139 * decoded image data and throttling the refresh driver. In Firefox,
140 * this corresponds to the visible tab.
141 *
142 * Defaults to true. For optimal performance, set it to false when
143 * appropriate.
144 */
145 attribute boolean isActive;
146 };

Mercurial Repository: The Tor Browser

Europalab SCM Repository Server

mercurial