spark.primitives.BitmapImage - Adobe® Flex® 4 Language Reference (Flex 4)

Package	spark.primitives
Class	public class BitmapImage
Inheritance	BitmapImage GraphicElement EventDispatcher Object

Language Version:

ActionScript 3.0

Product Version:

Flex 4

Runtime Versions:

Flash Player 10, AIR 1.5

A BitmapImage element defines a rectangular region in its parent element's coordinate space, filled with bitmap data drawn from a source file.

View the examples

See also

Using MXML graphics
Bitmap graphics

Public Properties

Hide Inherited Public Properties

Show Inherited Public Properties

	Property		Defined By
		alpha : Number The level of transparency of the graphic element.	GraphicElement
		baseline : Object The vertical distance in pixels from the anchor target to the control's baseline position.	GraphicElement
		baselinePosition : Number [read-only] The y-coordinate of the baseline of the first line of text of the component.	GraphicElement
		blendMode : String A value from the BlendMode class that specifies which blend mode to use.	GraphicElement
		bottom : Object The vertical distance in pixels from the bottom edge of the component to the anchor target's bottom edge.	GraphicElement
		constructor : Object A reference to the class object or constructor function for a given object instance.	Object
		depth : Number Determines the order in which items inside of containers are rendered.	GraphicElement
		designLayer : DesignLayer Specifies the optional DesignLayer instance associated with this visual element.	GraphicElement
		displayObject : DisplayObject [read-only] The shared DisplayObject where this IGraphicElement is drawn.	GraphicElement
		displayObjectSharingMode : String Indicates the association between this IGraphicElement and its display objects.	GraphicElement
		explicitHeight : Number Number that specifies the explicit height of the component, in pixels, in the component's coordinates.	GraphicElement
		explicitMaxHeight : Number The maximum recommended height of the component to be considered by the parent during layout.	GraphicElement
		explicitMaxWidth : Number The maximum recommended width of the component to be considered by the parent during layout.	GraphicElement
		explicitMinHeight : Number The minimum recommended height of the component to be considered by the parent during layout.	GraphicElement
		explicitMinWidth : Number The minimum recommended width of the component to be considered by the parent during layout.	GraphicElement
		explicitWidth : Number Number that specifies the explicit width of the component, in pixels, in the component's coordinates.	GraphicElement
		fillMode : String The fillMode determines how the bitmap fills in the dimensions.	BitmapImage
		filters : Array An indexed array that contains each filter object currently associated with the graphic element.	GraphicElement
		hasLayoutMatrix3D : Boolean [read-only] Contians true if the element has 3D Matrix.	GraphicElement
		height : Number The height of the graphic element.	GraphicElement
		horizontalCenter : Object The horizontal distance in pixels from the center of the component to the center of the anchor target's content area.	GraphicElement
		id : String The identity of the component.	GraphicElement
		includeInLayout : Boolean Specifies whether this element is included in the layout of the group.	GraphicElement
		is3D : Boolean [read-only] Contains true when the element is in 3D.	GraphicElement
		left : Object The horizontal distance in pixels from the left edge of the component to the anchor target's left edge.	GraphicElement
		luminosityClip : Boolean A property that controls whether the luminosity mask clips the masked content.	GraphicElement
		luminosityInvert : Boolean A property that controls the calculation of the RGB color value of a graphic element being masked by a luminosity mask.	GraphicElement
		mask : DisplayObject The calling display object is masked by the specified mask object.	GraphicElement
		maskType : String Defines how the mask is applied to the GraphicElement. The possible values are MaskType.CLIP, MaskType.ALPHA, and MaskType.LUMINOSITY. Clip Masking When masking in clip mode, a clipping masks is reduced to 1-bit.	GraphicElement
		maxHeight : Number The maximum recommended height of the component to be considered by the parent during layout.	GraphicElement
		maxWidth : Number The maximum recommended width of the component to be considered by the parent during layout.	GraphicElement
		measuredHeight : Number The default height of the component, in pixels.	GraphicElement
		measuredWidth : Number The default width of the component, in pixels.	GraphicElement
		measuredX : Number The default measured bounds top-left corner relative to the origin of the element.	GraphicElement
		measuredY : Number The default measured bounds top-left corner relative to the origin of the element.	GraphicElement
		minHeight : Number The minimum recommended height of the component to be considered by the parent during layout.	GraphicElement
		minWidth : Number The minimum recommended width of the component to be considered by the parent during layout.	GraphicElement
		owner : DisplayObjectContainer The owner of this IVisualElement object.	GraphicElement
		parent : DisplayObjectContainer [read-only] The parent container or component for this component.	GraphicElement
		percentHeight : Number Number that specifies the height of a component as a percentage of its parent's size.	GraphicElement
		percentWidth : Number Number that specifies the width of a component as a percentage of its parent's size.	GraphicElement
		postLayoutTransformOffsets : mx.geom:TransformOffsets Defines a set of adjustments that can be applied to the object's transform in a way that is invisible to its parent's layout.	GraphicElement
		prototype : Object [static] A reference to the prototype object of a class or function object.	Object
		right : Object The horizontal distance in pixels from the right edge of the component to the anchor target's right edge.	GraphicElement
		rotation : Number Indicates the rotation of the element, in degrees, from the transform point.	GraphicElement
		rotationX : Number Indicates the x-axis rotation of the element instance, in degrees, from its original orientation relative to the 3D parent container.	GraphicElement
		rotationY : Number Indicates the y-axis rotation of the DisplayObject instance, in degrees, from its original orientation relative to the 3D parent container.	GraphicElement
		rotationZ : Number Indicates the rotation of the element, in degrees, from the transform point.	GraphicElement
		scaleX : Number The horizontal scale (percentage) of the element as applied from the transform point.	GraphicElement
		scaleY : Number The vertical scale (percentage) of the element as applied from the transform point.	GraphicElement
		scaleZ : Number The z scale (percentage) of the element as applied from the transform point.	GraphicElement
		smooth : Boolean Specifies whether to apply a smoothing algorithm to the bitmap image.	BitmapImage
		source : Object The source used for the bitmap fill.	BitmapImage
		top : Object The vertical distance in pixels from the top edge of the component to the anchor target's top edge.	GraphicElement
		transform : flash.geom:Transform An object with properties pertaining to a display object's matrix, color transform, and pixel bounds.	GraphicElement
		transformX : Number The x position transform point of the element.	GraphicElement
		transformY : Number The y position transform point of the element.	GraphicElement
		transformZ : Number The z position transform point of the element.	GraphicElement
		verticalCenter : Object The vertical distance in pixels from the center of the component to the center of the anchor target's content area.	GraphicElement
		visible : Boolean Controls the visibility of this visual element.	GraphicElement
		width : Number The width of the graphic element.	GraphicElement
		x : Number The x position of the graphic element.	GraphicElement
		y : Number The y position of the graphic element.	GraphicElement
		z : Number The z position of the graphic element.	GraphicElement

