当前位置：文江博客知识库 en-US 文档 Mozilla Tech XPCOM Reference Interface imgIContainer

imgIContainer 编辑

image/public/imgIContainer.idlScriptable Represents an image in the Gecko rendering engine. It provides access to frames as Thebes surfaces and lets users extract subregions as other imgIContainer objects. It also provides methods for drawing images onto Thebes contexts. Internally, this interface also manages animation of images. 66 Introduced Gecko 1.0 Inherits from: nsISupports Last changed in Gecko 14.0 (Firefox 14.0 / Thunderbird 14.0 / SeaMonkey 2.11)

Implemented by: ?????????????????????????????????????. To create an instance, use:

Implemented by: ????????????????????????????????????? as a service:

var imgIContainer = Components.classes["@mozilla.org/????????????????????????????"]
                    .createInstance(Components.interfaces.imgIContainer);

Method overview

void addRestoreData([array, size_is(aCount), const] in char data, in unsigned long aCount); Native code only! Obsolete since Gecko 2.0

void appendFrame(in PRInt32 aX, in PRInt32 aY, in PRInt32 aWidth, in PRInt32 aHeight, in gfxImageFormat aFormat, [array, size_is(imageLength)] out PRUint8 imageData, out unsigned long imageLength);

Native code only! Obsolete since Gecko 2.0

void appendPalettedFrame(in PRInt32 aX, in PRInt32 aY, in PRInt32 aWidth, in PRInt32 aHeight, in gfxImageFormat aFormat, in PRUint8 aPaletteDepth, [array, size_is(imageLength)] out PRUint8 imageData, out unsigned long imageLength, [array, size_is(paletteLength)] out PRUint32 paletteData, out unsigned long paletteLength);

Native code only! Obsolete since Gecko 2.0

void clear(); Obsolete since Gecko 1.9.2

gfxImageSurface copyCurrentFrame(); Native code only! Obsolete since Gecko 2.0

gfxImageSurface copyFrame(in PRUint32 aWhichFrame, in PRUint32 aFlags); Native code only!

void decodingComplete(); Obsolete since Gecko 2.0

void draw(in gfxContext aContext, in gfxGraphicsFilter aFilter, [const] in gfxMatrix aUserSpaceToImageSpace, [const] in gfxRect aFill, [const] in nsIntRect aSubimage, [const] in nsIntSize aViewportSize, in PRUint32 aFlags);

Native code only!

void endFrameDecode(in unsigned long framenumber); Obsolete since Gecko 2.0

void ensureCleanFrame(in unsigned long aFramenum, in PRInt32 aX, in PRInt32 aY, in PRInt32 aWidth, in PRInt32 aHeight, in gfxImageFormat aFormat, [array, size_is(imageLength)] out PRUint8 imageData, out unsigned long imageLength);

Native code only! Obsolete since Gecko 2.0

imgIContainer extractCurrentFrame([const] in nsIntRect aRect); Native code only! Obsolete since Gecko 2.0

imgIContainer extractFrame(in PRUint32 aWhichFrame, [const] in nsIntRect aRect, in PRUint32 aFlags); Native code only!

void frameUpdated(in unsigned long framenum, in nsIntRect aNewRect); Native code only! Obsolete since Gecko 2.0

void getCurrentFrameRect(in nsIntRect aFrameRect); Native code only! Obsolete since Gecko 2.0

gfxASurface getFrame(in PRUint32 aWhichFrame, in PRUint32 aFlags); Native code only!

gfxIImageFrame getFrameAt(in unsigned long index); Obsolete since Gecko 1.9.2

void getFrameColormap(in unsigned long framenumber, [array, size_is(paletteLength)] out PRUint32 paletteData, out unsigned long paletteLength);

Obsolete since Gecko 2.0

unsigned long getFrameImageDataLength(in unsigned long framenumber); Obsolete since Gecko 2.0

ImageContainer getImageContainer(); Native code only!

nsIFrame GetRootLayoutFrame(); Violates the XPCOM interface guidelines

PRUint16 GetType(); Violates the XPCOM interface guidelines

void init(in PRInt32 aWidth, in PRInt32 aHeight, in imgIContainerObserver aObserver); Obsolete since Gecko 2.0

void lockImage();

void removeFrame(in gfxIImageFrame item); Obsolete since Gecko 1.9.2

void requestDecode();

void requestDiscard();

void requestRefresh([const] in TimeStamp aTime); Violates the XPCOM interface guidelines

void resetAnimation();

void restoreDataDone(); Native code only! Obsolete since Gecko 2.0

void setDiscardable(in string aMimeType); Native code only! Obsolete since Gecko 2.0

