Functional and Design Specification

Glossary

Not applicable.

Summary and Background

The primary driver of this feature is Adobe Flash Catalyst. This feature and API set is intended to be used primarily by design tools.

Flash Catalyst currently leverages DesignLayer language tags which allow the design-time layer structure to be expressed and retained within the MXML document itself. In the initial pre-release version of Flex 4.0, the MXML compiler essentially ignored the design layer tags at compile time. The intended visibility and alpha of a layer are stored as custom meta-data by Catalyst and propagated by the tool down to children of the layers themselves. This process has proven unwieldy and error prone.

In 4.1, the DesignLayer will become a runtime object on which you can directly set the "visible" and "alpha" properties. At compile time the DesignLayer elements will be extracted from the DOM along with their visual element associations (layer children) and at runtime they will be addressable like any other runtime component instance. The design layers themselves will not exist as part of the visual element hierarchy but will be associated with their layer children much like RadioButtons are associated with RadioButtonGroup instances.

Usage Scenarios

A Flash Catalyst designer has made use of several design-time layers in her interactive. She has designated that one or more of the layers are to be invisible when her applet is in a given state. She has also authored an effect sequences that animates the alpha property of another layer when transitioning between several states. The Runtime Design Layer feature simplifies the MXML code generated by Flash Catalyst in this case, as the tool can now make use of state-specific visible and alpha properties directly on the design layers themselves.

Detailed Description

• The DesignLayer is still considered to be a language tag and is scoped to the 2009 language namespace.
• Design layers will support three properties: id, visible, and alpha.
• DesignLayer tags will support state-specific visible and alpha values (e.g. visible.StateA="false").
• DesignLayer tags will not support the includeIn, excludeFrom, itemCreationPolicy, and itemDestructionPolicy attributes.
• The IVisualElement interface will be extended to include a designLayer property.
• The Flex SDK will retrofit the (4) types that implement IVisualElement (e.g. UIComponent, GraphicElement, SpriteVisualElement, and UIMovieClip) with the logic necessary to subscribe to layer attribute changes and to consider their associated layer's alpha or visibility when ultimately committing their effective alpha or visibility.
• DesignLayer instances will dispatch a LayerPropertyChanged event whenever their effective visibility or effective alpha changes..either directly or indirectly. e.g. If layer B is parented by layer A and layer A's alpha changes, both layer A and layer B will ultimately dispatch a LayerPropertyChanged event to their layer children, notifying of the new effective property values at their specific level of the layer hierarchy.
• When the alpha or visible properties of an IVisualElement instance are set at runtime, the instance will consider the effective alpha or visibility of its associated layer before committing the actual value. The DesignLayer class will provide effectiveAlpha and effectiveVisibility properties to facilitate this use case.
• When queried for its visible or alpha property, the IVisualElement will continue to return its own visible or alpha, not the effective value. This is consistent with how the intrinsic alpha and visible properties work today.
• When a layered element is reparented at runtime (or removed and returned to the display list), it will retain its original layer association.
• The compiler will optimize away any design layer that is considered a "noop". A layer that has no id specified (is not addressable at runtime), and has the equivalent of the default values for both alpha and visible is considered a candidate for optimization. Layers with no attributes at all are by definition noop layers as well. Layer children of optimized (stripped) layers will be hoisted up to parent layers if applicable.
• Nothing about the DesignLayer component should preclude its use with the Fade effect. e.g. Because the DesignLayer supports an alpha and visible property. Catalyst requires that the Fade effect functions as designed when targeting a layer instance.

API Description

The IVisualElement interface will be extended as follows. All SDK provided implementers of IVisualElement (UIComponent, GraphicElement, SpriteVisualElement, and UIMovieClip) will be extended accordingly.

package mx.core
{

public interface IVisualElement extends ILayoutElement
{
    /**
     *  Specifies the optional DesignLayer instance associated with this visual 
     *  element.  
     *
     *  <p>When a DesignLayer is assigned, a visual element must consider the 
     *  visibility and alpha of its parent layer when ultimately committing its 
     *  own effective visibility or alpha to its backing DisplayObject (if 
     *  applicable).</p>
     *
     *  <p>A visual element must listen for <code>layerPropertyChange</code>
     *  notifications from the associated layer parent.  When the 
     *  <code>effectiveAlpha</code> or <code>effectiveVisibility</code> of the 
     *  layer changes, the element must then compute its own effective visibility 
     *  (or alpha) and apply it accordingly.</p>
     *
     *  <p>The <code>designLayer</code> property is not used for z-order control, 
     *  please @see #depth.</p>
     *
     *  <p>This property should not be set within MXML directly.</p>

     */
    function get designLayer():DesignLayer;

    /**
     *  @private
     */
    function set designLayer(value:DesignLayer):void;
}

}

