flashx.textLayout.compose

# StandardFlowComposer - AS3

Package | flashx.textLayout.compose
Class | public class StandardFlowComposer
Inheritance | StandardFlowComposer FlowComposerBase Object
Implements | IFlowComposer

Language Version: | ActionScript 3.0

Runtime Versions: | Flash Player 10, AIR 1.5

The StandardFlowComposer class provides a standard composer and container manager.

Each call to `compose()` or `updateAllControllers()` normalizes the text flow as a first step. The normalizing process checks the parts of the TextFlow object that were modified and takes the following steps:

1. Deletes empty FlowLeafElement and SubParagraphGroupElement objects.
2. Merges sibling spans that have identical attributes.
3. Adds an empty paragraph if a flow is empty.

To use a StandardFlowComposer, assign it to the `flowComposer` property of a TextFlow object. Call the `updateAllControllers()` method to lay out and display the text in the containers attached to the flow composer.

Note: For simple, static text flows, you can also use the one of the text line factory classes. These factory classes will typically create lines with less overhead than a flow composer, but do not support editing, dynamic changes, or user interaction.

View the examples

More examples

Managing text containers with TLF

Related API Elements

flashx.textLayout.elements.TextFlow.flowComposer

Public Properties
Hide Inherited Public Properties
Show Inherited Public Properties

| Property | Defined By
--- | --- | ---
|  | composing : Boolean [read-only] True, if the flow composer is currently performing a composition operation. | StandardFlowComposer
|  | constructor : Object A reference to the class object or constructor function for a given object instance. | Object
|  | damageAbsoluteStart : int [read-only] The absolute position immediately preceding the first element in the text flow that requires composition and updating. | FlowComposerBase
|  | numControllers : int [read-only] The number of containers assigned to this IFlowComposer instance. | StandardFlowComposer
|  | numLines : int [read-only] The total number of lines composed in the flow. | FlowComposerBase
|  | rootElement : ContainerFormattedElement [read-only] The root element associated with this IFlowComposer instance. | StandardFlowComposer
|  | swfContext : ISWFContext The ISWFContext instance used to make FTE calls as needed. | FlowComposerBase
|  | textFlow : flashx.textLayout.elements:TextFlow [read-only] The TextFlow object to which this flow composer is attached. | FlowComposerBase

Public Methods
Hide Inherited Public Methods
Show Inherited Public Methods

| Method | Defined By
--- | --- | ---
|  | StandardFlowComposer() Creates a StandardFlowComposer object. | StandardFlowComposer
|  | addController(controller:ContainerController):void Adds a controller to this IFlowComposer instance. | StandardFlowComposer
|  | addControllerAt(controller:ContainerController, index:int):void Adds a controller to this IFlowComposer instance at the specified index. | StandardFlowComposer
|  | compose():Boolean Calculates how many lines are necessary to display the content in the root element of the flow and the positions of these lines in the flow's display containers. | StandardFlowComposer
|  | composeToController(index:int):Boolean Composes the content of the root element up to and including the container at the specified index. | StandardFlowComposer
|  | composeToPosition(absolutePosition:int):Boolean Composes the content of the root element up to the specified position. | StandardFlowComposer
|  | damage(startPosition:int, damageLength:int, damageType:String):void Mark lines as damaged and needing a recompose. | FlowComposerBase
|  | findControllerIndexAtPosition(absolutePosition:int, preferPrevious:Boolean = false):int Returns the index of the controller containing the content at the specified position. | StandardFlowComposer
|  | findLineAtPosition(absolutePosition:int, preferPrevious:Boolean = false):flashx.textLayout.compose:TextFlowLine Returns the TextFlowLine object containing the content at the specified position. | FlowComposerBase
|  | findLineIndexAtPosition(absolutePosition:int, preferPrevious:Boolean = false):int Returns the sequential line number of the TextFlowLine object that contains the content at the specified position. | FlowComposerBase
|  | getAbsoluteStart(controller:ContainerController):int Returns the absolute position of the first content element in the specified ContainerController object. | StandardFlowComposer
|  | getControllerAt(index:int):ContainerController Returns the ContainerController object at the specified index. | StandardFlowComposer
|  | getControllerIndex(controller:ContainerController):int Returns the index of the specified ContainerController object. | StandardFlowComposer
|  | getLineAt(index:int):flashx.textLayout.compose:TextFlowLine Returns the line with the specified line number. | FlowComposerBase
|  | hasOwnProperty(name:String):Boolean Indicates whether an object has a specified property defined. | Object
|  | interactionManagerChanged(newInteractionManager:ISelectionManager):void Called by the TextFlow when the interaction manager changes. | StandardFlowComposer
|  | isDamaged(absolutePosition:int):Boolean Indicates whether any TextFlowLine objects between the beginning of the flow and the line containing the content at the specified position are marked as damaged. | FlowComposerBase
|  | 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
|  | removeAllControllers():void Removes all controllers from this IFlowComposer instance. | StandardFlowComposer
|  | removeController(controller:ContainerController):void Removes a controller from this IFlowComposer instance. | StandardFlowComposer
|  | removeControllerAt(index:int):void Removes the controller at the specified index from this IFlowComposer instance. | StandardFlowComposer
|  | setFocus(absolutePosition:int, leanLeft:Boolean = false):void Sets the focus to the container that contains the location specified by the absolutePosition parameter. | StandardFlowComposer
|  | setPropertyIsEnumerable(name:String, isEnum:Boolean = true):void Sets the availability of a dynamic property for loop operations. | Object
|  | setRootElement(newRootElement:ContainerFormattedElement):void | StandardFlowComposer
|  | 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
|  | updateAllControllers():Boolean Composes the content of the root element and updates the display. | StandardFlowComposer
|  | updateLengths(startPosition:int, deltaLength:int):void Update the lengths in the lines to maintain mapping to the TextFlow. | FlowComposerBase
|  | updateToController(index:int):Boolean Composes and updates the display up to and including the container at the specified index. | StandardFlowComposer
|  | valueOf():Object Returns the primitive value of the specified object. | Object

Protected Methods

| Method | Defined By
--- | --- | ---
|  | preCompose():Boolean Returns true if composition is necessary, false otherwise | StandardFlowComposer

Property Detail

### composing

property

`composing:Boolean` [read-only]

Language Version: | ActionScript 3.0

Runtime Versions: | Flash Player 10, AIR 1.5

True, if the flow composer is currently performing a composition operation.

Implementation
`public function get composing():Boolean`

### numControllers

property

`numControllers:int` [read-only]

Language Version: | ActionScript 3.0

Runtime Versions: | Flash Player 10, AIR 1.5

The number of containers assigned to this IFlowComposer instance.

Implementation
`public function get numControllers():int`

### rootElement

property

`rootElement:ContainerFormattedElement` [read-only]

Language Version: | ActionScript 3.0

Runtime Versions: | Flash Player 10, AIR 1.5

The root element associated with this IFlowComposer instance.

Only a TextFlow object can be a root element.

Implementation
`public function get rootElement():ContainerFormattedElement`
Constructor Detail

### StandardFlowComposer

()
Constructor

`public function StandardFlowComposer()`

Language Version: | ActionScript 3.0

Runtime Versions: | Flash Player 10, AIR 1.5

Creates a StandardFlowComposer object.

To use an StandardFlowComposer object, assign it to the `flowComposer` property of a TextFlow object. Call the `updateAllControllers()` method to lay out and display the text in the containers attached to the flow composer.

Example ( How to use this example )
The following example composes a text flow up to and including the container holding the 345th position:
Copy

    package flashx.textLayout.compose.examples
    {
        import flashx.textLayout.elements.TextFlow;
        import flashx.textLayout.compose.StandardFlowComposer;

        public class StandardFlowComposer_constructor
        {
            public function createComposer(textFlow:TextFlow):void
            {
                 textFlow.flowComposer = new StandardFlowComposer();
            }
        }
    }

Method Detail

### addController

()
method

`public function addController(controller:ContainerController):void`

Language Version: | ActionScript 3.0

Runtime Versions: | Flash Player 10, AIR 1.5

Adds a controller to this IFlowComposer instance.

The container is added to the end of the container list.

Parameters

| `controller:ContainerController` — The ContainerController object to add.

Example ( How to use this example )
The following example creates a ContainerController and adds it to a TextFlow object:
Copy

    package flashx.textLayout.compose.examples
    {
        public class StandardFlowComposer_addController
        {
            import flash.display.Sprite;
            import flashx.textLayout.elements.TextFlow;
            import flashx.textLayout.container.ContainerController;

            public function setupController(textFlow:TextFlow):void
            {
                var container:Sprite = new Sprite();
                var controller:ContainerController = new ContainerController( container, 400, 200 );
                textFlow.flowComposer.addController( controller );
            }
        }
    }

### addControllerAt

()
method

`public function addControllerAt(controller:ContainerController, index:int):void`

Language Version: | ActionScript 3.0

Runtime Versions: | Flash Player 10, AIR 1.5

Adds a controller to this IFlowComposer instance at the specified index.

The list of controllers is 0-based (the first controller has an index of 0).

Parameters