Protected Properties

Hide Inherited Protected Properties

Show Inherited Protected Properties

	Property		Defined By
		drawnDisplayObject : DisplayObject [read-only] The actual DisplayObject that is drawn into by the GraphicElement.	GraphicElement
		drawX : Number [read-only] The x position where the element should be drawn.	GraphicElement
		drawY : Number [read-only] The y position where the element should be drawn.	GraphicElement
		hasComplexLayoutMatrix : Boolean [read-only] Returns true if the GraphicElement has any non-translation (x,y) transform properties	GraphicElement
		layoutFeatures : AdvancedLayoutFeatures Contain all of the implementation details of how the GraphicElement implements transform and layering support.	GraphicElement
		needsDisplayObject : Boolean [read-only] True if the element requires an exclusive DisplayObject.	GraphicElement

Public Methods

Hide Inherited Public Methods

Show Inherited Public Methods

	Method		Defined By
		BitmapImage() Constructor.	BitmapImage
		addEventListener(type:String, listener:Function, useCapture:Boolean = false, priority:int = 0, useWeakReference:Boolean = false):void Registers an event listener object with an EventDispatcher object so that the listener receives notification of an event.	EventDispatcher
		canShareWithNext(element:IGraphicElement):Boolean Returns true if this IGraphicElement is compatible and can share display objects with the next IGraphicElement in the sequence.	GraphicElement
		canShareWithPrevious(element:IGraphicElement):Boolean Returns true if this IGraphicElement is compatible and can share display objects with the previous IGraphicElement in the sequence.	GraphicElement
		createDisplayObject():DisplayObject Creates a new DisplayObject where this IGraphicElement is drawn.	GraphicElement
		dispatchEvent(event:Event):Boolean Dispatches an event into the event flow.	EventDispatcher
		getBoundsXAtSize(width:Number, height:Number, postLayoutTransform:Boolean = true):Number Returns the x coordinate of the element's bounds at the specified element size.	GraphicElement
		getBoundsYAtSize(width:Number, height:Number, postLayoutTransform:Boolean = true):Number Returns the y coordinate of the element's bounds at the specified element size.	GraphicElement
		getLayoutBoundsHeight(postLayoutTransform:Boolean = true):Number Returns the element's layout height.	GraphicElement
		getLayoutBoundsWidth(postLayoutTransform:Boolean = true):Number Returns the element's layout width.	GraphicElement
		getLayoutBoundsX(postLayoutTransform:Boolean = true):Number Returns the x coordinate that the element uses to draw on screen.	GraphicElement
		getLayoutBoundsY(postLayoutTransform:Boolean = true):Number Returns the y coordinate that the element uses to draw on screen.	GraphicElement
		getLayoutMatrix():Matrix Returns the transform matrix that is used to calculate the component's layout relative to its siblings.	GraphicElement
		getLayoutMatrix3D():Matrix3D Returns the layout transform Matrix3D for this element.	GraphicElement
		getMaxBoundsHeight(postLayoutTransform:Boolean = true):Number Returns the element's maximum height.	GraphicElement
		getMaxBoundsWidth(postLayoutTransform:Boolean = true):Number Returns the element's maximum width.	GraphicElement
		getMinBoundsHeight(postLayoutTransform:Boolean = true):Number Returns the element's minimum height.	GraphicElement
		getMinBoundsWidth(postLayoutTransform:Boolean = true):Number Returns the element's minimum width.	GraphicElement
		getPreferredBoundsHeight(postLayoutTransform:Boolean = true):Number Returns the element's preferred height.	GraphicElement
		getPreferredBoundsWidth(postLayoutTransform:Boolean = true):Number Returns the element's preferred width.	GraphicElement
		hasEventListener(type:String):Boolean Checks whether the EventDispatcher object has any listeners registered for a specific type of event.	EventDispatcher
		hasOwnProperty(name:String):Boolean Indicates whether an object has a specified property defined.	Object
		initialized(document:Object, id:String):void Called automatically by the MXML compiler when the GraphicElement is created using an MXML tag.	GraphicElement
		invalidateDisplayList():void Calling this method results in a call to the elements's validateDisplayList() method before the display list is rendered.	GraphicElement
		invalidateProperties():void Calling this method results in a call to the elements's validateProperties() method before the display list is rendered.	GraphicElement
		invalidateSize():void Calling this method results in a call to the elements's validateSize() method before the display list is rendered.	GraphicElement
		isPrototypeOf(theClass:Object):Boolean Indicates whether an instance of the Object class is in the prototype chain of the object specified as the parameter.	Object
		localToGlobal(point:Point):Point Converts the point object from the object's (local) coordinates to the Stage (global) coordinates.	GraphicElement
		parentChanged(value:Group):void Called by Group when an IGraphicElement is added to or removed from a Group.	GraphicElement
		propertyIsEnumerable(name:String):Boolean Indicates whether the specified property exists and is enumerable.	Object
		removeEventListener(type:String, listener:Function, useCapture:Boolean = false):void Removes a listener from the EventDispatcher object.	EventDispatcher
		setLayoutBoundsPosition(newBoundsX:Number, newBoundsY:Number, postLayoutTransform:Boolean = true):void Sets the coordinates that the element uses to draw on screen.	GraphicElement
		setLayoutBoundsSize(width:Number, height:Number, postLayoutTransform:Boolean = true):void Sets the layout size of the element.	GraphicElement
		setLayoutMatrix(value:Matrix, invalidateLayout:Boolean):void Sets the transform Matrix that is used to calculate the component's layout size and position relative to its siblings.	GraphicElement
		setLayoutMatrix3D(value:Matrix3D, invalidateLayout:Boolean):void Sets the transform Matrix3D that is used to calculate the component's layout size and position relative to its siblings.	GraphicElement
		setPropertyIsEnumerable(name:String, isEnum:Boolean = true):void Sets the availability of a dynamic property for loop operations.	Object
		setSharedDisplayObject(sharedDisplayObject:DisplayObject):Boolean Determines whether this element can draw itself to the sharedDisplayObject of the sequence.	GraphicElement
		toLocaleString():String Returns the string representation of this object, formatted according to locale-specific conventions.	Object
		toString():String Returns the string representation of the specified object.	Object
		transformAround(transformCenter:Vector3D, scale:Vector3D = null, rotation:Vector3D = null, translation:Vector3D = null, postLayoutScale:Vector3D = null, postLayoutRotation:Vector3D = null, postLayoutTranslation:Vector3D = null, invalidateLayout:Boolean = true):void A utility method to update the rotation, scale, and translation of the transform while keeping a particular point, specified in the component's own coordinate space, fixed in the parent's coordinate space.	GraphicElement
		transformPointToParent(localPosition:Vector3D, position:Vector3D, postLayoutPosition:Vector3D):void A utility method to transform a point specified in the local coordinates of this object to its location in the object's parent's coordinates.	GraphicElement
		validateDisplayList():void Called by the parent Group to redraw this element in its displayObject property.	GraphicElement
		validateNow():void Validates and updates the properties and layout of this object by immediately calling validateProperties(), validateSize(), and validateDisplayList(), if necessary.	GraphicElement
		validateProperties():void Used by layout logic to validate the properties of a component by calling the commitProperties() method.	GraphicElement
		validateSize():void Called by the parent Group to validate the size of this element.	GraphicElement
		valueOf():Object Returns the primitive value of the specified object.	Object
		willTrigger(type:String):Boolean Checks whether an event listener is registered with this EventDispatcher object or any of its ancestors for the specified event type.	EventDispatcher

