FTE Layout Tricks with BreakOpportunity.ALL
by Paul Taylor, Jun. 2, 2011, under [ actionscript ]

This should be a relatively short post, since it’s late and I’ve been drinking. I’m going to focus on just one property from ElementFormat: breakOpportunity.

Cunning Line Breaks

BreakOpportunity is relatively straightforward. It directs the Flash Text Engine of when to break new TextLines. It’s different from the standard unicode line breaking control character, the break-if-you-wanna Zero-width space character, and it isn’t the soft hyphen used in auto-hyphenation engines.

BreakOpportunity is subtler. It gives you control over line breaks without inserting control characters into your content.

Documentation

Here’s the documentation of breakOpportunity. I’m pasting it here to illustrate that this doesn’t tell the whole story.

String value Description
BreakOpportunity.ALL All characters in the range are treated as line break opportunities, meaning that a line break will occur after each character. Useful for creating effects like text on a path.
Subclass Effect of setting property
GraphicElement Has no effect.
GroupElement Determines the break opportunity between adjacent text elements in the group. If the elementFormat of the group is null, the format of the first of the adjacent elements is used.
TextElement Determines the break opportunity between the characters in the text element.


Standard Line Breaking

I’ve posted this before, but here’s a refresher. Breaking lines in the Flash Text Engine couldn’t be easier:

var content:ContentElement = new TextElement("Some example text to be broken into TextLine objects by a TextBlock instance.", new ElementFormat());
var tb:TextBlock = new TextBlock(content);
var line:TextLine = tb.createTextLine(null, 200);
var y:Number = 0;
while(line != null)
{
    addChild(line);
    y += line.ascent;
    line.y = y;
    y += line.descent;
    line = tb.createTextLine(line, 200);
}



Tricks

But what happens if we modify the breakOpportunity of the ElementFormat?

var ef:ElementFormat = new ElementFormat();
ef.breakOpportunity = BreakOpportunity.ALL;
var content:ContentElement = new TextElement("Some example text to be broken into TextLine objects by a TextBlock instance.", ef);
var tb:TextBlock = new TextBlock(content);
var line:TextLine = tb.createTextLine(null, 200);
var y:Number = 0;
while(line != null)
{
    addChild(line);
    y += line.ascent;
    line.y = y;
    y += line.descent;
    line = tb.createTextLine(line, 200);
}






As you can see, when the ElementFormat for a TextElement has its breakOpportunity set to BreakOpportunity.ALL, the TextBlock breaks a new TextLine instance after each character. Crazy right?

When I figured this out about 9 months ago, my next thought was to test how GroupElement responds to BreakOpportunity:

var ef:ElementFormat = new ElementFormat();
ef.breakOpportunity = BreakOpportunity.ALL;
 
var group:GroupElement = new GroupElement(
    new <ContentElement>[
    new TextElement("Some example text ", new ElementFormat()),
    new TextElement("to be broken into ", new ElementFormat()),
    new TextElement("TextLine objects by ", new ElementFormat()),
    new TextElement("a TextBlock instance.", new ElementFormat()),
    ], ef);
 
var tb:TextBlock = new TextBlock(group);
var line:TextLine = tb.createTextLine(null, 200);
var y:Number = 0;
while(line != null)
{
    addChild(line);
    y += line.ascent;
    line.y = y;
    y += line.descent;
    line = tb.createTextLine(line, 200);
}




Sweet. So it does what the documentation says it’ll do, break between adjacent TextElements. But is it only TextElements? What about adjacent GraphicElements?

var ef:ElementFormat = new ElementFormat();
ef.breakOpportunity = BreakOpportunity.ALL;
 
var group:GroupElement = new GroupElement(
    new <ContentElement>[
        new TextElement("Some example text ", new ElementFormat()),
        new GraphicElement(new GraphicRect(), 20, 20, new ElementFormat()),
        new TextElement("with GraphicElements ", new ElementFormat()),
        new GraphicElement(new GraphicRect(), 20, 20, new ElementFormat()),
        new TextElement("to be broken into ", new ElementFormat()),
        new TextElement("TextLine objects by ", new ElementFormat()),
        new TextElement("a TextBlock instance.", new ElementFormat()),
    ], ef);
 
var tb:TextBlock = new TextBlock(group);
var line:TextLine = tb.createTextLine(null, 200);
var y:Number = 0;
while(line != null)
{
    addChild(line);
    y += line.totalHeight;
    line.y = y;
    line = tb.createTextLine(line, 200);
}




Ah ha! So it doesn’t only work for TextElements, it works for any siblings enclosed in a GroupElement. Good to know. Can you imagine the implications of this? (hint, this is important for rendering floats using the FTE!)

Tags: , , ,

This entry was posted on Thursday, June 2nd, 2011 at 11:48 pm and is filed under actionscript. You can follow any responses to this entry through the RSS 2.0 feed. You can leave a response, or trackback from your own site.

One Response to “FTE Layout Tricks with BreakOpportunity.ALL”
  1. Joshua Sullivan says:
    September 25, 2011 at 6:15 pm

    I wish I had known about this weeks ago! No I need to go back and redo some code. Thank you so much!

    Reply
Leave a Reply: