summaryrefslogtreecommitdiffstats
path: root/dom/base/nsIImageLoadingContent.idl
blob: cdb2f10f2a2fc66793f148ee5369f75c9b3e7e8c (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
/* -*- Mode: C++; tab-width: 2; 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 "imgINotificationObserver.idl"

%{C++
#include "mozilla/Maybe.h"
#include "Visibility.h"
%}

interface imgIRequest;
interface nsIChannel;
interface nsIStreamListener;
interface nsIURI;
interface nsIFrame;

[ref] native MaybeOnNonvisible(const mozilla::Maybe<mozilla::OnNonvisible>);
native Visibility(mozilla::Visibility);

/**
 * This interface represents a content node that loads images.  The interface
 * exists to allow getting information on the images that the content node
 * loads and to allow registration of observers for the image loads.
 *
 * Implementors of this interface should handle all the mechanics of actually
 * loading an image -- getting the URI, checking with content policies and
 * the security manager to see whether loading the URI is allowed, performing
 * the load, firing any DOM events as needed.
 *
 * An implementation of this interface may support the concepts of a
 * "current" image and a "pending" image.  If it does, a request to change
 * the currently loaded image will start a "pending" request which will
 * become current only when the image is loaded.  It is the responsibility of
 * observers to check which request they are getting notifications for.
 *
 * Please make sure to update the MozImageLoadingContent WebIDL
 * mixin to mirror this interface when changing it.
 */

// We can't make this interface noscript yet, because there is JS code doing
// "instanceof Ci.nsIImageLoadingContent" and using the nsIImageLoadingContent
// constants.
[scriptable, builtinclass, uuid(0357123d-9224-4d12-a47e-868c32689777)]
interface nsIImageLoadingContent : imgINotificationObserver
{
  /**
   * Request types.  Image loading content nodes attempt to do atomic
   * image changes when the image url is changed.  This means that
   * when the url changes the new image load will start, but the old
   * image will remain the "current" request until the new image is
   * fully loaded.  At that point, the old "current" request will be
   * discarded and the "pending" request will become "current".
   */
  const long UNKNOWN_REQUEST = -1;
  const long CURRENT_REQUEST = 0;
  const long PENDING_REQUEST = 1;

  /**
   * setLoadingEnabled is used to enable and disable loading in
   * situations where loading images is unwanted.  Note that enabling
   * loading will *not* automatically trigger an image load.
   */
  [notxpcom, nostdcall] void setLoadingEnabled(in boolean aEnabled);

  /**
   * Used to register an image decoder observer.  Typically, this will
   * be a proxy for a frame that wants to paint the image.
   * Notifications from ongoing image loads will be passed to all
   * registered observers.  Notifications for all request types,
   * current and pending, will be passed through.
   *
   * @param aObserver the observer to register
   */
  [notxpcom, nostdcall] void addNativeObserver(in imgINotificationObserver aObserver);

  /**
   * Used to unregister an image decoder observer.
   *
   * @param aObserver the observer to unregister
   */
  [notxpcom, nostdcall] void removeNativeObserver(in imgINotificationObserver aObserver);

  /**
   * Accessor to get the image requests
   *
   * @param aRequestType a value saying which request is wanted
   *
   * @return the imgIRequest object (may be null, even when no error
   * is thrown)
   *
   * @throws NS_ERROR_UNEXPECTED if the request type requested is not
   * known
   */
  [noscript] imgIRequest getRequest(in long aRequestType);

  /**
   * Used to notify the image loading content node that a frame has been
   * created.
   */
  [notxpcom] void frameCreated(in nsIFrame aFrame);

  /**
   * Used to notify the image loading content node that a frame has been
   * destroyed.
   */
  [notxpcom] void frameDestroyed(in nsIFrame aFrame);

  /**
   * Used to find out what type of request one is dealing with (eg
   * which request got passed through to the imgINotificationObserver
   * interface of an observer)
   *
   * @param aRequest the request whose type we want to know
   *
   * @return an enum value saying what type this request is
   *
   * @throws NS_ERROR_UNEXPECTED if aRequest is not known
   */
  [noscript] long getRequestType(in imgIRequest aRequest);

  /**
   * Gets the URI of the current request, if available.
   * Otherwise, returns the last URI that this content tried to load, or
   * null if there haven't been any such attempts.
   */
  [noscript, infallible] readonly attribute nsIURI currentURI;

  /**
   * Gets the sync-decoding hint set by the decoding attribute.
   */
  [noscript, infallible] readonly attribute boolean syncDecodingHint;

  /**
   * loadImageWithChannel allows data from an existing channel to be
   * used as the image data for this content node.
   *
   * @param aChannel the channel that will deliver the data
   *
   * @return a stream listener to pump the image data into
   *
   * @see imgILoader::loadImageWithChannel
   *
   * @throws NS_ERROR_NULL_POINTER if aChannel is null
   */
  [noscript] nsIStreamListener loadImageWithChannel(in nsIChannel aChannel);

  /**
   * Called by layout to announce when the frame associated with this content
   * has changed its visibility state.
   *
   * @param aNewVisibility    The new visibility state.
   * @param aNonvisibleAction A requested action if the frame has become
   *                          nonvisible. If Nothing(), no action is
   *                          requested. If DISCARD_IMAGES is specified, the
   *                          frame is requested to ask any images it's
   *                          associated with to discard their surfaces if
   *                          possible.
   */
  [noscript, notxpcom] void onVisibilityChange(in Visibility aNewVisibility,
                                               in MaybeOnNonvisible aNonvisibleAction);
};