diff options
Diffstat (limited to 'dom/base/nsIImageLoadingContent.idl')
| -rw-r--r-- | dom/base/nsIImageLoadingContent.idl | 163 |
1 files changed, 163 insertions, 0 deletions
diff --git a/dom/base/nsIImageLoadingContent.idl b/dom/base/nsIImageLoadingContent.idl new file mode 100644 index 0000000000..cdb2f10f2a --- /dev/null +++ b/dom/base/nsIImageLoadingContent.idl @@ -0,0 +1,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); +}; |