spark.core.IGraphicElement - Adobe® Flex® 4 Language Reference (Flex 4)

Package	spark.core
Interface	public interface IGraphicElement extends IVisualElement , ILayoutElement , IEventDispatcher
Implementors	GraphicElement

Language Version:

ActionScript 3.0

Product Version:

Flex 4

Runtime Versions:

Flash Player 10, AIR 1.5

The IGraphicElement is implemented by IVisualElements that take advantage of the parent Group's DisplayObject management.

One typical use case is DisplayObject sharing. Group organizes its IGraphicElement children in sequences that share and draw to the same DisplayObject. The DisplayObject is created by the first element in the sequence.

Another use case is when an element does not derrive from DisplayObject but instead maintains, creates and/or destroys its own DisplayObject. The Group will ensure to call the element to create the DisplayObject, add the DisplayObject as its child at the correct index as well as handle its removal.

Typically a developer extends the GraphicElement class instead of directly implementing the IGraphciElement interface. The GraphicElement class already provides most of the required functionality.

Public Properties

Hide Inherited Public Properties

Show Inherited Public Properties

	Property		Defined By
		alpha : Number Indicates the alpha transparency value of the object specified.	IVisualElement
		baseline : Object The vertical distance in pixels from the anchor target to the control's baseline position.	ILayoutElement
		baselinePosition : Number [read-only] The y-coordinate of the baseline of the first line of text of the component.	ILayoutElement
		bottom : Object The vertical distance in pixels from the bottom edge of the component to the anchor target's bottom edge.	ILayoutElement
		depth : Number Determines the order in which items inside of containers are rendered.	IVisualElement
		designLayer : DesignLayer Specifies the optional DesignLayer instance associated with this visual element.	IVisualElement
		displayObject : DisplayObject [read-only] The shared DisplayObject where this IGraphicElement is drawn.	IGraphicElement
		displayObjectSharingMode : String Indicates the association between this IGraphicElement and its display objects.	IGraphicElement
		hasLayoutMatrix3D : Boolean [read-only] Contians true if the element has 3D Matrix.	ILayoutElement
		height : Number Indicates the height of the display object, in pixels.	IVisualElement
		horizontalCenter : Object The horizontal distance in pixels from the center of the component to the center of the anchor target's content area.	ILayoutElement
		includeInLayout : Boolean Specifies whether this component is included in the layout of the parent container.	ILayoutElement
		is3D : Boolean [read-only] Contains true when the element is in 3D.	IVisualElement
		left : Object The horizontal distance in pixels from the left edge of the component to the anchor target's left edge.	ILayoutElement
		owner : DisplayObjectContainer The owner of this IVisualElement object.	IVisualElement
		parent : DisplayObjectContainer [read-only] The parent container or component for this component.	IVisualElement
		percentHeight : Number Number that specifies the height of a component as a percentage of its parent's size.	ILayoutElement
		percentWidth : Number Number that specifies the width of a component as a percentage of its parent's size.	ILayoutElement
		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.	IVisualElement
		right : Object The horizontal distance in pixels from the right edge of the component to the anchor target's right edge.	ILayoutElement
		top : Object The vertical distance in pixels from the top edge of the component to the anchor target's top edge.	ILayoutElement
		verticalCenter : Object The vertical distance in pixels from the center of the component to the center of the anchor target's content area.	ILayoutElement
		visible : Boolean Controls the visibility of this visual element.	IVisualElement
		width : Number Indicates the width of the display object, in pixels.	IVisualElement
		x : Number Indicates the x coordinate of the DisplayObject instance relative to the local coordinates of the parent DisplayObjectContainer.	IVisualElement
		y : Number Indicates the y coordinate of the DisplayObject instance relative to the local coordinates of the parent DisplayObjectContainer.	IVisualElement

Public Methods

Hide Inherited Public Methods

