mx.managers

# LayoutManager - AS3 Flex

Package | mx.managers
Class | public class LayoutManager
Inheritance | LayoutManager EventDispatcher Object
Implements | ILayoutManager

Language Version: | ActionScript 3.0

Product Version: | Flex 3

Runtime Versions: | Flash Player 9, AIR 1.1

The LayoutManager is the engine behind Flex's measurement and layout strategy. Layout is performed in three phases; commit, measurement, and layout.

Each phase is distinct from the others and all UIComponents of one phase are processed prior to moving on to the next phase. During the processing of UIComponents in a phase, requests for UIComponents to get re-processed by some phase may occur. These requests are queued and are only processed during the next run of the phase.

The commit phase begins with a call to `validateProperties()`, which walks through a list (reverse sorted by nesting level) of objects calling each object's `validateProperties()` method.

The objects in the list are processed in reversed nesting order, with the least deeply nested object accessed first. This can also be referred to as top-down or outside-in ordering.

This phase allows components whose contents depend on property settings to configure themselves prior to the measurement and the layout phases. For the sake of performance, sometimes a component's property setter method does not do all the work to update to the new property value. Instead, the property setter calls the `invalidateProperties()` method, deferring the work until this phase runs. This prevents unnecessary work if the property is set multiple times.

The measurement phase begins with a call to `validateSize()`, which walks through a list (sorted by nesting level) of objects calling each object's `validateSize()` method to determine if the object has changed in size.

If an object's `invalidateSize()` method was previously called, then the `validateSize()` method is called. If the size or position of the object was changed as a result of the `validateSize()` call, then the object's `invalidateDisplayList()` method is called, thus adding the object to the processing queue for the next run of the layout phase. Additionally, the object's parent is marked for both measurement and layout phases, by calling `invalidateSize()` and `invalidateDisplayList()` respectively.

The objects in the list are processed by nesting order, with the most deeply nested object accessed first. This can also be referred to as bottom-up inside-out ordering.

The layout phase begins with a call to the `validateDisplayList()` method, which walks through a list (reverse sorted by nesting level) of objects calling each object's `validateDisplayList()` method to request the object to size and position all components contained within it (i.e. its children).

If an object's `invalidateDisplayList()` method was previously called, then `validateDisplayList()` method for the object is called.

The objects in the list are processed in reversed nesting order, with the least deeply nested object accessed first. This can also be referred to as top-down or outside-in ordering.

In general, components do not override the `validateProperties()`, `validateSize()`, or `validateDisplayList()` methods. In the case of UIComponents, most components override the `commitProperties()`, `measure()`, or `updateDisplayList()` methods, which are called by the `validateProperties()`, `validateSize()`, or `validateDisplayList()` methods, respectively.

At application startup, a single instance of the LayoutManager is created and stored in the `UIComponent.layoutManager` property. All components are expected to use that instance. If you do not have access to the UIComponent object, you can also access the LayoutManager using the static `LayoutManager.getInstance()` method.

Learn more

Layouts in sandboxed applications
Layouts in multi-versioned applications

Public Properties
Hide Inherited Public Properties
Show Inherited Public Properties

