imgIDecoderObserver

This article is in need of a technical review.

This interface is used both for observing imgIDecoder objects and for observing imgIRequest objects. It lets you monitor the progress of loading an image.
1.0
28
Introduced
Gecko 12.0
Inherits from: imgIContainerObserver Last changed in Gecko 1.7

We make the distinction here between "load" and "decode" notifications. Load notifications are fired as the image is loaded from the network or filesystem. Decode notifications are fired as the image is decoded. If an image is decoded on load and not visibly discarded, decode notifications are nested logically inside load notifications as one might expect. However, with decode-on-draw, the set of decode notifications can come completely after the load notifications, and can come multiple times if the image is discardable. Moreover, they can be interleaved in various ways. In general, any presumed ordering between load and decode notifications should not be relied upon.

Decode notifications may or may not be synchronous, depending on the situation. If imgIDecoder::FLAG_SYNC_DECODE is passed to a function that triggers a decode, all notifications that can be generated from the currently loaded data fire before the call returns. If FLAG_SYNC_DECODE is not passed, all, some, or none of the notifications may fire before the call returns.

Method overview

void onDataAvailable(in imgIRequest aRequest, in boolean aCurrentFrame, [const] in nsIntRect aRect); Native code only!
void onDiscard(in imgIRequest aRequest);
void onImageIsAnimated(in imgIRequest aRequest);
void onStartContainer(in imgIRequest aRequest, in imgIContainer aContainer);
void onStartDecode(in imgIRequest aRequest);
void onStartFrame(in imgIRequest aRequest, in unsigned long aFrame);
void onStartRequest(in imgIRequest aRequest);
void onStopContainer(in imgIRequest aRequest, in imgIContainer aContainer);
void onStopDecode(in imgIRequest aRequest, in nsresult status, in wstring statusArg);
void onStopFrame(in imgIRequest aRequest, in unsigned long aFrame);
void onStopRequest(in imgIRequest aRequest, in boolean aIsLastPart);

Methods

Native code only!

onDataAvailable

Decode notification. Called when there is more to paint.

void onDataAvailable(
  in imgIRequest aRequest,
  in boolean aCurrentFrame,
  [const] in nsIntRect aRect
);
Parameters
aRequest
The request on which data is available, or null if being called for an imgIDecoder object.
aCurrentFrame
Missing Description
aRect
Missing Description

Requires Gecko 2.0 (Firefox 4 / Thunderbird 3.3 / SeaMonkey 2.1)

onDiscard()

Called when the decoded image data is discarded. This means that the frames no longer exist in decoded form, and any attempt to access or draw the image will initiate a new series of progressive decode notifications.

void onDiscard(
  in imgIRequest aRequest
);
Parameters
aRequest
The request on which data is available, or null if being called for an imgIDecoder object.

Requires Gecko 12.0 (Firefox 12.0 / Thunderbird 12.0 / SeaMonkey 2.9)

onImageIsAnimated()

Notification for when an image is known to be animated. This should be fired at the earliest possible time.

void onImageIsAnimated(
  in imgIRequest aRequest
);
Parameters
aRequest
The request on which data is available, or null if being called for an imgIDecoder object.

onStartContainer()

This load notification is called once enough data has been loaded from the network that we were able to parse the width and height from the image. By the time this callback is been called, the size has been set on the container and STATUS_SIZE_AVAILABLE has been set on the associated imgRequest.

void onStartContainer(
  in imgIRequest aRequest,
  in imgIContainer aContainer
);
Parameters
aRequest
The request on which data is available, or null if being called for an imgIDecoder object.
aContainer
Missing Description

onStartDecode()

This decode notification is called as soon as the image begins getting decoded. This does not include "header-only" decodes used by decode-on-draw to parse the width/height out of the image. Thus, it is a decode notification only.

void onStartDecode(
  in imgIRequest aRequest
);
Parameters
aRequest
The request on which data is available, or null if being called for an imgIDecoder object.

onStartFrame()

This is a decode notification which is called when each frame is created.

void onStartFrame(
  in imgIRequest aRequest,
  in unsigned long aFrame
);
Parameters
aRequest
The request on which data is available, or null if being called for an imgIDecoder object.
aFrame
Missing Description

Requires Gecko 1.9 (Firefox 3)

onStartRequest()

A load notification which is called at the same time that nsIRequestObserver.onStartRequest() would be (used only for observers of imgIRequest objects, which are nsIRequests, not imgIDecoder objects).

void onStartRequest(
  in imgIRequest aRequest
);
Parameters
aRequest
The request on which data is available, or null if being called for an imgIDecoder object.

onStopContainer()

Warning: Do not implement this. It is useless and going away.
void onStopContainer(
  in imgIRequest aRequest,
  in imgIContainer aContainer
);
Parameters
aRequest
The request on which data is available, or null if being called for an imgIDecoder object.
aContainer
Missing Description

onStopDecode()

In theory a decode notification, but currently a load notification.

Ideally this would be called when the decode is complete. Unfortunately, this is currently the only way to signal decoding errors to consumers, and the only decoding errors that consumers care about (indeed, the only ones that they're prepared to hear about) are failures to instantiate the decoder (<img src="foo.html"> for example). Thus, currently this is just a companion to onStopRequest to signal success or failure. You probably want onStopContainer instead. This will be revisited in bug 505385. If you're thinking of doing something new with this, please talk to bholley first.

void onStopDecode(
  in imgIRequest aRequest,
  in nsresult status,
  in wstring statusArg
);
Parameters
aRequest
The request on which data is available, or null if being called for an imgIDecoder object.
status
Missing Description
statusArg
Missing Description

onStopFrame()

A decode notification that is called when a frame is finished decoding.

void onStopFrame(
  in imgIRequest aRequest,
  in unsigned long aFrame
);
Parameters
aRequest
The request on which data is available, or null if being called for an imgIDecoder object.
aFrame
Missing Description

Requires Gecko 1.9 (Firefox 3)

onStopRequest()

A load notification that is called at the same time that nsIRequestObserver.onStopRequest() would be (used only for observers of imgIRequest objects, which are nsIRequests, not imgIDecoder objects).

void onStopRequest(
  in imgIRequest aRequest,
  in boolean aIsLastPart
);
Parameters
aRequest
The request on which data is available, or null if being called for an imgIDecoder object.
aIsLastPart
Missing Description

See also

Document Tags and Contributors

Contributors to this page: Sheppy, fscholz, kscarfone, bholley
Last updated by: Sheppy,