187 lines
6.7 KiB
Plaintext
187 lines
6.7 KiB
Plaintext
/* -*- 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"
|
|
|
|
interface imgIRequest;
|
|
interface nsIChannel;
|
|
interface nsIStreamListener;
|
|
interface nsIURI;
|
|
interface nsIDocument;
|
|
interface nsIFrame;
|
|
|
|
/**
|
|
* 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(770f7d84-c917-42d7-bf8d-d1b70649e733)]
|
|
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.
|
|
*/
|
|
[infallible] 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;
|
|
|
|
/**
|
|
* A visible count is stored, if it is non-zero then this image is considered
|
|
* visible. These methods increment, decrement, or return the visible count.
|
|
*
|
|
* @param aNonvisibleAction What to do if the image's visibility count is now
|
|
* zero. If ON_NONVISIBLE_NO_ACTION, nothing will be
|
|
* done. If ON_NONVISIBLE_REQUEST_DISCARD, the image
|
|
* will be asked to discard its surfaces if possible.
|
|
*/
|
|
[noscript, notxpcom] void IncrementVisibleCount();
|
|
[noscript, notxpcom] void DecrementVisibleCount(in uint32_t aNonvisibleAction);
|
|
[noscript, notxpcom] uint32_t GetVisibleCount();
|
|
|
|
const long ON_NONVISIBLE_NO_ACTION = 0;
|
|
const long ON_NONVISIBLE_REQUEST_DISCARD = 1;
|
|
};
|