Packagefeathers.core
Classpublic class DisplayListWatcher
InheritanceDisplayListWatcher Inheritance starling.events.EventDispatcher

Watches a container on the display list. As new display objects are added, and if they match a specific type, they will be passed to initializer functions to set properties, call methods, or otherwise modify them. Useful for initializing skins and styles on UI controls.

Note: This class is no longer recommended as a base class for themes. See Custom Feathers themes for complete details.

In the example below, the buttonInitializer() function will be called when a Button is added to the display list, and no values are specified in its styleNameList that match other initializers:

     setInitializerForClass(Button, buttonInitializer);

You can specify a value in the button's styleNameList to call a different initializer for a button. You might do this to apply different skins for some buttons:

     var button:Button = new Button();
     button.label = "Click Me";
     button.styleNameList.add( Button.ALTERNATE_STYLE_NAME_CALL_TO_ACTION );
     this.addChild( button );

The callToActionButtonInitializer() function will be called when a Button with the Button.ALTERNATE_STYLE_NAME_CALL_TO_ACTION value is added to its styleNameList:

     setInitializerForClass( Button, callToActionButtonInitializer, Button.ALTERNATE_STYLE_NAME_CALL_TO_ACTION );

Initializers are not called for subclasses. If a Check is added to the display list (Check extends Button), the buttonInitializer() function will not be called. This important restriction allows subclasses to have different skins.

You can target a specific subclass with the same initializer function without adding it for all subclasses:

     setInitializerForClass(Button, buttonInitializer);
     setInitializerForClass(Check, buttonInitializer);

In this case, Button and Check will trigger the buttonInitializer() function, but Radio (another subclass of Button) will not.

You can target a class and all of its subclasses, using a different function. This is recommended only when you are absolutely sure that no subclasses will need a separate initializer.

     setInitializerForClassAndSubclasses(Button, buttonInitializer);

In this case, Button, Check, Radio and every other subclass of Button (including any subclasses that you create yourself) will trigger the buttonInitializer() function.



Public Properties
 PropertyDefined By
  initializeOnce : Boolean
Determines if objects added to the display list are initialized only once or every time that they are re-added.
DisplayListWatcher
  processRecursively : Boolean = true
Determines if only the object added should be processed or if its children should be processed recursively.
DisplayListWatcher
  requiredBaseClass : Class
The minimum base class required before the AddedWatcher will check to see if a particular display object has any initializers.
DisplayListWatcher
Protected Properties
 PropertyDefined By
  root : DisplayObjectContainer
The root of the display list that is watched for added children.
DisplayListWatcher
Public Methods
 MethodDefined By
  
DisplayListWatcher(topLevelContainer:DisplayObjectContainer)
Constructor.
DisplayListWatcher
  
clearInitializerForClass(type:Class, withName:String = null):void
If an initializer exists for a specific class, it will be removed completely.
DisplayListWatcher
  
If an initializer exists for a specific class and its subclasses, the initializer will be removed completely.
DisplayListWatcher
  
dispose():void
Stops listening to the root and cleans up anything else that needs to be disposed.
DisplayListWatcher
  
exclude(target:DisplayObject):void
Excludes a display object, and all if its children (if any) from being watched.
DisplayListWatcher
  
getInitializerForClass(type:Class, withName:String = null):Function
If an initializer exists for a specific class, it will be returned.
DisplayListWatcher
  
If an initializer exists for a specific class and its subclasses, the initializer will be returned.
DisplayListWatcher
  
initializeObject(target:DisplayObject):void
Immediately initialize an object.
DisplayListWatcher
  
isExcluded(target:DisplayObject):Boolean
Determines if an object is excluded from being watched.
DisplayListWatcher
  
setInitializerForClass(type:Class, initializer:Function, withName:String = null):void
Sets the initializer for a specific class.
DisplayListWatcher
  
setInitializerForClassAndSubclasses(type:Class, initializer:Function):void
Sets an initializer for a specific class and any subclasses.
DisplayListWatcher
Property Detail
initializeOnceproperty
initializeOnce:Boolean

Determines if objects added to the display list are initialized only once or every time that they are re-added. Disabling this property will allow you to reinitialize a component when it is removed and added to the display list. However, this may also unnecessarily reinitialize components that have not changed, which will affect performance.

The default value is true.


Implementation
    public function get initializeOnce():Boolean
    public function set initializeOnce(value:Boolean):void
processRecursivelyproperty 
public var processRecursively:Boolean = true

Determines if only the object added should be processed or if its children should be processed recursively. Disabling this property may improve performance slightly, but it limits the capabilities of DisplayListWatcher.

In the following example, children are not processed recursively:

         watcher.processRecursively = false;

The default value is true.

requiredBaseClassproperty 
public var requiredBaseClass:Class

The minimum base class required before the AddedWatcher will check to see if a particular display object has any initializers.

In the following example, the required base class is changed:

         watcher.requiredBaseClass = Sprite;

The default value is feathers.core.IFeathersControl.

rootproperty 
protected var root:DisplayObjectContainer

The root of the display list that is watched for added children.

Constructor Detail
DisplayListWatcher()Constructor
public function DisplayListWatcher(topLevelContainer:DisplayObjectContainer)

Constructor.

Parameters
topLevelContainer:DisplayObjectContainer — The root display object to watch (not necessarily Starling's stage or root object)
Method Detail
clearInitializerForClass()method
public function clearInitializerForClass(type:Class, withName:String = null):void

If an initializer exists for a specific class, it will be removed completely.

Parameters

type:Class
 
withName:String (default = null)

clearInitializerForClassAndSubclasses()method 
public function clearInitializerForClassAndSubclasses(type:Class):void

If an initializer exists for a specific class and its subclasses, the initializer will be removed completely.

Parameters

type:Class

dispose()method 
public function dispose():void

Stops listening to the root and cleans up anything else that needs to be disposed. If a DisplayListWatcher is extended for a theme, it should also dispose textures and other assets.

exclude()method 
public function exclude(target:DisplayObject):void

Excludes a display object, and all if its children (if any) from being watched.

Parameters

target:DisplayObject

getInitializerForClass()method 
public function getInitializerForClass(type:Class, withName:String = null):Function

If an initializer exists for a specific class, it will be returned.

Parameters

type:Class
 
withName:String (default = null)

Returns
Function
getInitializerForClassAndSubclasses()method 
public function getInitializerForClassAndSubclasses(type:Class):Function

If an initializer exists for a specific class and its subclasses, the initializer will be returned.

Parameters

type:Class

Returns
Function
initializeObject()method 
public function initializeObject(target:DisplayObject):void

Immediately initialize an object. Useful for initializing components that are already on stage when this DisplayListWatcher is created.

If the object has already been initialized, it won't be initialized again. However, it's children may be initialized, if they haven't been initialized yet.

Parameters

target:DisplayObject

isExcluded()method 
public function isExcluded(target:DisplayObject):Boolean

Determines if an object is excluded from being watched.

In the following example, we check if a display object is excluded:

         if( watcher.isExcluded( image ) )
         {
             // this display object won't be processed by the watcher
         }

Parameters

target:DisplayObject

Returns
Boolean
setInitializerForClass()method 
public function setInitializerForClass(type:Class, initializer:Function, withName:String = null):void

Sets the initializer for a specific class.

Parameters

type:Class
 
initializer:Function
 
withName:String (default = null)

setInitializerForClassAndSubclasses()method 
public function setInitializerForClassAndSubclasses(type:Class, initializer:Function):void

Sets an initializer for a specific class and any subclasses. This option can potentially hurt performance, so use sparingly.

Parameters

type:Class
 
initializer:Function