| `controller:ContainerController` — The ContainerController object to add.
| `index:int` — A numeric index that specifies the position in the controller list at which to insert the ContainerController object.

Example ( How to use this example )
The following example creates a ContainerController and inserts it as the first container of a TextFlow object:
Copy

    package flashx.textLayout.compose.examples
    {
        public class StandardFlowComposer_addControllerAt
        {
            import flash.display.Sprite;
            import flashx.textLayout.elements.TextFlow;
            import flashx.textLayout.container.ContainerController;

            public function setupController(textFlow:TextFlow):void
            {
                var container:Sprite = new Sprite();
                var controller:ContainerController = new ContainerController( container, 400, 200 );
                textFlow.flowComposer.addControllerAt( controller, 0 );
            }
        }
    }

### compose

()
method

`public function compose():Boolean`

Language Version: | ActionScript 3.0

Runtime Versions: | Flash Player 10, AIR 1.5

Calculates how many lines are necessary to display the content in the root element of the flow and the positions of these lines in the flow's display containers.

The `compose()` method only composes content if it has changed since the last composition operation. Results are saved so that subsequent calls to `compose()` or `updateAllControllers()` do not perform an additional recomposition if the flow content has not changed.

If the contents of any container have changed, the method returns `true`.

Returns

| `Boolean` — true if anything changed.

Related API Elements

updateAllControllers()
updateToController()
Example ( How to use this example )
The following example composes a text flow:
Copy

    package flashx.textLayout.compose.examples
    {
        public class StandardFlowComposer_compose
        {
            import flashx.textLayout.elements.TextFlow;

            public function compose(textFlow:TextFlow):void
            {
                textFlow.flowComposer.compose();
            }
        }
    }

### composeToController

()
method

`public function composeToController(index:int):Boolean`

Language Version: | ActionScript 3.0

Runtime Versions: | Flash Player 10, AIR 1.5

Composes the content of the root element up to and including the container at the specified index.

If the contents of any container up to and including the container at the specified index has changed, the method returns `true`. If `index` is greater than the number of controllers (or not specified), then all containers are composed.

Parameters

| `index:int` (default = `NaN`)`` — compose at least up to this container in the TextFlow. If controllerIndex is greater than the number of controllers, compose to the end of the last container.

Returns

| `Boolean` — true if anything changed.

Example ( How to use this example )
The following example composes a text flow up to the fourth container:
Copy

    package flashx.textLayout.compose.examples
    {
        public class StandardFlowComposer_composeToController
        {
            import flashx.textLayout.elements.TextFlow;

            public function compose(textFlow:TextFlow):void
            {
                textFlow.flowComposer.composeToController( 3 );
            }
        }
    }

### composeToPosition

()
method

`public function composeToPosition(absolutePosition:int):Boolean`

Language Version: | ActionScript 3.0

Runtime Versions: | Flash Player 10, AIR 1.5

Composes the content of the root element up to the specified position.

If the contents of any container up to and including the container holding the content at the specified position has changed, the method returns `true`. If `absolutePosition` is greater than the length of the TextFlow (or not specified), then the entire flow is composed.

Parameters

| `absolutePosition:int` (default = `NaN`)`` — compose at least up to this position in the TextFlow. By default or if absolutePosition is past the end of the flow compose to the end of the flow.

Returns

| `Boolean` — true if anything changed.

Example ( How to use this example )
The following example composes a text flow up to and including the container holding the 345th position:
Copy

    package flashx.textLayout.compose.examples
    {
        public class StandardFlowComposer_composeToPosition
        {
            import flashx.textLayout.elements.TextFlow;

            public function compose(textFlow:TextFlow):void
            {
                textFlow.flowComposer.composeToPosition( 344 );
            }
        }
    }

### findControllerIndexAtPosition

()
method

`public function findControllerIndexAtPosition(absolutePosition:int, preferPrevious:Boolean = false):int`

Language Version: | ActionScript 3.0

Runtime Versions: | Flash Player 10, AIR 1.5

Returns the index of the controller containing the content at the specified position.

A position can be considered to be the division between two characters or other elements of a text flow. If the value in `absolutePosition` is a position between the last character of one container and the first character of the next, then the preceding container is returned if the `preferPrevious` parameter is set to `true` and the later container is returned if the `preferPrevious` parameter is set to `false`.

The method returns -1 if the content at the specified position is not in any container or is outside the range of positions in the text flow.

Parameters

| `absolutePosition:int` — The position of the content for which the container index is sought.
| `preferPrevious:Boolean` (default = `false`)`` — Specifies which container index to return when the position is between the last element in one container and the first element in the next.

Returns