void setFrameBlendMethod(in unsigned long framenumber, in PRInt32 aBlendMethod); Obsolete since Gecko 2.0

void setFrameDisposalMethod(in unsigned long framenumber, in PRInt32 aDisposalMethod); Obsolete since Gecko 2.0

void setFrameHasNoAlpha(in unsigned long framenumber); Obsolete since Gecko 2.0

void setFrameTimeout(in unsigned long framenumber, in PRInt32 aTimeout); Obsolete since Gecko 2.0

void startAnimation(); Obsolete since Gecko 2.0

void stopAnimation(); Obsolete since Gecko 2.0

void unlockImage();

Attributes

Attribute	Type	Description
`animated`	`boolean`	Whether this image is `animated`. You can only be guaranteed that querying this will not throw if STATUS_DECODE_COMPLETE is set on the `imgIRequest`. Read only. Exceptions thrown `NS_ERROR_NOT_AVAILABLE` If the `animated` state cannot be determined.
`animationMode`	`unsigned short`
`currentFrame`	`gfxASurface`	Get a surface for the current frame. This may be a platform-native, optimized frame, so you cannot inspect its pixel data. Read only. Native code only! Obsolete since Gecko 2.0
`currentFrameIndex`	`unsigned long`	The index of the current frame that would be drawn if the image was to be drawn now. Read only. Obsolete since Gecko 2.0
`currentFrameIsOpaque`	`boolean`	Whether the current frame is opaque; that is, needs the background painted behind it. Read only.
`height`	`PRInt32`	The `height` of the container rectangle. In the case of any error, zero is returned, and an exception will be thrown. Read only.
`loopCount`	`long`	number of times to loop the image. Note: -1 means forever. Obsolete since Gecko 2.0
`numFrames`	`unsigned long`	The total number of frames in this image. Read only. Obsolete since Gecko 2.0
`preferredAlphaChannelFormat`	`gfx_format`	Read only. Obsolete since Gecko 1.9.2
`type`	`unsigned short`	The `type` of this image (one of the TYPE_* values above). Read only.
`width`	`PRInt32`	The `width` of the container rectangle. In the case of any error, zero is returned, and an exception will be thrown. Read only.

Constants

Constant	Value	Description
`TYPE_RASTER`	`0`	Enumerated values for the '`type`' attribute (below).
`TYPE_VECTOR`	`1`
`FLAG_NONE`	`0x0`	Flags for `imgIContainer` operations. Meanings: `FLAG_NONE`: Lack of flags. `FLAG_SYNC_DECODE`: Forces synchronous/non-progressive decode of all available data before the call returns. It is an error to pass this flag from a call stack that originates in a decoder (that is, from a decoder observer event). `FLAG_DECODE_NO_PREMULTIPLY_ALPHA`: Do not premultiply alpha if it is not already premultiplied in the image data. `FLAG_DECODE_NO_COLORSPACE_CONVERSION`: Do not do any colorspace conversion; ignore any embedded profiles, and do not convert to any particular destination space. `FLAG_CLAMP`: Extend the image to the fill area by clamping image sample coordinates instead of by tiling. This only affects '`draw()`'.
`FLAG_SYNC_DECODE`	`0x1`
`FLAG_DECODE_NO_PREMULTIPLY_ALPHA`	`0x2`
`FLAG_DECODE_NO_COLORSPACE_CONVERSION`	`0x4`
`FLAG_CLAMP`	`0x8`
`FRAME_FIRST`	`0`	Constants for specifying various "special" frames. `FRAME_FIRST`: The first frame `FRAME_CURRENT`: The current frame. `FRAME_MAX_VALUE` should be set to the value of the maximum constant above, as it is used for ensuring that a valid value was passed in.
`FRAME_CURRENT`	`1`
`FRAME_MAX_VALUE`	`1`
`kNormalAnimMode`	`0`	Animation mode Constants 0 = normal 1 = do not animate 2 = loop once.
`kDontAnimMode`	`1`
`kLoopOnceAnimMode`	`2`
`kDisposeClearAll`	`-1`	"Disposal" method indicates how the image should be handled before the subsequent image is displayed. Do not change these without looking at the implementations using them, struct gif_struct::disposal_method and gif_write() in particular. `Clear()` the whole image, revealing. Obsolete since Gecko 2.0
`kDisposeNotSpecified`	`0`	Leave frame, let new frame `draw()` on top. Obsolete since Gecko 2.0
`kDisposeKeep`	`1`	Leave frame, let new frame `draw()` on top. Obsolete since Gecko 2.0
`kDisposeClear`	`2`	`Clear()` the frame's area, revealing bg. Obsolete since Gecko 2.0
`kDisposeRestorePrevious`	`3`	Restore the previous(composited) frame. Obsolete since Gecko 2.0
`kBlendSource`	`0`	All color components of the frame, including alpha, const long kBlendOver = 1; // The frame should be composited onto the output buffer. Obsolete since Gecko 2.0

