← Back to branch summary

~ubuntu-branches/ubuntu/precise/kompozer/precise

« back to all changes in this revision

Viewing changes to mozilla/embedding/browser/webBrowser/nsIWebBrowser.idl

  • Committer: Bazaar Package Importer
  • Author(s): Anthony Yarusso
  • Date: 2007-08-27 01:11:03 UTC
  • Revision ID: james.westby@ubuntu.com-20070827011103-2jgf4s6532gqu2ka
Tags: upstream-0.7.10
Import upstream version 0.7.10

Show diffs side-by-side

added added

removed removed

Lines of Context:
mozilla/embedding/browser/webBrowser/nsIWebBrowser.idl
 
1
/* -*- Mode: IDL; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*-
 
2
 *
 
3
 * The contents of this file are subject to the Mozilla Public
 
4
 * License Version 1.1 (the "License"); you may not use this file
 
5
 * except in compliance with the License. You may obtain a copy of
 
6
 * the License at http://www.mozilla.org/MPL/
 
7
 * 
 
8
 * Software distributed under the License is distributed on an "AS
 
9
 * IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or
 
10
 * implied. See the License for the specific language governing
 
11
 * rights and limitations under the License.
 
12
 * 
 
13
 * The Original Code is the Mozilla browser.
 
14
 * 
 
15
 * The Initial Developer of the Original Code is Netscape
 
16
 * Communications, Inc.  Portions created by Netscape are
 
17
 * Copyright (C) 1999, Mozilla.  All Rights Reserved.
 
18
 * 
 
19
 * Contributor(s):
 
20
 *   Travis Bogard <travis@netscape.com>
 
21
 */
 
22
 
 
23
#include "nsISupports.idl"
 
24
 
 
25
interface nsIInterfaceRequestor;
 
26
interface nsIWebBrowserChrome;
 
27
interface nsIURIContentListener;
 
28
interface nsIDOMWindow;
 
29
interface nsIWeakReference;
 
30
 
 
31
/**
 
32
 * The nsIWebBrowser interface is implemented by web browser objects.
 
33
 * Embedders use this interface during initialisation to associate
 
34
 * the new web browser instance with the embedders chrome and
 
35
 * to register any listeners. The interface may also be used at runtime
 
36
 * to obtain the content DOM window and from that the rest of the DOM.
 
37
 *
 
38
 * @status FROZEN
 
39
 */
 
40
[scriptable, uuid(69E5DF00-7B8B-11d3-AF61-00A024FFC08C)]
 
41
interface nsIWebBrowser : nsISupports
 