| Property | Defined By
--- | --- | ---
|  | constructor : Object A reference to the class object or constructor function for a given object instance. | Object
|  | usePhasedInstantiation : Boolean A flag that indicates whether the LayoutManager allows screen updates between phases. | LayoutManager

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. | EventDispatcher
|  | attachListeners(systemManager:ISystemManager):void | LayoutManager
|  | dispatchEvent(event:Event):Boolean Dispatches an event into the event flow. | EventDispatcher
|  | getInstance():LayoutManager [static] Returns the sole instance of this singleton class, creating it if it does not already exist. | LayoutManager
|  | hasEventListener(type:String):Boolean Checks whether the EventDispatcher object has any listeners registered for a specific type of event. | EventDispatcher
|  | hasOwnProperty(name:String):Boolean Indicates whether an object has a specified property defined. | Object
|  | invalidateDisplayList(obj:ILayoutManagerClient):void Called when a component changes in some way that its layout and/or visuals need to be changed. | LayoutManager
|  | invalidateProperties(obj:ILayoutManagerClient):void Adds an object to the list of components that want their validateProperties() method called. | LayoutManager
|  | invalidateSize(obj:ILayoutManagerClient):void Adds an object to the list of components that want their validateSize() method called. | LayoutManager
|  | isInvalid():Boolean Returns true if there are components that need validating; false if all components have been validated. | LayoutManager
|  | isPrototypeOf(theClass:Object):Boolean Indicates whether an instance of the Object class is in the prototype chain of the object specified as the parameter. | Object
|  | propertyIsEnumerable(name:String):Boolean Indicates whether the specified property exists and is enumerable. | Object
|  | removeEventListener(type:String, listener:Function, useCapture:Boolean = false):void Removes a listener from the EventDispatcher object. | EventDispatcher
|  | setPropertyIsEnumerable(name:String, isEnum:Boolean = true):void Sets the availability of a dynamic property for loop operations. | Object
|  | toLocaleString():String Returns the string representation of this object, formatted according to locale-specific conventions. | Object
|  | toString():String Returns the string representation of the specified object. | Object
|  | validateClient(target:ILayoutManagerClient, skipDisplayList:Boolean = false):void When properties are changed, components generally do not apply those changes immediately. | LayoutManager
|  | validateNow():void When properties are changed, components generally do not apply those changes immediately. | LayoutManager
|  | valueOf():Object Returns the primitive value of the specified object. | Object
|  | 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. | EventDispatcher

Events
Click for more information on events
Hide Inherited Events
Show Inherited Events

| Event | Summary | Defined By
--- | --- | --- | ---
|  | activate | [broadcast event] Dispatched when the Flash Player or AIR application gains operating system focus and becomes active. | EventDispatcher
|  | deactivate | [broadcast event] Dispatched when the Flash Player or AIR application operating loses system focus and is becoming inactive. | EventDispatcher

Property Detail

### usePhasedInstantiation

property

`usePhasedInstantiation:Boolean`

Language Version: | ActionScript 3.0

Product Version: | Flex 3

Runtime Versions: | Flash Player 9, AIR 1.1

A flag that indicates whether the LayoutManager allows screen updates between phases. If `true`, measurement and layout are done in phases, one phase per screen update. All components have their `validateProperties()` and `commitProperties()` methods called until all their properties are validated. The screen will then be updated.

Then all components will have their `validateSize()` and `measure()` methods called until all components have been measured, then the screen will be updated again.

Finally, all components will have their `validateDisplayList()` and `updateDisplayList()` methods called until all components have been validated, and the screen will be updated again. If in the validation of one phase, an earlier phase gets invalidated, the LayoutManager starts over. This is more efficient when large numbers of components are being created an initialized. The framework is responsible for setting this property.

If `false`, all three phases are completed before the screen is updated.

Implementation
`public function get usePhasedInstantiation():Boolean`
`public function set usePhasedInstantiation(value:Boolean):void`
Method Detail

### attachListeners

()
method

`public function attachListeners(systemManager:ISystemManager):void`

Parameters

| `systemManager:ISystemManager`

### getInstance

()
method

`public static function getInstance():LayoutManager`

Language Version: | ActionScript 3.0

Product Version: | Flex 3

Runtime Versions: | Flash Player 9, AIR 1.1

Returns the sole instance of this singleton class, creating it if it does not already exist.

Returns

| `LayoutManager` — Returns the sole instance of this singleton class, creating it if it does not already exist.

### invalidateDisplayList

()
method

`public function invalidateDisplayList(obj:ILayoutManagerClient):void`

Language Version: | ActionScript 3.0

Product Version: | Flex 3

Runtime Versions: | Flash Player 9, AIR 1.1

