summaryrefslogtreecommitdiffstats
path: root/dom/base/nsIImageLoadingContent.idl
diff options
context:
space:
mode:
Diffstat (limited to 'dom/base/nsIImageLoadingContent.idl')
-rw-r--r--dom/base/nsIImageLoadingContent.idl193
1 files changed, 193 insertions, 0 deletions
diff --git a/dom/base/nsIImageLoadingContent.idl b/dom/base/nsIImageLoadingContent.idl
new file mode 100644
index 000000000..fea261a34
--- /dev/null
+++ b/dom/base/nsIImageLoadingContent.idl
@@ -0,0 +1,193 @@
+/* -*- 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);
+};