Protected Methods

Show Inherited Protected Methods

	Method		Defined By
		canSkipMeasurement():Boolean Determines if the call to the measure() method can be skipped.	GraphicElement
		commitProperties():void Processes the properties set on the element.	GraphicElement
		getStrokeExtents(postLayoutTransform:Boolean = true):Rectangle Returns the amount of pixels occupied by the stroke on each side of the element's bounds.	GraphicElement
		invalidateDisplayObjectSharing():void Utility method that notifies the host that this element has changed and needs its layer to be updated.	GraphicElement
		invalidateParentSizeAndDisplayList():void Helper method to invalidate parent size and display list if this object affects its layout (includeInLayout is true).	GraphicElement
		measure():void [override] Calculates the default size of the element.	BitmapImage
		preferredHeightPreTransform():Number Used for the implementation of the ILayoutElement interface, returns the explicit of measured height pre-transform.	GraphicElement
		preferredWidthPreTransform():Number Used for the implementation of the ILayoutElement interface, returns the explicit of measured width pre-transform.	GraphicElement
		transformHeightForLayout(width:Number, height:Number, postLayoutTransform:Boolean = true):Number Transform the element's size.	GraphicElement
		transformWidthForLayout(width:Number, height:Number, postLayoutTransform:Boolean = true):Number Transform the element's size.	GraphicElement
		updateDisplayList(unscaledWidth:Number, unscaledHeight:Number):void [override] Draws the element and/or sizes and positions its content.	BitmapImage