Show Inherited Public Methods

	Method		Defined By
		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.	IEventDispatcher
		canShareWithNext(element:IGraphicElement):Boolean Returns true if this IGraphicElement is compatible and can share display objects with the next IGraphicElement in the sequence.	IGraphicElement
		canShareWithPrevious(element:IGraphicElement):Boolean Returns true if this IGraphicElement is compatible and can share display objects with the previous IGraphicElement in the sequence.	IGraphicElement
		createDisplayObject():DisplayObject Creates a new DisplayObject where this IGraphicElement is drawn.	IGraphicElement
		dispatchEvent(event:Event):Boolean Dispatches an event into the event flow.	IEventDispatcher
		getBoundsXAtSize(width:Number, height:Number, postLayoutTransform:Boolean = true):Number Returns the x coordinate of the element's bounds at the specified element size.	ILayoutElement
		getBoundsYAtSize(width:Number, height:Number, postLayoutTransform:Boolean = true):Number Returns the y coordinate of the element's bounds at the specified element size.	ILayoutElement
		getLayoutBoundsHeight(postLayoutTransform:Boolean = true):Number Returns the element's layout height.	ILayoutElement
		getLayoutBoundsWidth(postLayoutTransform:Boolean = true):Number Returns the element's layout width.	ILayoutElement
		getLayoutBoundsX(postLayoutTransform:Boolean = true):Number Returns the x coordinate that the element uses to draw on screen.	ILayoutElement
		getLayoutBoundsY(postLayoutTransform:Boolean = true):Number Returns the y coordinate that the element uses to draw on screen.	ILayoutElement
		getLayoutMatrix():Matrix Returns the transform matrix that is used to calculate the component's layout relative to its siblings.	ILayoutElement
		getLayoutMatrix3D():Matrix3D Returns the layout transform Matrix3D for this element.	ILayoutElement
		getMaxBoundsHeight(postLayoutTransform:Boolean = true):Number Returns the element's maximum height.	ILayoutElement
		getMaxBoundsWidth(postLayoutTransform:Boolean = true):Number Returns the element's maximum width.	ILayoutElement
		getMinBoundsHeight(postLayoutTransform:Boolean = true):Number Returns the element's minimum height.	ILayoutElement
		getMinBoundsWidth(postLayoutTransform:Boolean = true):Number Returns the element's minimum width.	ILayoutElement
		getPreferredBoundsHeight(postLayoutTransform:Boolean = true):Number Returns the element's preferred height.	ILayoutElement
		getPreferredBoundsWidth(postLayoutTransform:Boolean = true):Number Returns the element's preferred width.	ILayoutElement
		hasEventListener(type:String):Boolean Checks whether the EventDispatcher object has any listeners registered for a specific type of event.	IEventDispatcher
		parentChanged(parent:Group):void Called by Group when an IGraphicElement is added to or removed from a Group.	IGraphicElement
		removeEventListener(type:String, listener:Function, useCapture:Boolean = false):void Removes a listener from the EventDispatcher object.	IEventDispatcher
		setLayoutBoundsPosition(x:Number, y:Number, postLayoutTransform:Boolean = true):void Sets the coordinates that the element uses to draw on screen.	ILayoutElement
		setLayoutBoundsSize(width:Number, height:Number, postLayoutTransform:Boolean = true):void Sets the layout size of the element.	ILayoutElement
		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.	ILayoutElement
		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.	ILayoutElement
		setSharedDisplayObject(sharedDisplayObject:DisplayObject):Boolean Determines whether this element can draw itself to the sharedDisplayObject of the sequence.	IGraphicElement
		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.	ILayoutElement
		validateDisplayList():void Called by the parent Group to redraw this element in its displayObject property.	IGraphicElement
		validateProperties():void Called by the parent Group to validate the properties of this element.	IGraphicElement
		validateSize():void Called by the parent Group to validate the size of this element.	IGraphicElement
		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.	IEventDispatcher

Property Detail

displayObject

property

displayObject:DisplayObject [read-only]

Language Version:

ActionScript 3.0

Product Version:

Flex 4

Runtime Versions:

Flash Player 10, AIR 1.5

The shared DisplayObject where this IGraphicElement is drawn.

Implementers should not create the DisplayObject here, but in the createDisplayObject() method.

Implementation
public function get displayObject():DisplayObject

displayObjectSharingMode

property

displayObjectSharingMode:String

Indicates the association between this IGraphicElement and its display objects. The Group manages this property and the values are one of the DisplayObjectSharingMode enum class.

A value of DisplayObjectSharingMode.OWNS_UNSHARED_OBJECT indicates that the IGraphicElement owns exclusively the DisplayObject corresponding to its displayObject property.
A value of DisplayObjectSharingMode.OWNS_SHARED_OBJECT indicates taht the IGraphicElement owns the DisplayObject corresponding to its displayObject property but other IGraphicElements are using/drawing to that display object as well. Depending on the specific implementation, the IGraphicElement may perform certain management of the display object. For example the base class GraphicElement clears the transform of the display object, reset its visibility, alpha, etc. properties to their default values and additionally clear the graphics on every validateDisplayList() call.
A value of DisplayObjectSharingMode.USES_SHARED_OBJECT indicates that the IGraphicElement draws into the DisplayObject corresponding to its displayObject property. There are one or more IGraphicElements that draw into that same displayObject, and the first element that draws has its mode set to DisplayObjectMode.OWNS_SHARED_OBJECT

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

Method Detail

canShareWithNext

()

method

public function canShareWithNext(element:IGraphicElement):Boolean

Language Version:

ActionScript 3.0

Product Version:

Flex 4

Runtime Versions:

Flash Player 10, AIR 1.5

Returns true if this IGraphicElement is compatible and can share display objects with the next IGraphicElement in the sequence.

Parameters

element:IGraphicElement — The element that comes after this element in the sequence.

Returns

Boolean — Returns true when this element is compatible with the previous element in the sequence.