42
{
 
43
    /**
 
44
     * Registers a listener of the type specified by the iid to receive
 
45
     * callbacks. The browser stores a weak reference to the listener
 
46
     * to avoid any circular dependencies.
 
47
     * Typically this method will be called to register an object
 
48
     * to receive <CODE>nsIWebProgressListener</CODE> or 
 
49
     * <CODE>nsISHistoryListener</CODE> notifications in which case the
 
50
     * the IID is that of the interface.
 
51
     *
 
52
     * @param aListener The listener to be added.
 
53
     * @param aIID      The IID of the interface that will be called
 
54
     *                  on the listener as appropriate.
 
55
     * @return          <CODE>NS_OK</CODE> for successful registration;
 
56
     *                  <CODE>NS_ERROR_INVALID_ARG</CODE> if aIID is not
 
57
     *                  supposed to be registered using this method;
 
58
     *                  <CODE>NS_ERROR_FAILURE</CODE> either aListener did not
 
59
     *                  expose the interface specified by the IID, or some
 
60
     *                  other internal error occurred.
 
61
     *
 
62
     * @see removeWebBrowserListener
 
63
     * @see nsIWeakReference
 
64
     * @see nsIWebProgressListener
 
65
     * @see nsISHistoryListener
 
66
     *
 
67
     * @return <CODE>NS_OK</CODE>, listener was successfully added;
 
68
     *         <CODE>NS_ERROR_INVALID_ARG</CODE>, one of the arguments was
 
69
     *         invalid or the object did not implement the interface
 
70
     *         specified by the IID.
 
71
     */
 
72
    void addWebBrowserListener(in nsIWeakReference aListener, in nsIIDRef aIID);
 
73
 
 
74
    /**
 
75
     * Removes a previously registered listener.
 
76
     *
 
77
     * @param aListener The listener to be removed.
 
78
     * @param aIID      The IID of the interface on the listener that will
 
79
     *                  no longer be called.
 
80
     *
 
81
     * @return <CODE>NS_OK</CODE>, listener was successfully removed;
 
82
     *         <CODE>NS_ERROR_INVALID_ARG</CODE> arguments was invalid or
 
83
     *         the object did not implement the interface specified by the IID.
 
84
     *
 
85
     * @see addWebBrowserListener
 
86
     * @see nsIWeakReference
 
87
     */
 
88
    void removeWebBrowserListener(in nsIWeakReference aListener, in nsIIDRef aIID);
 
89
 
 
90
    /**
 
91
     * The chrome object associated with the browser instance. The embedder
 
92
     * must create one chrome object for <I>each</I> browser object
 
93
     * that is instantiated. The embedder must associate the two by setting
 
94
     * this property to point to the chrome object before creating the browser
 
95
     * window via the browser's <CODE>nsIBaseWindow</CODE> interface. 
 
96
     *
 
97
     * The chrome object must also implement <CODE>nsIEmbeddingSiteWindow</CODE>.
 
98
     *
 
99
     * The chrome may optionally implement <CODE>nsIInterfaceRequestor</CODE>,
 
100
     * <CODE>nsIWebBrowserChromeFocus</CODE>,
 
101
     * <CODE>nsIContextMenuListener</CODE> and
 
102
     * <CODE>nsITooltipListener</CODE> to receive additional notifications
 
103
     * from the browser object.
 
104
     *
 
105
     * The chrome object may optionally implement <CODE>nsIWebProgressListener</CODE> 
 
106
     * instead of explicitly calling <CODE>addWebBrowserListener</CODE> and
 
107
     * <CODE>removeWebBrowserListener</CODE> to register a progress listener
 
108
     * object. If the implementation does this, it must also implement
 
109
     * <CODE>nsIWeakReference</CODE>.
 
110
     * 
 
111
     * @note The implementation should not refcount the supplied chrome
 
112
     *       object; it should assume that a non <CODE>nsnull</CODE> value is
 
113
     *       always valid. The embedder must explicitly set this value back
 
114
     *       to nsnull if the chrome object is destroyed before the browser
 
115
     *       object.
 
116
     *
 
117
     * @see nsIBaseWindow
 
118
     * @see nsIWebBrowserChrome
 
119
     * @see nsIEmbeddingSiteWindow
 
120
     * @see nsIInterfaceRequestor
 
121
     * @see nsIWebBrowserChromeFocus
 
122
     * @see nsIContextMenuListener
 
123
     * @see nsITooltipListener
 
124
     * @see nsIWeakReference
 
125
     * @see nsIWebProgressListener
 
126
     */
 
127
    attribute nsIWebBrowserChrome containerWindow;
 
128
 
 
129
    /**
 
130
     * URI content listener parent. The embedder may set this property to
 
131
     * their own implementation if they intend to override or prevent
 
132
     * how certain kinds of content are loaded.
 
133
     *
 
134
     * @note The implementation should not refcount this interface; it
 
135
     *       should assume that a non nsnull value is always valid.
 
136
     *       The embedder should explicitly set this value back to nsnull
 
137
     *       if the parent content listener is destroyed before the
 
138
     *       browser object.
 
139
     *
 
140
     * @see nsIURIContentListener
 
141
     */
 
142
    attribute nsIURIContentListener parentURIContentListener;
 
143
 
 
144
    /**
 
145
     * The top-level DOM window. The embedder may walk the entire
 
146
     * DOM starting from this value.
 
147
     *
 
148
     * @see nsIDOMWindow
 
149
     */
 
150
    readonly attribute nsIDOMWindow contentDOMWindow;
 
151
};