Events

Click for more information on events

Hide Inherited Events

Show Inherited Events

	Event		Summary	Defined By
		activate	[broadcast event] Dispatched when the Flash Player or AIR application gains operating system focus and becomes active.	EventDispatcher
		deactivate	[broadcast event] Dispatched when the Flash Player or AIR application operating loses system focus and is becoming inactive.	EventDispatcher

Property Detail

fillMode

property

fillMode:String

Language Version:

ActionScript 3.0

Product Version:

Flex 4

Runtime Versions:

Flash Player 10, AIR 1.5

The fillMode determines how the bitmap fills in the dimensions. If you set the value of this property in a tag, use the string (such as "repeat"). If you set the value of this property in ActionScript, use the constant (such as BitmapFillMode.CLIP). When set to BitmapFillMode.CLIP ("clip"), the bitmap ends at the edge of the region. When set to BitmapFillMode.REPEAT ("repeat"), the bitmap repeats to fill the region. When set to BitmapFillMode.SCALE ("scale"), the bitmap stretches to fill the region.

The default value is BitmapFillMode.SCALE.

Implementation
public function get fillMode():String
public function set fillMode(value:String):void

smooth

property

smooth:Boolean

Language Version:

ActionScript 3.0

Product Version:

Flex 4

Runtime Versions:

Flash Player 10, AIR 1.5

Specifies whether to apply a smoothing algorithm to the bitmap image.

If false, upscaled bitmap images are rendered by using a nearest-neighbor algorithm and look pixelated. If true, upscaled bitmap images are rendered by using a bilinear algorithm. Rendering by using the nearest neighbor algorithm is usually faster.

The default value is false.

Implementation
public function get smooth():Boolean
public function set smooth(value:Boolean):void

source

property

source:Object

Language Version:

ActionScript 3.0

Product Version:

Flex 4

Runtime Versions:

Flash Player 10, AIR 1.5

The source used for the bitmap fill. The fill can render from various graphical sources, including the following:

A Bitmap or BitmapData instance.
A class representing a subclass of DisplayObject. The BitmapFill instantiates the class and creates a bitmap rendering of it.
An instance of a DisplayObject. The BitmapFill copies it into a Bitmap for filling.