canShareWithPrevious

()

method

public function canShareWithPrevious(element:IGraphicElement):Boolean

Language Version:

ActionScript 3.0

Product Version:

Flex 4

Runtime Versions:

Flash Player 10, AIR 1.5

Returns true if this IGraphicElement is compatible and can share display objects with the previous IGraphicElement in the sequence.

In certain cases the element might be passed to the parent Group itself in a call to the setSharedDisplayObject() method. In those cases, this method is not called.

Parameters

element:IGraphicElement — The element that comes before this element in the sequence.

Returns

Boolean — Returns true when this element is compatible with the previous element in the sequence.

See also

canShareWithNext
setSharedDisplayObject

createDisplayObject

()

method

public function createDisplayObject():DisplayObject

Language Version:

ActionScript 3.0

Product Version:

Flex 4

Runtime Versions:

Flash Player 10, AIR 1.5

Creates a new DisplayObject where this IGraphicElement is drawn. Subsequent calls to the getter of the displayObject property must return the same display object. After the DisplayObject is created, the parent Group will pass along the display objects to the rest of the elements in the sequence. The Group ensures that this method is called only when needed.

If the element wants to participate in the DisplayObject sharing, then the new DisplayObject must implement IShareableDisplayObject. This interface is being used by the Group to manage invalidation and redrawing of the graphic element sequence and typically is not directly used by the Developer.

To reevaluate the shared sequences, call the parent Group invalidateGraphicElementSharing() method.

To force the Group to remove the element's current DisplayObject from its display list and recalculate the display object sharing, call the parent Group's discardDisplayObject() method.

Returns

DisplayObject — The display object created.

parentChanged

()

method

public function parentChanged(parent:Group):void

Language Version:

ActionScript 3.0

Product Version:

Flex 4

Runtime Versions:

Flash Player 10, AIR 1.5

Called by Group when an IGraphicElement is added to or removed from a Group.

Developers typically never need to call this method.

Parameters

parent:Group — The parent group of this IGraphicElement.

setSharedDisplayObject

()

method

public function setSharedDisplayObject(sharedDisplayObject:DisplayObject):Boolean

Language Version:

ActionScript 3.0

Product Version:

Flex 4

Runtime Versions:

Flash Player 10, AIR 1.5

Determines whether this element can draw itself to the sharedDisplayObject of the sequence.

Typically implementers will return true when this IGraphicElement can cumulatively draw in the shared DisplayObject graphics property. In all cases where this IGraphicElement needs to set properties on the DisplayObjects that don't apply to the rest of the elements in the sequence, this method must return false. Examples for such properties are rotation, scale, transform, mask, alpha, filters, color transform, 3D, and layer.

When this method returns true, subsequent calls to the getter of the displayObject property must return the same display object.

In certain cases, the sharedDisplayObject property might be the parent Group itself. In the rest of the cases, the DisplayObject is created by the first element in the sequence.

When this IGraphicElement needs to rebuild its sequence, it notifies the parent Group by calling its invalidateGraphicElementSharing() method.

Parameters

sharedDisplayObject:DisplayObject

Returns

Boolean — Returns true when this IGraphicElement can draw itself to the shared DisplayObject of the sequence.

validateDisplayList

()

method

public function validateDisplayList():void

Language Version:

ActionScript 3.0

Product Version:

Flex 4

Runtime Versions:

Flash Player 10, AIR 1.5

Called by the parent Group to redraw this element in its displayObject property.

If the element is the first in the sequence (displayObjectSharingMode is set to DisplayObjectSharingMode.OWNS_SHARED_OBJECT) then it must clear the displayObject graphics and set it up as necessary for drawing the rest of the elements.

The element must alway redraw even if it itself has not changed since the last time the validateDisplayList() method was called. The parent Group will redraw the whole sequence if any of its elements need to be redrawn.

To ensure this method is called, notify the parent Group by calling its invalidateGraphicElementSize() method.

This method might be called even if this element has not notified the parent Group.

validateProperties

()

method

public function validateProperties():void

Language Version:

ActionScript 3.0

Product Version:

Flex 4

Runtime Versions:

Flash Player 10, AIR 1.5

Called by the parent Group to validate the properties of this element.

To ensure that this method is called, notify the parent Group by calling its invalidateGraphicElementProperties() method.

This method might be called even if this element has not notified the parent Group.

See also

validateSize
validateDisplayList

validateSize

()

method

public function validateSize():void

Language Version:

ActionScript 3.0

Product Version:

Flex 4

Runtime Versions:

Flash Player 10, AIR 1.5

Called by the parent Group to validate the size of this element.

When the size of the element changes and is going to affect the parent Group layout, the implementer is responsible for invalidating the parent's size and display list.

To ensure that this method is called, notify the parent Group by calling its invalidateGraphicElementSize() method.

This method might be called even if this element has not notified the parent Group.

See also

validateProperties
validateDisplayList