A new DesignLayer class will be introduced to the mx.core package.

package mx.core
{  
/**
 *  Dispatched by the layer when either <code>effectiveVisibility</code> or 
 *  <code>effectiveAlpha</code> changes.
 *  
 *  @langversion 3.0
 *  @playerversion Flash 9
 *  @playerversion AIR 1.1
 *  @productversion Flex 3
 */
<a href="Event%28name%3D%26quot%3BlayerPropertyChange%26quot%3B%2C%20type%3D%26quot%3Bmx.events.PropertyChangeEvent%26quot%3B%29">Event(name="layerPropertyChange", type="mx.events.PropertyChangeEvent")</a>

/**
 *  The DesignLayer class represents a visibility group that can be associated
 *  with one or more IVisualElement instances at runtime.  
 * 
 *  DesignLayer instances support a <code>visible</code> and alpha property 
 *  that when set will propagate to the associated layer children.
 *
 *  @langversion 3.0
 *  @playerversion Flash 9
 *  @playerversion AIR 1.1
 *  @productversion Flex 4
 */
public class DesignLayer extends EventDispatcher implements IMXMLObject
{  
    //----------------------------------
    //  id
    //----------------------------------

    /**
     *  ID of the layer component. This value becomes the instance name of the layer
     *  and as such, should not contain any white space or special characters. 
     */
    public function get id():String;
    public function set id(value:String):void;

    //----------------------------------
    //  parent
    //----------------------------------

    /**
     *  This layer's parent layer. 
     *  
     *  @default null
     */  
    public function get parent():DesignLayer;

    //----------------------------------
    //  visible
    //----------------------------------

    /**
     *  The visibility for this design layer instance.
     *
     *  <p>When updated, the appropriate change event for <code>effectiveVisibility</code> 
     *  will be dispatched to all <code>layerPropertyChange<code> listeners for 
     *  this layer, as well as those of affected descendant layers if any.</p>
     *
     *  @default true
     */
    public function get visible():Boolean;        
    public function set visible(value:Boolean):void;

    //----------------------------------
    //  effectiveVisibility
    //----------------------------------

    /**
     *  Returns the effective visibility of this design layer (which considers 
     *  the visibility of this layer as well as any ancestor layers).   
     * 
     *  @default true
     */ 
    public function get effectiveVisibility():Boolean;

    /**
     * @private
     * Used to notify the visual elements associated with this layer
     * that the effective visibility has changed.  Dispatches a 
     * "layerPropertyChange" event with property field set to 
     * "effectiveVisibility".
     */  
    protected function effectiveVisibilityChanged(value:Boolean):void;

    //----------------------------------
    //  alpha
    //----------------------------------

    /**
     *  The alpha for this design layer instance.
     *
     *  <p>When updated, the appropriate change event for <code>effectiveAlpha</code> 
     *  will be dispatched to all <code>layerPropertyChange</code> listeners 
     *  for this layer, as well as those of affected descendant layers if any.</p>
     *
     *  @default 1.0
     */
    public function get alpha():Number;
    public function set alpha(value:Number):void;

    //----------------------------------
    //  effectiveAlpha
    //----------------------------------

    /**
     *  Property that returns the effective alpha of this design layer
     *  (which considers the alpha of this layer multiplied with the alpha of 
     *  any ancestor layers).      
     * 
     *  @default 1.0
     */ 
    public function get effectiveAlpha():Number

    /**
     * @private
     * Used to notify the visual elements associated with this layer
     * that the effective alpha has changed.  Dispatches a "layerPropertyChange"
     * event with the property field set to "effectiveAlpha".
     */  
    protected function effectiveAlphaChanged(oldAlpha:Number):void;

    //--------------------------------------------------------------------------
    //
    //  Methods
    //
    //--------------------------------------------------------------------------

    /**
     *  The number of DesignLayer children directly parented by this layer.
     *
     *  @default 0
     */
     public function get numLayers():int;

    /**
     *  Returns the DesignLayer child at the specified index.
     *
     *  <p>Note that the order of DesignLayer children is insignificant.
     *  The <code>getLayerAt</code> method is meant to be used in
     *  conjunction with numLayers to iterate over the child list.</p>
     *
     *  @param index The 0-based index of a DesignLayer child.
     *
     *  @return The specified DesignLayer child if index is between
     *  0 and <code>numLayers</code> - 1.  Returns
     *  <code>null</code> if the index is invalid.
     * 
     *  @see numLayers
     */
     public function getLayerAt(index:int):DesignLayer

    /**
     *  Adds a DesignLayer child to this layer.
     *
     *  @param value The layer child to add.
     */
     public function addLayer(value:DesignLayer):void;

    /**
     *  Removes a DesignLayer child from this layer.
     *
     *  @param value The layer child to remove.
     */
     public function removeLayer(value:DesignLayer):void;

    /**
     * IMXMLObject implementation provides access to id information at runtime.
     *
     *  @param document The MXML document (not used).
     *  @param id The MXML id attribute.
     */
     public function initialized(document:Object, id:String):void
}
}

