nsIImageLoadingContent.idl (6104B)
1 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */ 2 /* This Source Code Form is subject to the terms of the Mozilla Public 3 * License, v. 2.0. If a copy of the MPL was not distributed with this 4 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ 5 6 #include "imgINotificationObserver.idl" 7 8 %{C++ 9 #include "mozilla/Maybe.h" 10 #include "Visibility.h" 11 %} 12 13 interface imgIRequest; 14 interface nsIChannel; 15 interface nsIStreamListener; 16 interface nsIURI; 17 interface nsIFrame; 18 19 [ref] native MaybeOnNonvisible(const mozilla::Maybe<mozilla::OnNonvisible>); 20 native Visibility(mozilla::Visibility); 21 22 /** 23 * This interface represents a content node that loads images. The interface 24 * exists to allow getting information on the images that the content node 25 * loads and to allow registration of observers for the image loads. 26 * 27 * Implementors of this interface should handle all the mechanics of actually 28 * loading an image -- getting the URI, checking with content policies and 29 * the security manager to see whether loading the URI is allowed, performing 30 * the load, firing any DOM events as needed. 31 * 32 * An implementation of this interface may support the concepts of a 33 * "current" image and a "pending" image. If it does, a request to change 34 * the currently loaded image will start a "pending" request which will 35 * become current only when the image is loaded. It is the responsibility of 36 * observers to check which request they are getting notifications for. 37 * 38 * Please make sure to update the MozImageLoadingContent WebIDL 39 * mixin to mirror this interface when changing it. 40 */ 41 42 // We can't make this interface noscript yet, because there is JS code doing 43 // "instanceof Ci.nsIImageLoadingContent" and using the nsIImageLoadingContent 44 // constants. 45 [scriptable, builtinclass, uuid(0357123d-9224-4d12-a47e-868c32689777)] 46 interface nsIImageLoadingContent : imgINotificationObserver 47 { 48 /** 49 * Request types. Image loading content nodes attempt to do atomic 50 * image changes when the image url is changed. This means that 51 * when the url changes the new image load will start, but the old 52 * image will remain the "current" request until the new image is 53 * fully loaded. At that point, the old "current" request will be 54 * discarded and the "pending" request will become "current". 55 */ 56 const long UNKNOWN_REQUEST = -1; 57 const long CURRENT_REQUEST = 0; 58 const long PENDING_REQUEST = 1; 59 60 /** 61 * setLoadingEnabled is used to enable and disable loading in 62 * situations where loading images is unwanted. Note that enabling 63 * loading will *not* automatically trigger an image load. 64 */ 65 [notxpcom, nostdcall] void setLoadingEnabled(in boolean aEnabled); 66 67 /** 68 * Used to register an image decoder observer. Typically, this will 69 * be a proxy for a frame that wants to paint the image. 70 * Notifications from ongoing image loads will be passed to all 71 * registered observers. Notifications for all request types, 72 * current and pending, will be passed through. 73 * 74 * @param aObserver the observer to register 75 */ 76 [notxpcom, nostdcall] void addNativeObserver(in imgINotificationObserver aObserver); 77 78 /** 79 * Used to unregister an image decoder observer. 80 * 81 * @param aObserver the observer to unregister 82 */ 83 [notxpcom, nostdcall] void removeNativeObserver(in imgINotificationObserver aObserver); 84 85 /** 86 * Accessor to get the image requests 87 * 88 * @param aRequestType a value saying which request is wanted 89 * 90 * @return the imgIRequest object (may be null, even when no error 91 * is thrown) 92 * 93 * @throws NS_ERROR_UNEXPECTED if the request type requested is not 94 * known 95 */ 96 [noscript] imgIRequest getRequest(in long aRequestType); 97 98 /** 99 * Used to notify the image loading content node that a frame has been 100 * created. 101 */ 102 [notxpcom] void frameCreated(in nsIFrame aFrame); 103 104 /** 105 * Used to notify the image loading content node that a frame has been 106 * destroyed. 107 */ 108 [notxpcom] void frameDestroyed(in nsIFrame aFrame); 109 110 /** 111 * Used to find out what type of request one is dealing with (eg 112 * which request got passed through to the imgINotificationObserver 113 * interface of an observer) 114 * 115 * @param aRequest the request whose type we want to know 116 * 117 * @return an enum value saying what type this request is 118 * 119 * @throws NS_ERROR_UNEXPECTED if aRequest is not known 120 */ 121 [noscript] long getRequestType(in imgIRequest aRequest); 122 123 /** 124 * Gets the URI of the current request, if available. 125 * Otherwise, returns the last URI that this content tried to load, or 126 * null if there haven't been any such attempts. 127 */ 128 [noscript, infallible] readonly attribute nsIURI currentURI; 129 130 /** 131 * Gets the sync-decoding hint set by the decoding attribute. 132 */ 133 [noscript, infallible] readonly attribute boolean syncDecodingHint; 134 135 /** 136 * loadImageWithChannel allows data from an existing channel to be 137 * used as the image data for this content node. 138 * 139 * @param aChannel the channel that will deliver the data 140 * 141 * @return a stream listener to pump the image data into 142 * 143 * @see imgILoader::loadImageWithChannel 144 * 145 * @throws NS_ERROR_NULL_POINTER if aChannel is null 146 */ 147 [noscript] nsIStreamListener loadImageWithChannel(in nsIChannel aChannel); 148 149 /** 150 * Called by layout to announce when the frame associated with this content 151 * has changed its visibility state. 152 * 153 * @param aNewVisibility The new visibility state. 154 * @param aNonvisibleAction A requested action if the frame has become 155 * nonvisible. If Nothing(), no action is 156 * requested. If DISCARD_IMAGES is specified, the 157 * frame is requested to ask any images it's 158 * associated with to discard their surfaces if 159 * possible. 160 */ 161 [noscript, notxpcom] void onVisibilityChange(in Visibility aNewVisibility, 162 in MaybeOnNonvisible aNonvisibleAction); 163 };