Methods

Native code only!

addRestoreData

Obsolete since Gecko 2.0 (Firefox 4 / Thunderbird 3.3 / SeaMonkey 2.1)
This feature is obsolete. Although it may still work in some browsers, its use is discouraged since it could be removed at any time. Try to avoid using it.

void addRestoreData(
  [array, size_is(aCount), const] in char data,
  in unsigned long aCount
);

Parameters

data: Missing Description
aCount: Missing Description

Exceptions thrown

Missing Exception: Missing Description

Native code only!

appendFrame

Adds to the end of the list of frames.

void appendFrame(
  in PRInt32 aX,
  in PRInt32 aY,
  in PRInt32 aWidth,
  in PRInt32 aHeight,
  in gfxImageFormat aFormat,
  [array, size_is(imageLength)] out PRUint8 imageData,
  out unsigned long imageLength
);

Parameters

aX: Missing Description
aY: Missing Description
aWidth: Missing Description
aHeight: Missing Description
aFormat: Missing Description
imageData: Missing Description
imageLength: Missing Description

Exceptions thrown

Missing Exception: Missing Description

Native code only!

appendPalettedFrame

void appendPalettedFrame(
  in PRInt32 aX,
  in PRInt32 aY,
  in PRInt32 aWidth,
  in PRInt32 aHeight,
  in gfxImageFormat aFormat,
  in PRUint8 aPaletteDepth,
  [array, size_is(imageLength)] out PRUint8 imageData,
  out unsigned long imageLength,
  [array, size_is(paletteLength)] out PRUint32 paletteData,
  out unsigned long paletteLength
);

Parameters

aX: Missing Description
aY: Missing Description
aWidth: Missing Description
aHeight: Missing Description
aFormat: Missing Description
aPaletteDepth: Missing Description
imageData: Missing Description
imageLength: Missing Description
paletteData: Missing Description
paletteLength: Missing Description

Exceptions thrown

Missing Exception: Missing Description

clear()

Obsolete since Gecko 1.9.2 (Firefox 3.6 / Thunderbird 3.1 / Fennec 1.0)

void clear();

Parameters

None.

Exceptions thrown

Missing Exception: Missing Description

Native code only!

copyCurrentFrame

Create and return a new copy of the current frame that you can write to and otherwise inspect the pixels of.

gfxImageSurface copyCurrentFrame();

Parameters

None.

Return value

Missing Description

Exceptions thrown

Missing Exception: Missing Description

Native code only!

copyFrame

Create and return a new copy of the given frame that you can write to and otherwise inspect the pixels of.

gfxImageSurface copyFrame(
  in PRUint32 aWhichFrame,
  in PRUint32 aFlags
);

Parameters

aWhichFrame: Frame specifier of the FRAME_* variety.
aFlags: Flags of the FLAG_* variety.

Return value

Missing Description

Exceptions thrown

Missing Exception: Missing Description

decodingComplete()

Obsolete since Gecko 2.0 (Firefox 4 / Thunderbird 3.3 / SeaMonkey 2.1)

void decodingComplete();

Parameters

None.

Exceptions thrown

Missing Exception: Missing Description

Native code only!

draw

Draw the current frame on to the context specified.

void draw(
  in gfxContext aContext,
  in gfxGraphicsFilter aFilter,
  [const] in gfxMatrix aUserSpaceToImageSpace,
  [const] in gfxRect aFill,
  [const] in nsIntRect aSubimage,
  [const] in nsIntSize aViewportSize,
  in PRUint32 aFlags
);

Parameters