B Features

• When a Reparent language tag is used to reparent a visual element in a given state, the element will adopt the Reparent tag's immediate layer parent (if any) while in the associated state. The element will be returned to its original layer parent (if any) when the original state is restored.

Examples and Usage

At runtime when 'myButton' is queried for its intrinsic alpha property (e.g. mx_internal:$alpha), it will return 0.375, which is ultimately the cumulative alpha of itself (1.0) and its layer hierarchy (the alpha for layer A and layer B):

<fx:DesignLayer id="A" alpha="0.75">
    <fx:DesignLayer id="B" alpha="0.50">
       <s:Button label="My Button" id="myButton" />
    </fx:DesignLayer>
</fx:DesignLayer>

When the button's visible property is changed from false to true, the button will still not be visible due to the fact that its owning layer hierarchy still computes to visible=false (due to layer A):

<fx:DesignLayer id="A" visible="false">
    <fx:DesignLayer id="B">
       <s:Button label="My Button" id="myButton" visible="false" />
    </fx:DesignLayer>
</fx:DesignLayer>

The following example recreates the layer hierarchy in the first example above dynamically.

import mx.core.DesignLayer;

private function createLayerHierarchy():void
{
    var layerA:DesignLayer = new DesignLayer();
    layerA.alpha = 0.75;
    var layerB:DesignLayer = new DesignLayer();
    layerB.alpha = 0.5;
    layerA.addLayer(layerB);
    myButton.designLayer = layerB;
}

Additional Implementation Details

Not applicable.

Prototype Work

A prototype exists and has been checked into the Flex 4 trunk. The implementation will be modified as necessary to account for specification changes or related feedback.

Compiler Work

At a high level…

The MXML compiler will assign design layer associations early during the scanning phase. The SyntaxAnalyzer will remove all instances of the DesignLayer tag from the actual document hierarchy (as it does today). During the "builder" phase all realized DesignLayer models will be constructed and assigned to the 'layerParent' property of associated 'Model' instances. During code generation, the layer initializers will be generated prior to all other top level initializers in the MXML document. When a visual component is initialized its layer (if any) will be assigned after all other properties have been initialized on the component instance.

Web Tier Compiler Impact

A new compiler flag is provided to enable runtime design layer code generation (-enable-runtime-design-layers). This flag is provided only for the short term, and will be removed once the tools have had sufficient time to integrate the feature.

Flex Feature Dependencies

Not applicable.

Backwards Compatibility

Syntax changes

The DesignLayer language tag now supports the id, alpha, and visible properties.

Behavior

DesignLayer instances are now a runtime concept as per the details presented in this specification.

Warnings/Deprecation

Not applicable.

Accessibility

Not applicable.

Performance

DesignLayer hierarchies as generated by Catalyst have a tendency to be verbose, so as mentioned prior, the compiler will optimize away design layers that do not have either an 'id' or a value specified for visible or alpha. Layers with no 'id' and the defaults specified for both alpha and visible will also be compiled out. Layer children of optimized layers will be hoisted up to parent layers if applicable.

Globalization

Not applicable.

Localization

Compiler Features

Not applicable.

Framework Features

Not applicable.

Issues and Recommendations

Not applicable at this time.

Documentation

Not applicable.

QA

Suggested focus areas and test cases to consider (not exhaustive):

• Test that MXML DesignLayer attributes other than id, visible, alpha are disallowed.
• Test that visible property set on DesignLayer is honored.
• Test that alpha property set on DesignLayer is honored.
• Test that visible property of DesignLayer is queryable at runtime.
• Test that alpha property of DesignLayer is queryable at runtime.
• Test that nested design layers correctly function when alpha and visible properties are set in MXML.
• Test that nested design layers correctly function when alpha and visible properties are set at runtime.
• Test that the Fade transition works with DesignLayer instances.
• Test that you can create a DesignLayer dynamically at runtime and associate it with a visual element.
• Test that design layers work properly with UIComponent, SpriteVisualElement, GraphicElement, and UIMovieClip instances.
• Test that you can clear (set to null) a layer property of a previously layered visual element at runtime.
• Test that removing a previously layered visual element does not leak the element (making sure to clear document references to the element if it has an id, and set its designLayer property to null to disassociate with its layer).
• Test state-specific layer properties (e.g. alpha.stateA or visible.stateB).
• Test that includeIn and excludeFrom are disallowed on DesignLayer tags.