Menu
▾
▴
IGraphicElement
There is a newer version of this page. You can find it here.
# IGraphicElement - Functional and Design Specification
----
## Glossary
----
* Shared DisplayObject - this is a DisplayObject that is being drawn to by multiple separate graphic elements. For example three rectangular graphic elements can draw to the same Sprite.
* Sequence - this is a sequence of one or more graphic elements that share the same DisplayObject. The Group maintains the graphic elements in sequences.
* Shared index - this is the index of a DisplayObject in its sequence.
* Rendering order - the order in which the children of a container render. This is well-defined at all times.
## Summary and Background
----
With the heavy skinning-oriented Gumbo, we are in need of light-weight (memory-wise) graphics primitives. Since every single display object brings a lot of overhead, the primary way of acheiving this is by minimizing the number of display objects. In Gumbo we're introducing the Group and GraphicElment relationship:
* The Group can host GraphicElements.
* GraphicElements can share DisplayObjects (in most common cases - no mask, no rotation, no 3D, etc.)
* The Group manages when the DisplayObjects are created and at what index they are added.
* The Group organizes the GEs into shared sequences.
The goal of this spec is to formalize the relationship between GraphicElements and Group with interface contracts, so that anyone can implement a custom graphic element, without the need to extend the Gumbo GraphicElement base class.
## Usage Scenarios
----
Enable implementation of lighter-weight VisualElements that:
* Share a DisplayObject and draw in its graphics property
* Some examples are Rect, Path, Line, BitmapImage, Ellipse
* Don't share a DisplayObject, but instead creates/gets a DisplayObject from a different source
* Some examples are VideoElement, SimpleText, RichText
## Detailed Description
----
### IGraphicElement Interface Goals and Requirements
* The IGraphicalElement interface has to allow the Group to specify the shared DisplayObject.
* set/get DisplayObject
* Interface is simple and relatively easy to implement. It should not require too much special bookkeeping around the shared DisplayObject.
* If a IGE is not going to share DOs, but only takes advantage of the Group's DO management, the it should not be required to have its DOs implement ISharedGraphicsDisplayObject.
* Group maintains creation and assignment of the DisplayObject.
* Group maintains a "sharedIndex" property on IGraphicElement - this index in the sequence of elements with shared DisplayObjects
* Group makes sure to efficiently draw all elements of the sequence if any element has requested redrawing - the shared DisplayObject has minimal obligations to implement ISharedDisplayObject which has a single property "redrawRequested".
* Allow custom implementations of IGraphicElement to have custom requirements for the shared DisplayObject (don't impose limits the type of the DisplayObject).
* IGraphicElements perform the actual creation of the DisplayObjects whenever the Group demands a new one. Group is responsible to call this efficiently.
* IGraphicElements can check the offered DisplayObject for their custom requirements and they can reject it, if it's not worthy - a method "canDrawToShared(displayObject:DisplayObject):Boolean". Group is responsible for calling this method efficiently with the correct arguments.
* The GraphicElement subclasses have a minimal requirement for the graphics property - they need a DisplayObject that implements "ISharedGraphicsDisplayObject"
* The GraphicElement classes should be able to share the DisplayObject of the Group itself - Group will implement "ISharedGraphicsDisplayObject" as well.
* IGraphicElement can select to use a shared DO, but don't allow any following GE to use it (IGE can specify itself as the end of the sequence). This is useful in the case where an IGE uses the shared DO in such a way that any following IGEs can't correctly render into it, for example if an IGE adds child DOs to a shared DO, no other IGEs should render to the shared DO, as the rendering order would be wrong.
* IGE can throw away a DO when it doesn't need it anymore.
* IGE can request re-evaluation of the shared sequences.
* IGE can request to be redrawn.
### How Group Organizes the Sequences of GraphicElements
The rendering order of the GraphicElements, as with any child of a GroupBase container, is well defined by GroupBase. By default the rendering order is the same as the child order, and explicit layer property can be set to allow for a rendering order, different from the child order. The important part is that there's a particular rendering order that is well defined.
Lets take a look at any three graphic elements A, B, C, such that renderingOrder(A) < renderingOrder(B) < renderingOrder(C). We can see that if A and C are drawing to the same DisplayObject, then: *Either B must also draw to the same DisplayObject *Or B's drawing must not overlap with A's and C's drawing.
The second clause "B's drawing must not overlap with A's and C's drawing" is hard/expensive to evaluate. Therefore Group will take the conservative approach and always assume that all graphic element drawings always overlap. Thus for a graphic element A and C to share a DisplayObject, B must also share the same DisplayObject.
This leads to the Group's algorithm of creating/assigning display objects to graphic elements. The Group will go through a rendering-order sorted list of elements and always keep track of the current sequence of elements with shared display object. If the current element can share the display object, then extend the current sequence, otherwise start a new sequence with that element. The Group ensures that the display objects are sorted in the correct rendering order defined by the elements.
### Sketches of various GraphicElements and the corresponding Group and DisplayObject tree
* The Group logic decides how to assign the DisplayObjects based on calls to the IGraphicElement.
* The Elements don't allow sharing of DisplayObjects when they are going to set some specific property on the DisplayObject (example: alpha, scale, rotation, filters, mask, etc.)
* Currently Group has some specific implementation around "layer" which produces sub-optimal DisplayObject sharing, but developers should not rely on the behavior, as it may change in the future.
Diagram 1:
* The Rectangles draw to the Group's graphics directly
* The Button is not a IGraphicElement, it's an UIComponent and it is added directly as a child of the Group
* The Ellipse needs to render on top of the Button, so it's assigned its own DisplayObject (InvalidatingSprite).
* Group.numElements = 4, Group.numChildren = 2, 3 DisplayObjects in total (excluding children of Button).
Diagram 2:
* The Ellipse has been configured with layer="-1" property, so it needs to render first. Therefore it gets assigned a DisplayObject that's the first child of the Group.
* The first two Rect elements render after the Ellipse and can share their own DisplayObject.
* The last two Rect elements also can share a DisplayObject.
* Note that when we have layer property, we don't necessarily implement the most optimal DisplayObject sharing, in fact the Group's logic of how to assign DisplayObject may change in future versions and could, for example, assign all the Rects a single DisplayObject.
* Group.numElements = 5, Group.numChildren = 3, 4 DisplayObjects in total.
Diagram 3:
* The Rects draw directly to the Group's graphics
* The SimpleText generates a DisplayObject for each text line, and adds them as children of the Group.
* The Last Rect has to render above the text, so it gets assigned its own DisplayObject (InvalidatingSprite).
* Group.numElements = 4, Group.numChildren = 1 + n, where n is the number of text lines.
Diagram 4:
* First Rect draws directly to the Group
* Second and third Rect have properties that need to be set directly on a Display Object (alpha="0.5") and hence they get assigned their own DisplayObjects
* The last two Rects share a DisplayObject
* Group.numElements = 5, Group.numChildren = 3
Diagram 5:
* The first Rect needs its own DisplayObject as it has alpha="0.5"
* Second Rect gets assigned its own DisplayObject as the first Rect won't share its own.
* The two SimpleText elements add their text lines directly to the Group
* The last Rect also gets assigned its own DisplayObject as there is no available to share.
* Group.numElements = 5, Group.numChildren = 3 + n, where n is the number of text lines.
Diagram 6:
* The first Rect draws directly to the Group
* The SimpleText has alpha="0.5" so it needs a DisplayObject to set the alpha on, therefore it gets assigned its own. The text lines are added as children to the DisplayObject.
* Group.numElements = 2, Group.numChildren = 1 + n, where n is the number of text lines.
## API Description
----
package spark.core
{
/**
* ISharedDisplayObject defines the minimum requirements for a
*
DisplayObject to be shared between IGraphicElement
* objects.
*
* Group uses ISharedDisplayObject to manage
* invalidation and redrawing of sequences of IGraphicElement
* objects that share a DisplayObject.
*
* Typically when implementing a custom IGraphicElement
* Developers also implement this interface for the DisplayObject
* that the custom IGraphicElement creates.
*/
public interface ISharedDisplayObject
{
/**
* True when any of the IGraphicElement objects, that share
* this DisplayObject, needs to redraw. This is used internally
* by the Group class and developers don't typically use this.
* The Group sets and reads back this property in order to
* determine which graphic elements to validate.
*
* @langversion 3.0
* @playerversion Flash 10
* @playerversion AIR 1.5
* @productversion Flex 4
*/
function get redrawRequested():Boolean;
function set redrawRequested(value:Boolean):void;
}
}
package spark.core
{
import flash.display.DisplayObject;
import flash.display.DisplayObjectContainer;
import spark.components.Group;
import mx.core.IVisualElement;
/**
* 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.
GraphicElement class
* instead of directly implementing the IGraphciElement
* interface as GraphicElement already provides most of the
* required functionality.
*
*/
public interface IGraphicElement extends IVisualElement
{
//--------------------------------------------------------------------------
//
// Properties
//
//--------------------------------------------------------------------------
//----------------------------------
// displayObject
//----------------------------------
/**
* The shared DisplayObject where this
* IGraphicElement is drawn.
*
* Implementers should not create the DisplayObject
* here, but in createDisplayObject().
*
* @see #createDisplayObject
* @see #validateDisplayList
* @see #sharedIndex
*
* @langversion 3.0
* @playerversion Flash 10
* @playerversion AIR 1.5
* @productversion Flex 4
*/
function get displayObject():DisplayObject;
//----------------------------------
// sharedIndex
//----------------------------------
/**
* The index of this IGraphicElement in the sequence
* of elements that share the same DisplayObject.
*
* A value of -1 indicates that this element doesn't
* share its displayObject with other elements and its sequence
* doesn't contain any other elements.
*
* A value of 0 or greater indicates the position of this element in its
* sequence.
*
* A value of 0 also indicates that this element creates the
* DisplayObject for its sequence.
*
* Group manages this property.
*
* @see #displayObject
* @see #createDisplayObject
*
* @langversion 3.0
* @playerversion Flash 10
* @playerversion AIR 1.5
* @productversion Flex 4
*/
function get sharedIndex():int;
/**
* @private
*/
function set sharedIndex(value:int):void;
//--------------------------------------------------------------------------
//
// Methods
//
//--------------------------------------------------------------------------
/**
* 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.
*
* Group will ensure 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.
Group
* graphicElementLayerChanged() 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
* discardDisplayObject() method.
*
* @return The display object created
* @see #displayObject
* @see spark.components.Group#graphicElementLayerChanged
* @see spark.components.Group#discardDisplayObject
*
*/
function createDisplayObject():DisplayObject;
/**
* 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 DisplayObject 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, layer, etc.
displayObject property must return the same display object.
*
* Note that in certain cases the sharedDisplayObject may 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
* graphicElementLayerChanged() method.
IGraphicElement can draw itself
* to the shared DisplayObject of the sequence.
*
* @see #canShareWithPrevious
* @see #canShareWithNext
* @see spark.components.Group#graphicElementLayerChanged
*
*/
function setSharedDisplayObject(sharedDisplayObject:DisplayObject):Boolean;
/**
* Return true if this IGraphicElement is compatible and can
* share display objects with the previous IGraphicElement
* in the sequence.
*
* Note that in certain cases the element may be passed offered the parent
* Group itself in a call to setSharedDisplayObject.
* In those cases, this method won't be called.
IGraphicElement is compatible and can
* share display objects with the next IGraphicElement
* in the sequence.
*
* @param element The element that comes after this element in the sequence.
* @return Returns true when this element is compatible with the previous
* element in the sequence.
*
* @see #canShareWithPrevious
* @see #setSharedDisplayObject
*
*/
function canShareWithNext(element:IGraphicElement):Boolean;
/**
* Called by Group when an IGraphicElement
* is added to or removed from a Group.
* Developers typically never need to call this method.
*
* @param parent The parent group of this IGraphicElement.
*
*/
function parentChanged(parent:Group):void;
/**
* Called by the parent Group to validate the properties of
* this element.
*
* To ensure this method is called, notify the parent Group
* by calling its graphicElementPropertiesChanged() method.
*
* Note that this method may be called even if this element have not
* notified the parent Group.
*
* @see #validateSize
* @see #validateDisplayList
*
*/
function validateProperties():void;
/**
* 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 this method is called, notify the parent Group
* by calling its graphicElementSizeChanged() method.
*
* Note that this method may be called even if this element have not
* notified the parent Group.
*
* @see #validateProperties
* @see #validateDisplayList
*
*/
function validateSize():void;
/**
* Called by the parent Group to redraw this element
* in its displayObject property.
*
* If the element is the first in the sequence (sharedIndex
* is less than or equal to zero) 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 validateDisplayList() was called
* as 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 graphicElementSizeChanged() method.
Note that this method may be called even if this element have not
* notified the parent Group.
DisplayObject from this Group's
* display list.
*
* The Group also ensures any elements that share the
* DisplayObject will be redrawn.
*
* This method doesn't necessarily trigger new DisplayObject
* reassignment for the passed in element.
* To request new display object reassignment, call the
* graphicElementLayerChanged method.
[[ include ref='flexsdk_rightnav' ]]
[[ include ref='site:open_commentlogin' ]]
