spark.core

# IGraphicElement - AS3 Flex

Package | spark.core
Interface | public interface IGraphicElement extends IVisualElement , ILayoutElement , ILayoutDirectionElement , 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 `IGraphicElementContainer` DisplayObject management.

One typical use case is DisplayObject sharing. the Group class, which implements `IGraphicElementContainer`, 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 derive from DisplayObject but instead maintains, creates and/or destroys its own DisplayObject. The `IGraphicElementContainer` will call the element to create the DisplayObject, add the DisplayObject as its child at the correct index, and handle its removal.

Typically, you extend the GraphicElement class instead of directly implementing the IGraphciElement interface. The GraphicElement class already provides most of the required functionality.

More examples

Groups in FXG and MXML graphics
Shapes in FXG and MXML graphics
Text in FXG and MXML graphics
Fills in FXG and MXML graphics
Bitmap graphics in FXG and MXML graphics
Effects in FXG and MXML graphics

Related API Elements

spark.core.IGraphicElementContainer

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] Contains 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
|  | layoutDirection : String Specifies the desired layout direction for an element: one of LayoutDirection.LTR (left to right), LayoutDirection.RTL (right to left), or null (inherit). | ILayoutDirectionElement
|  | 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 Specifies the height of a component as a percentage of its parent's size. | ILayoutElement
|  | percentWidth : Number 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
|  | invalidateLayoutDirection():void An element must call this method when its layoutDirection changes or when its parent's layoutDirection changes. | ILayoutDirectionElement
|  | parentChanged(parent:IGraphicElementContainer):void Called by IGraphicElementContainer when an IGraphicElement is added to or removed from the host component. | 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 IGraphicElementContainer to redraw this element in its displayObject property. | IGraphicElement
|  | validateProperties():void Called by the IGraphicElementContainer to validate the properties of this element. | IGraphicElement
|  | validateSize():void Called by the IGraphicElementContainer 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`

Related API Elements

createDisplayObject
validateDisplayList
displayObjectSharingMode

### displayObjectSharingMode

property

`displayObjectSharingMode:String`

Language Version: | ActionScript 3.0

Product Version: | Flex 4.5

Runtime Versions: | Flash Player 10, AIR 2.5

Indicates the association between this IGraphicElement and its display objects. The `IGraphicElementContainer` 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.

Related API Elements

canShareWithPrevious
setSharedDisplayObject

### 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 `IGraphicElementContainer` 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.

Related API Elements

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 `IGraphicElementContainer` will pass along the display objects to the rest of the elements in the sequence.

The `IGraphicElementContainer` 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 `IGraphicElementContainer` 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 `invalidateGraphicElementSharing()` method on the `IGraphicElementContainer`.

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

Returns

| `DisplayObject` — The display object created.

Related API Elements

displayObject
spark.core.IGraphicElementContainer.invalidateGraphicElementSharing
spark.core.IGraphicElementContainer.discardDisplayObject

### parentChanged

()
method

`public function parentChanged(parent:IGraphicElementContainer):void`

Language Version: | ActionScript 3.0

Product Version: | Flex 4

Runtime Versions: | Flash Player 10, AIR 1.5

Called by `IGraphicElementContainer` when an IGraphicElement is added to or removed from the host component.

You typically never need to call this method.

Parameters

| `parent:IGraphicElementContainer` — The `IGraphicElementContainer` 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 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 `IGraphicElementContainer` 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 `IGraphicElementContainer` by calling its `invalidateGraphicElementSharing()` method.

Parameters

| `sharedDisplayObject:DisplayObject` — The shared DisplayObject.

Returns

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

Related API Elements

canShareWithPrevious
canShareWithNext
spark.core.IGraphicElementContainer.invalidateGraphicElementSharing

### 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 `IGraphicElementContainer` 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 `IGraphicElementContainer` will redraw the whole sequence if any of its elements need to be redrawn.

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

This method might be called even if this element has not notified the `IGraphicElementContainer`.

Related API Elements

displayObject
validateProperties
validateSize

### 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 `IGraphicElementContainer` to validate the properties of this element.

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

This method might be called even if this element has not notified the `IGraphicElementContainer`.

Related API Elements

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 `IGraphicElementContainer` to validate the size of this element.

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

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

This method might be called even if this element has not notified the `IGraphicElementContainer`.

Related API Elements

validateProperties
validateDisplayList

© 2015 Adobe Systems Incorporated. All rights reserved.
Mon Apr 10 2017, 12:28 PM -07:00