aContext: The Thebes context to draw the image to.
aFilter: The filter to be used if we're scaling the image.
aUserSpaceToImageSpace: The transformation from user space (for example, appunits) to image space.
aFill: The area in the context to draw pixels to. When aFlags includes FLAG_CLAMP, the image will be extended to this area by clamping image sample coordinates. Otherwise, the image will be automatically tiled as necessary.
aSubimage: The area of the image, in pixels, that we are allowed to sample from.
aViewportSize: The size (in CSS pixels) of the viewport that would be available for the full image to occupy, if we were drawing the full image. (Note that we might not actually be drawing the full image -- we might be restricted by aSubimage -- but we still need the full image's viewport-size in order for SVG images with the "viewBox" attribute to position their content correctly.)
aFlags: Flags of the FLAG_* variety.

Exceptions thrown

Missing Exception: Missing Description

endFrameDecode()

Obsolete since Gecko 2.0 (Firefox 4 / Thunderbird 3.3 / SeaMonkey 2.1)

void endFrameDecode(
  in unsigned long framenumber
);

Parameters

framenumber: Missing Description

Exceptions thrown

Missing Exception: Missing Description

Native code only!

ensureCleanFrame

Create or reuse a frame at index aFrameNum. It is an error to call this with aFrameNum not in the range [0, numFrames].

void ensureCleanFrame(
  in unsigned long aFramenum,
  in PRInt32 aX,
  in PRInt32 aY,
  in PRInt32 aWidth,
  in PRInt32 aHeight,
  in gfxImageFormat aFormat,
  [array, size_is(imageLength)] out PRUint8 imageData,
  out unsigned long imageLength
);

Parameters

aFramenum: Missing Description
aX: Missing Description
aY: Missing Description
aWidth: Missing Description
aHeight: Missing Description
aFormat: Missing Description
imageData: Missing Description
imageLength: Missing Description

Exceptions thrown

Missing Exception: Missing Description

Native code only!

extractCurrentFrame

Create a new imgContainer that contains only a single frame, which itself contains a subregion of the current frame.

imgIContainer extractCurrentFrame(
  [const] in nsIntRect aRect
);

Parameters

aRect: The area of the current frame to be duplicated in the returned imgContainer's frame.

Return value

Missing Description

Exceptions thrown

Missing Exception: Missing Description

Native code only!

extractFrame

Create a new imgContainer that contains only a single frame, which itself contains a subregion of the given frame.

imgIContainer extractFrame(
  in PRUint32 aWhichFrame,
  [const] in nsIntRect aRect,
  in PRUint32 aFlags
);

Parameters

aWhichFrame: Frame specifier of the FRAME_* variety.
aRect: The area of the current frame to be duplicated in the returned imgContainer's frame.
aFlags: Flags of the FLAG_* variety.

Return value

Missing Description

Exceptions thrown

Missing Exception: Missing Description

Native code only!

frameUpdated

void frameUpdated(
  in unsigned long framenum,
  in nsIntRect aNewRect
);

Parameters

framenum: Missing Description
aNewRect: Missing Description

Exceptions thrown

Missing Exception: Missing Description

Native code only!

getCurrentFrameRect

The rectangle defining the location and size of the currently displayed frame. Should be an attribute, but cannot be because of reference/pointer conflicts with native types in xpidl.

void getCurrentFrameRect(
  in nsIntRect aFrameRect
);

Parameters

aFrameRect: Missing Description

Exceptions thrown

Missing Exception: Missing Description

Native code only!

getFrame

Get a surface for the given frame. This may be a platform-native, optimized surface, so you cannot inspect its pixel data.

gfxASurface getFrame(
  in PRUint32 aWhichFrame,
  in PRUint32 aFlags
);

Parameters

aWhichFrame: Frame specifier of the FRAME_* variety.
aFlags: Flags of the FLAG_* variety.

Return value

Missing Description

Exceptions thrown

Missing Exception: Missing Description

getFrameAt()

Obsolete since Gecko 1.9.2 (Firefox 3.6 / Thunderbird 3.1 / Fennec 1.0)

gfxIImageFrame getFrameAt(
  in unsigned long index
);

Parameters

index: Missing Description

Return value

Missing Description

Exceptions thrown

Missing Exception: Missing Description

getFrameColormap()

void getFrameColormap(
  in unsigned long framenumber,
  [array, size_is(paletteLength)] out PRUint32 paletteData,
  out unsigned long paletteLength
);

Parameters

framenumber: Missing Description
paletteData: Missing Description
paletteLength: Missing Description

Exceptions thrown

Missing Exception: Missing Description

getFrameImageDataLength()

Get the size, in bytes, of a particular frame's image data.

unsigned long getFrameImageDataLength(
  in unsigned long framenumber
);

Parameters

framenumber: Missing Description

Return value

Missing Description

Exceptions thrown

Missing Exception: Missing Description

Native code only!

getImageContainer

Attempts to create an ImageContainer (and Image) containing the current frame. Only valid for RASTER type images.

ImageContainer getImageContainer();

Parameters

None.

Return value

Missing Description

Exceptions thrown

Missing Exception: Missing Description

Violates the XPCOM interface guidelines

GetRootLayoutFrame()

If this image is TYPE_VECTOR, that is really an embedded SVG document, and this method returns a pointer to the root nsIFrame of that document. If not (or if the root nsIFrame is not available for some reason), this method returns nsnull.

"notxpcom" for convenience, since we have no need for nsresult return-val.

nsIFrame GetRootLayoutFrame();

Parameters

None.

Return value

Missing Description

Exceptions thrown

Missing Exception: Missing Description

Violates the XPCOM interface guidelines

GetType()

Direct C++ accessor for 'type' attribute, for convenience.

PRUint16 GetType();

Parameters

None.

Return value

Missing Description

Exceptions thrown

Missing Exception: Missing Description

init()

Obsolete since Gecko 2.0 (Firefox 4 / Thunderbird 3.3 / SeaMonkey 2.1)

Create a new \a aWidth x \a aHeight sized image container.

void init(
  in PRInt32 aWidth,
  in PRInt32 aHeight,
  in imgIContainerObserver aObserver
);

Parameters

aWidth: The width of the container in which all the frames will fit.
aHeight: The height of the container in which all the frames will fit.
aObserver: Observer to send animation notifications to.

Exceptions thrown

Missing Exception: Missing Description

lockImage()

Increments the lock count on the image. An image will not be discarded as long as the lock count is nonzero. Note that it is still possible for the image to be undecoded if decode-on-draw() is enabled and the image was never drawn.

Upon instantiation images have a lock count of zero.

void lockImage();

Parameters

None.

Exceptions thrown

Missing Exception: Missing Description

removeFrame()

Obsolete since Gecko 1.9.2 (Firefox 3.6 / Thunderbird 3.1 / Fennec 1.0)

void removeFrame(
  in gfxIImageFrame item
);

Parameters

item: Missing Description

Exceptions thrown

Missing Exception: Missing Description

requestDecode()

void requestDecode();

Parameters

None.

Exceptions thrown

Missing Exception: Missing Description

requestDiscard()

If this image is unlocked, discard its decoded data. If the image is locked or has already been discarded, do nothing.

void requestDiscard();

Parameters

None.

Exceptions thrown

Missing Exception: Missing Description

Violates the XPCOM interface guidelines

requestRefresh()

Indicates that this imgIContainer has been triggered to update its internal animation state. Likely this should only be called from within nsImageFrame or objects of similar type.

void requestRefresh(
  [const] in TimeStamp aTime
);

Parameters

aTime: Missing Description

Exceptions thrown

Missing Exception: Missing Description

resetAnimation()

void resetAnimation();

Parameters

None.

Exceptions thrown

Missing Exception: Missing Description

Native code only!

restoreDataDone

void restoreDataDone();

Parameters

None.

Exceptions thrown

Missing Exception: Missing Description

Native code only!

setDiscardable

void setDiscardable(
  in string aMimeType
);

Parameters

aMimeType: Missing Description

Exceptions thrown

Missing Exception: Missing Description

setFrameBlendMethod()

void setFrameBlendMethod(
  in unsigned long framenumber,
  in PRInt32 aBlendMethod
);

Parameters

framenumber: Missing Description
aBlendMethod: Missing Description

Exceptions thrown

Missing Exception: Missing Description

setFrameDisposalMethod()

void setFrameDisposalMethod(
  in unsigned long framenumber,
  in PRInt32 aDisposalMethod
);

Parameters

framenumber: Missing Description
aDisposalMethod: Missing Description

Exceptions thrown

Missing Exception: Missing Description

setFrameHasNoAlpha()

void setFrameHasNoAlpha(
  in unsigned long framenumber
);

Parameters

framenumber: Missing Description

Exceptions thrown

Missing Exception: Missing Description

setFrameTimeout()

void setFrameTimeout(
  in unsigned long framenumber,
  in PRInt32 aTimeout
);

Parameters

framenumber: Missing Description
aTimeout: Missing Description

Exceptions thrown

Missing Exception: Missing Description

startAnimation()

Obsolete since Gecko 2.0 (Firefox 4 / Thunderbird 3.3 / SeaMonkey 2.1)

void startAnimation();

Parameters

None.

Exceptions thrown

Missing Exception: Missing Description

stopAnimation()

Obsolete since Gecko 2.0 (Firefox 4 / Thunderbird 3.3 / SeaMonkey 2.1)

void stopAnimation();

Parameters

None.

Exceptions thrown

Missing Exception: Missing Description

unlockImage()

Decreases the lock count on the image. If the lock count drops to zero, the image is allowed to discard its frame data to save memory.

Upon instantiation images have a lock count of zero. It is an error to call this method without first having made a matching lockImage() call. In other words, the lock count is not allowed to be negative.

void unlockImage();

Parameters

None.

Exceptions thrown

Missing Exception: Missing Description

Remarks

---