If you use an image file for the source, it can be of type PNG, GIF, or JPG.

To specify an image as a source, you must use the @Embed directive, as the following example shows:

      source="@Embed('image_location')"

The image location can be a URL or file reference. If it is a file reference, its location is relative to the location of the file that is being compiled.

If the source is a Bitmap or BitmapData instance, it is the responsibility of the caller to dispose of the source once it is no longer needed. If BitmapImage created the BitmapData instance, then it will dispose of the BitmapData once the source has changed.

Implementation
public function get source():Object
public function set source(value:Object):void

BitmapImage

()

Constructor

public function BitmapImage()

Language Version:

ActionScript 3.0

Product Version:

Flex 4

Runtime Versions:

Flash Player 10, AIR 1.5

Constructor.

Method Detail

measure

()

method

override protected function measure():void

Language Version:

ActionScript 3.0

Product Version:

Flex 4

Runtime Versions:

Flash Player 10, AIR 1.5

Calculates the default size of the element. This is an advanced method that you might override when creating a subclass of GraphicElement.

You do not call this method directly. Flex calls the measure() method when the element is added to a group using the addElement() method, and when the element's invalidateSize() method is called.

By default you set both explicit height and explicit width of an element, Flex does not call the measure() method, even if you explicitly call the invalidateSize() method. To override this behavior, override skipMeasure() method.

In your override of this method, you must set the measuredWidth and measuredHeight properties to define the default size. You can optionally set the measuredX and measuredY properties to define the default measured bounds top-left corner relative to the origin of the element.

The conceptual point of measure() is for the element to provide its own natural or intrinsic bounds as a default. Therefore, the measuredWidth and measuredHeight properties should be determined by factors such as:

The amount of text the component needs to display.
The size of a JPEG image that the component displays.

In some cases, there is no intrinsic way to determine default values. For example, a simple GreenCircle element might simply set measuredWidth = 100 and measuredHeight = 100 in its measure() method to provide a reasonable default size. In other cases, such as a TextArea, an appropriate computation (such as finding the right width and height that would just display all the text and have the aspect ratio of a Golden Rectangle) might be too time-consuming to be worthwhile.

The default implementation of measure() sets the values of the measuredWidth, measuredHeight, measuredX, and measuredY properties to 0.

updateDisplayList

()

method

override protected function updateDisplayList(unscaledWidth:Number, unscaledHeight:Number):void

Language Version:

ActionScript 3.0

Product Version:

Flex 4

Runtime Versions:

Flash Player 10, AIR 1.5

Draws the element and/or sizes and positions its content. This is an advanced method that you might override when creating a subclass of GraphicElement.

You do not call this method directly. Flex calls the updateDisplayList() method when the component is added to a group using the addElement() method, and when the element's invalidateDisplayList() method is called.

This method is where you would do programmatic drawing using methods on the elements's displayObject such as graphics.drawRect().

Parameters

	`unscaledWidth:Number` — Specifies the width of the component, in pixels, in the component's coordinates, regardless of the value of the `scaleX` property of the component.

	`unscaledHeight:Number` — Specifies the height of the component, in pixels, in the component's coordinates, regardless of the value of the `scaleY` property of the component.

Examples ( How to use this example )

BitmapImageExample.mxml

<?xml version="1.0" encoding="utf-8"?>
<!-- BitmapGraphicExample.mxml -->
<s:Application xmlns:fx="http://ns.adobe.com/mxml/2009" xmlns:s="library://ns.adobe.com/flex/spark">

    <s:Panel title="Bitmap Graphic Example"
            width="75%" height="75%"
            horizontalCenter="0" verticalCenter="0">
        <s:Group left="10" right="10" top="10" bottom="10">
            <!-- Single image, not resized, not repeated. -->
            <s:Graphic x="0" y="0">             
                <s:BitmapImage id="bg1" source="@Embed('assets/AirIcon12x12.gif')" fillMode="clip"/>
            </s:Graphic>

            <!-- Single image, scaled to fit specified dimensions. -->
            <s:Graphic x="150" y="0">
                <s:BitmapImage id="bg2" source="@Embed('assets/AirIcon12x12.gif')" width="60" height="60" fillMode="scale"/>
            </s:Graphic>

            <!-- Repeated image to fit specified dimensions. -->
            <s:Graphic x="300" y="0">
                <s:BitmapImage id="bg3" source="@Embed('assets/AirIcon12x12.gif')" width="120" height="120" fillMode="repeat"/>
            </s:Graphic>
        </s:Group>
    </s:Panel>

</s:Application>