/* -*- 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 nsIDocument; 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 * interface to mirror this interface when changing it. */ [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; /** * loadingEnabled 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. */ attribute boolean loadingEnabled; /** * Returns the image blocking status (@see nsIContentPolicy). This * will always be an nsIContentPolicy REJECT_* status for cases when * the image was blocked. This status always refers to the * CURRENT_REQUEST load. */ readonly attribute short imageBlockingStatus; /** * 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 * * @throws NS_ERROR_OUT_OF_MEMORY */ void addObserver(in imgINotificationObserver aObserver); /** * Used to unregister an image decoder observer. * * @param aObserver the observer to unregister */ void removeObserver(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 */ imgIRequest getRequest(in long aRequestType); /** * @return true if the current request's size is available. */ [noscript, notxpcom] boolean currentRequestHasSize(); /** * 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 */ 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. */ readonly attribute nsIURI currentURI; /** * 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 */ nsIStreamListener loadImageWithChannel(in nsIChannel aChannel); /** * forceReload forces reloading of the image pointed to by currentURI * * @param aNotify [optional] request should notify, defaults to true * @throws NS_ERROR_NOT_AVAILABLE if there is no current URI to reload */ [optional_argc] void forceReload([optional] in boolean aNotify /* = true */); /** * Enables/disables image state forcing. When |aForce| is PR_TRUE, we force * nsImageLoadingContent::ImageState() to return |aState|. Call again with |aForce| * as PR_FALSE to revert ImageState() to its original behaviour. */ void forceImageState(in boolean aForce, in unsigned long long aState); /** * The intrinsic size and width of this content. May differ from actual image * size due to things like responsive image density. */ readonly attribute unsigned long naturalWidth; readonly attribute unsigned long naturalHeight; /** * 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); };