| `int` — the index of the container controller or -1 if not found.

Example ( How to use this example )
The following example gets the index of the container containing the 345th character or element of a text flow:
Copy

    package flashx.textLayout.compose.examples
    {
        import flashx.textLayout.elements.TextFlow;
        import flashx.textLayout.compose.StandardFlowComposer;

        public class StandardFlowComposer_findControllerIndexAtPosition
        {
            public function findControllerIndexAtPosition(textFlow:TextFlow):void
            {
                var index:int = textFlow.flowComposer.findControllerIndexAtPosition( 344 );
            }
        }
    }

### getAbsoluteStart

()
method

`public function getAbsoluteStart(controller:ContainerController):int`

Language Version: | ActionScript 3.0

Runtime Versions: | Flash Player 10, AIR 1.5

Returns the absolute position of the first content element in the specified ContainerController object.

A position is calculated by counting the division between two characters or other elements of a text flow. The position preceding the first element of a flow is zero. An absolute position is the position counting from the beginning of the flow.

Parameters

| `controller:ContainerController` — A ContainerController object associated with this flow composer.

Returns

| `int` — the position before the first character or graphic in the ContainerController.

### getControllerAt

()
method

`public function getControllerAt(index:int):ContainerController`

Language Version: | ActionScript 3.0

Runtime Versions: | Flash Player 10, AIR 1.5

Returns the ContainerController object at the specified index.

Parameters

| `index:int` — The index of the ContainerController object to return.

Returns

| `ContainerController` — the ContainerController object at the specified position.

Example ( How to use this example )
The following example returns a reference to the first ContainerController in a text flow:
Copy

    package flashx.textLayout.compose.examples
    {
        import flashx.textLayout.elements.TextFlow;
        import flashx.textLayout.container.ContainerController;

        public class StandardFlowComposer_getControllerAt
        {
            public function findControllerIndexAtPosition(textFlow:TextFlow):void
            {
                var controller:ContainerController =  textFlow.flowComposer.getControllerAt( 0 );
            }
        }
    }

### getControllerIndex

()
method

`public function getControllerIndex(controller:ContainerController):int`

Language Version: | ActionScript 3.0

Runtime Versions: | Flash Player 10, AIR 1.5

Returns the index of the specified ContainerController object.

Parameters

| `controller:ContainerController` — A reference to the ContainerController object to find.

Returns

| `int` — the index of the specified ContainerController object or -1 if the controller is not attached to this flow composer.

Example ( How to use this example )
The following example returns the index of a controller in a text flow:
Copy

    package flashx.textLayout.compose.examples
    {
        import flashx.textLayout.elements.TextFlow;
        import flashx.textLayout.container.ContainerController;

        public class StandardFlowComposer_getControllerIndex
        {
            public function getControllerIndex(textFlow:TextFlow, controller:ContainerController):void
            {
                var index:int =  textFlow.flowComposer.getControllerIndex( controller );
            }
        }
    }

### interactionManagerChanged

()
method

`public function interactionManagerChanged(newInteractionManager:ISelectionManager):void`

Language Version: | ActionScript 3.0

Runtime Versions: | Flash Player 10, AIR 1.5

Called by the TextFlow when the interaction manager changes.

This function is called automatically. Your code does not typically need to call this method. Classes that extend StandardFlowComposer can override this method to update event listeners and other properties that depend on the interaction manager.

Parameters

| `newInteractionManager:ISelectionManager` — The new ISelectionManager instance.

### preCompose

()
method

`protected function preCompose():Boolean`

Returns true if composition is necessary, false otherwise

Returns

| `Boolean`

### removeAllControllers

()
method

`public function removeAllControllers():void`

Language Version: | ActionScript 3.0

Runtime Versions: | Flash Player 10, AIR 1.5

Removes all controllers from this IFlowComposer instance.

### removeController

()
method

`public function removeController(controller:ContainerController):void`

Language Version: | ActionScript 3.0

Runtime Versions: | Flash Player 10, AIR 1.5

Removes a controller from this IFlowComposer instance.

Parameters

| `controller:ContainerController` — The ContainerController instance to remove.

### removeControllerAt

()
method

`public function removeControllerAt(index:int):void`

Language Version: | ActionScript 3.0

Runtime Versions: | Flash Player 10, AIR 1.5

Removes the controller at the specified index from this IFlowComposer instance.

Parameters

| `index:int` — The index of the ContainerController object to remove.

### setFocus

()
method

`public function setFocus(absolutePosition:int, leanLeft:Boolean = false):void`

Language Version: | ActionScript 3.0

Runtime Versions: | Flash Player 10, AIR 1.5