Called when a component changes in some way that its layout and/or visuals need to be changed. In that case, it is necessary to run the component's layout algorithm, even if the component's size hasn't changed. For example, when a new child component is added, or a style property changes or the component has been given a new size by its parent.

Parameters

| `obj:ILayoutManagerClient` — The object that changed.

### invalidateProperties

()
method

`public function invalidateProperties(obj:ILayoutManagerClient):void`

Language Version: | ActionScript 3.0

Product Version: | Flex 3

Runtime Versions: | Flash Player 9, AIR 1.1

Adds an object to the list of components that want their `validateProperties()` method called. A component should call this method when a property changes. Typically, a property setter method stores a the new value in a temporary variable and calls the `invalidateProperties()` method so that its `validateProperties()` and `commitProperties()` methods are called later, when the new value will actually be applied to the component and/or its children. The advantage of this strategy is that often, more than one property is changed at a time and the properties may interact with each other, or repeat some code as they are applied, or need to be applied in a specific order. This strategy allows the most efficient method of applying new property values.

Parameters

| `obj:ILayoutManagerClient` — The object whose property changed.

### invalidateSize

()
method

`public function invalidateSize(obj:ILayoutManagerClient):void`

Language Version: | ActionScript 3.0

Product Version: | Flex 3

Runtime Versions: | Flash Player 9, AIR 1.1

Adds an object to the list of components that want their `validateSize()` method called. Called when an object's size changes.

An object's size can change for two reasons:

1. The content of the object changes. For example, the size of a button changes when its `label` is changed.
2. A script explicitly changes one of the following properties: `minWidth`, `minHeight`, `explicitWidth`, `explicitHeight`, `maxWidth`, or `maxHeight`.

When the first condition occurs, it's necessary to recalculate the measurements for the object. When the second occurs, it's not necessary to recalculate the measurements because the new size of the object is known. However, it's necessary to remeasure and relayout the object's parent.

Parameters

| `obj:ILayoutManagerClient` — The object whose size changed.

### isInvalid

()
method

`public function isInvalid():Boolean`

Language Version: | ActionScript 3.0

Product Version: | Flex 3

Runtime Versions: | Flash Player 9, AIR 1.1

Returns `true` if there are components that need validating; `false` if all components have been validated.

Returns

| `Boolean` — Returns `true` if there are components that need validating; `false` if all components have been validated.

### validateClient

()
method

`public function validateClient(target:ILayoutManagerClient, skipDisplayList:Boolean = false):void`

Language Version: | ActionScript 3.0

Product Version: | Flex 3

Runtime Versions: | Flash Player 9, AIR 1.1

When properties are changed, components generally do not apply those changes immediately. Instead the components usually call one of the LayoutManager's invalidate methods and apply the properties at a later time. The actual property you set can be read back immediately, but if the property affects other properties in the component or its children or parents, those other properties may not be immediately updated.

To guarantee that the values are updated, you can call the `validateClient()` method. It updates all properties in all components whose nest level is greater than or equal to the target component before returning. Call this method only when necessary as it is a computationally intensive call.

Parameters

| `target:ILayoutManagerClient` — The component passed in is used to test which components should be validated. All components contained by this component will have their `validateProperties()`, `commitProperties()`, `validateSize()`, `measure()`, `validateDisplayList()`, and `updateDisplayList()` methods called.
| `skipDisplayList:Boolean` (default = `false`)`` — If `true`, does not call the `validateDisplayList()` and `updateDisplayList()` methods.

### validateNow

()
method

`public function validateNow():void`

Language Version: | ActionScript 3.0

Product Version: | Flex 3

Runtime Versions: | Flash Player 9, AIR 1.1

When properties are changed, components generally do not apply those changes immediately. Instead the components usually call one of the LayoutManager's invalidate methods and apply the properties at a later time. The actual property you set can be read back immediately, but if the property affects other properties in the component or its children or parents, those other properties may not be immediately updated. To guarantee that the values are updated, you can call the `validateNow()` method. It updates all properties in all components before returning. Call this method only when necessary as it is a computationally intensive call.

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