Sets the focus to the container that contains the location specified by the `absolutePosition` parameter.

The StandardFlowComposer calls the `setFocus()` method of the ContainerController object containing the specified text flow position.

Parameters

| `absolutePosition:int` — Specifies the position in the text flow of the container to receive focus.
| `leanLeft:Boolean` (default = `false`)`` — If true and the position is before the first character in a container, sets focus to the end of the previous container.

Related API Elements

flash.display.Stage.focus

### setRootElement

()
method

`public function setRootElement(newRootElement:ContainerFormattedElement):void`

Language Version: | ActionScript 3.0

Runtime Versions: | Flash Player 10, AIR 1.5

Parameters

| `newRootElement:ContainerFormattedElement`

### updateAllControllers

()
method

`public function updateAllControllers():Boolean`

Language Version: | ActionScript 3.0

Runtime Versions: | Flash Player 10, AIR 1.5

Composes the content of the root element and updates the display.

Text layout is conducted in two phases: composition and display. In the composition phase, the flow composer calculates how many lines are necessary to display the content as well as the position of these lines in the flow's display containers. In the display phase, the flow composer updates the display object children of its containers. The `updateAllControllers()` method initiates both phases in sequence. The StandardFlowComposer keeps track of changes to content so that a full cycle of composition and display is only performed when necessary.

This method updates all the text lines and the display list immediately and synchronously.

If the contents of any container is changed, the method returns `true`.

Returns

| `Boolean` — true if anything changed.

### updateToController

()
method

`public function updateToController(index:int):Boolean`

Language Version: | ActionScript 3.0

Runtime Versions: | Flash Player 10, AIR 1.5

Composes and updates the display up to and including the container at the specified index.

The `updateToController()` method composes the content and updates the display of all containers up to and including the container at the specified index. For example, if you have a chain of 20 containers and specify an index of 10, `updateToController()` ensures that the first through the tenth (indexes 0-9) containers are composed and displayed. Composition stops at that point. If `controllerIndex` is -1 (or not specified), then all containers are updated.

This method updates all the text lines and the display list immediately and synchronously.

If the contents of any container is changed, the method returns `true`.

Parameters

| `index:int` (default = `NaN`)`` — index of the last container to update (by default updates all containers)

Returns

| `Boolean` — `true`, if anything changed.

Examples How to use this example
StandardFlowComposer_ClassExample.as
The following example creates, composes, and displays a text flow with two containers. The text flow is created by using the TextConverter `importToFlow()` method.
Copy

    package flashx.textLayout.compose.examples {
        import flash.display.Sprite;

        import flashx.textLayout.compose.StandardFlowComposer;
        import flashx.textLayout.container.ContainerController;
        import flashx.textLayout.conversion.TextConverter;
        import flashx.textLayout.elements.TextFlow;

        public class StandardFlowComposer_ClassExample extends Sprite
        {
            private var poem:String = "Sonnet 18\n" +
            "Shall I compare thee to a summer's day?\n" +
            "Thou art more lovely and more temperate:\n" +
            "Rough winds do shake the darling buds of May,\n" +
            "And summer's lease hath all too short a date:\n" +
            "Sometime too hot the eye of heaven shines,\n" +
            "And often is his gold complexion dimmed,\n" +
            "And every fair from fair sometime declines,\n" +
            "By chance, or nature's changing course untrimmed:\n" +
            "But thy eternal summer shall not fade,\n" +
            "Nor lose possession of that fair thou ow'st,\n" +
            "Nor shall death brag thou wand'rest in his shade,\n" +
            "When in eternal lines to time thou grow'st,\n" +
            "So long as men can breathe or eyes can see,\n" +
            "So long lives this, and this gives life to thee.\n" +
            "William Shakespeare\n";

            private var flow:TextFlow;

            public function StandardFlowComposer_ClassExample()
            {
                var firstContainer:Sprite = new Sprite();
                firstContainer.x = 180;
                firstContainer.y = 30;
                this.stage.addChild( firstContainer );

                var secondContainer:Sprite = new Sprite();
                secondContainer.x = 30;
                secondContainer.y = 130
                this.stage.addChild( secondContainer );

                var firstController:ContainerController = new ContainerController( firstContainer, 300, 100 );
                var secondController:ContainerController = new ContainerController( secondContainer, 800, 600 );

                flow = TextConverter.importToFlow( poem, TextConverter.PLAIN_TEXT_FORMAT );
                flow.flowComposer = new StandardFlowComposer();;

                flow.flowComposer.addController( firstController );
                flow.flowComposer.addController( secondController );

                flow.flowComposer.updateAllControllers();
            }
        }
    }

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