Text

From Frontal Wiki

Jump to: navigation, search

Contents

Introduction to the text tag

The "text" tag is used to add text to a Frontal document. Its basic form is: 

<text>Hello, world.</text>

though if Frontal encounters unprocessed text in the Frontal definition it will automatically wrap it with a text tag. For example these are equivalent: 

<div>Hello, world.</div>

and 

<div><text>Hello, world.</text></div>

You must account for this transformation when defining selectors in a style sheet; the selectors should be written to match the latter form.

Behind the scenes, the text tag uses the Flash TextField class for its implementation and so an understanding of that class's capabilities and limitations in important in using the text tag efficiently. For example, when adding a title and text to a Frontal document, one approach might be to do the following: 

<text style="font-size: 24px;">Welcome to Frontal</text>
<text>Here is some text.</text>

While this will work, it's more efficient to use the Flash TextField's formatting capabilities to achieve the same effect: 

<text><![CDATA[<font size="24">Welcome to Frontal</font><br />
Here is some text.]]></text>

The reason that it's more efficient is because it uses a single TextField instance rather than two. Also, by putting the texts together allows them to be scrolled together as well as copy and pasted together. Futhermore, the easiest way to flow text around an image in Frontal is to use the Flash TextField's abilities to do that as well: 

<text style="condense-white: true; width: 350px;">
<![CDATA[<img src="http://frontalcode.com/frontal_logo.gif" />
Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
]]>
</text>

The Flash TextField has a number of formatting options available to it and these are described in the Flash documentation for the TextField's htmlText property. Note that when using these formatting tags, you must include them in a CDATA tag as in the examples above. This is to prevent Frontal from trying to parse these tags as its own and instead to allow them to be passed to the TextField instance.

Implementation

The text tag is a visual element implemented by the ContainerText class which extends the Container class - the class that implements the "div" tag. But unlike, say, the "img" tag which also extends the "div" tag, the text tag may not contain other Frontal elements. This is because it uses all of its children elements to populate the TextField instance assocaited with it.

Properties

On top of the Container properties, ContainerText add these properties:

  • textField: The instance of the Flash TextField class associated with the text tag.
  • scrollTop: While not particular to the text tag, this property is linked with the Flash TextField's scrollV property. That is, setting this property also sets scrollV on the textField property.
  • scrollLeft: While not particular to the text tag, this property is linked with the Flash TextField's scrollH property. That is, setting this property also sets scrollH on the textField property.
  • text: Use this property to get and set the text of the text tag.
  • value: This is a synonym for the text property and comes into play when a text tag is used as a form input. For more details, see the "form" tag.

Styles

These styles are particular to the text tag:

  • text-transform: One of "uppercase," "lowercase," "capitalize" or "none." This style will transform the text when preparing it for display. In the case of a dynamic text field, it will not affect the return value of the text property. In the case of an input field, though, it will.
  • html-text: Set to true to have Flash interpret the TextField contents as HTML. Set to false to have it interpret the contents as plain text.
  • cache-as-bitmap: While not unique to the text tag, unless this style is explicitly set to false, it will be turned on. This is because a TextField represents complex vector data and caching it as a bitmap can generally improve the performance of its display.
  • flash-text-type: One of either "dynamic" or "input." The default value is "dynamic." This maps to the TextField.type property.
  • font-family: This is the name of the font to use for the text. It should be the name of the font exactly as it appears in the Flash IDE when creating a text field. For more details see Embedding Fonts below.
  • flash-text-always-show-selection: This maps to the TextField.alwaysShowSelection property. The default is false.
  • flash-text-anti-alias-type: One of "normal" or "advanced," this maps to the TextField.antiAliasType property. The default is "normal."
  • condense-white: This maps to the TextField.condenseWhite property. The default is false.
  • display-as-password: This maps to the TextField.displayAsPassword property. The default is false.
  • flash-text-grid-fit-type: "none," "pixel" or "subpixel." This maps to the TextField.gridFitType property. The default is "pixel."
  • max-chars: This maps to the TextField.maxChars property. The default is 0.
  • mouse-wheel-enabled: This maps to the TextField.mouseWheelEnabled property. The default is true.
  • multiline: This maps to the TextField.multiline property. The default is true.
  • flash-text-restrict: This maps to the TextField.restrict.
  • selectable: This maps to the TextField.selectable property. The default is true.
  • sharpness: This maps to the TextField.sharpness property. The default is 0.
  • thickness: This maps to the TextField.thickness property. The default is 0.
  • flash-text-use-rich-text-clipboard: This maps to the TextField.useRichTextClipboard property. The default is false.
  • word-wrap: This maps to the TextField.wordWrap property. The default is true.
  • text-align: One of "center," "justify," "left" or "right." This maps to the TextField.align property. The default is "left."
  • color: This maps to the TextField.textColor property. The default is black.
  • block-indent: This maps to the TextField.blockIndent property.
  • bold: This maps to the TextField.bold property. The default is false.
  • flash-text-bullet: This maps to the TextField.bullet property. The default is false.
  • indent: This maps to the TextField.indent property.
  • italic: This maps to the TextField.italic property. The default is false.
  • kerning: This maps to the TextField.kerning property.
  • leading: This maps to the TextField.leading property.
  • flash-text-left-margin: This maps to the TextField.leftMargin property.
  • letter-spacing: This maps to the TextField.letterSpacing property.
  • flash-text-right-margin: This maps to the TextField.rightMargin property.
  • block-indent: This maps to the TextField.blockIndent property.
  • font-size: This maps to the TextField.size property.
  • flash-text-tab-stops: This maps to the TextField.tabStops property.
  • flash-text-target: This maps to the TextField.target property.
  • underline: This maps to the TextField.underline property. The default is false.
  • flash-text-url: This maps to the TextField.url property.
  • link-color: This uses the Flash StyleSheet class to set the color of links (text within anchor "<a />" tags) in an HTML text tag.
  • link-decoraton: One of "none" or "underline," this uses the Flash StyleSheet class to set the decoration of links (text within anchor "<a />" tags) in an HTML text tag.
  • hover-color: This uses the Flash StyleSheet class to set the color of links (text within anchor "<a />" tags) in an HTML text tag when the mouse is over them.
  • hover-decoration: One of "none" or "underline," this uses the Flash StyleSheet class to set the decoration of links (text within anchor "<a />" tags) in an HTML text tag when the mouse is over them.


How the text Tag is Sized

If explicit values are not set for a text tag's width and height then we need to determine practical values for them.

If no "width" style is set or if it is set to "auto," then we temporarily set the width of the Flash TextField instance to an evaluation of "100% leftover." This sets the width of the TextField such that it will fill its parent element minus things like borders and padding. Later, we will see if we can shrink the TextField.

If no "height" style is set then we note this fact as we will use the height of the rendered TextField as the height of the text tag.

Next, we set the text of the TextField. If we had automatically set the width of the TextField then now we see if we can shrink it. That is, if the rendered text is not as wide as the TextField then we make the TextField.width property just wide enough to encompass the text. (Just wide enough is 6 pixels more than the return of the TextField.textWidth property. Any narrower and Flash will occasionally re-layout the text after setting the TextField.width property thus making our calculations inaccurate.)

And if no "height" style had been set, we now set the TextField.height to be just tall enough to encompass the text. (Just all enough is 4 pixels more than the return of the TextField.textHeight property to include the 2 pixel gutter that Flash automatically adds to all TextFields.)

These rules then explain how the backgrounds of the two text tags in the following example are limited by the amount of text in the tags. 

<div style="width: 300px; color: white;">
    <text style="background-color: blue;">Short text.</text>
    <text style="background-color: green;">Long text. Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.</text>
</div>


The 2-Pixel Text Gutters

It is worth noting in its own section that Flash always applies a two pixel gutter around the text in a TextField. So if you are trying to achieve a pixel-perfect design, you will need to position your text tag 2 pixels left and above where you would like the top left corner of your rendered text to be.


Scrolling a text Tag

Text may be scrolled in one of two ways: either as content in a scrollable div or as a scrollable element itself. In the former case, it's as if you were scrolling a graphic - the scrolling will be very smooth but it will not respect the text's formatting. That is, after a scroll, the top line may be cut off.

In the latter case, the text will scroll by lines and so the top line will always be fully visible. But the scrolling will not be smooth.

In the following example, we show the two ways to scroll text. 

<div style="width: 200px; height: 150px; scroll: auto; float: left; margin-right: 20px; overflow: hidden;">
    <text style="background-color: green; color: white; font-size: 18px;"><![CDATA[<font size="24">Big Text Header</font><br />Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.]]></text>
</div>
<text style="background-color: blue; color: white; width: 200px; height: 150px; scroll: auto; float: left; font-size: 18px;"><![CDATA[<font size="24">Big Text Header</font><br />Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.]]></text>

Note that in the left block, dragging the scrollbar slider smoothly slides the text. In the right, it jumps line by line even when the line heights are varying. Also note how in the right block, dragging a selection causes the text to scroll whereas it does not in the left.

In general, the approach of applying a scrollbar directly to a text tag is a bit more functional than treating it like a graphic.


System and Embedded Fonts

When you use the font-family style, Frontal checks the list of registered fonts (via the Flash API Font.enumerateFonts) to see if the font is available either as an embedded font or a system font. If available as an embedded font then that is used. Otherwise if it is available as a system font then that is used. And if it is available as neither then the system default font is used. In the latter two cases, if the embedded font is later loaded via an external resource then the text tag will automatically be re-rendered using the embedded font.

Note that if only a system font is available for a font family then there will be significant limitations in the presentation of the font including no anti-aliasing, alpha or rotation support.

Flash supports embedding fonts in a few different ways. The first is to embed a font using a dynamic text field directly in the SWF that contains the Frontal renderer. This is the most straightforward way to do things though it does require you build your own Frontal Renderer. You may to download the source code to build your own Frontal Renderer here.

Instructions for building your own Frontal Renderer can be found at the following location: http://code.google.com/p/frontal/wiki/Building_the_Frontal_Renderer

To do this, add a text field to the stage or to a movie in the library that it exported for ActionScript. Choose the font you wish to embed and then choose "Embed..." in the properties pane for the text field. Then choose the characters you wish to embed. After doing this, you will be able to use this font by setting the "font-family" style to the exact name of the font as shown for the text field in the Flash IDE.

The other way to embed a font is as a font class in a SWF's library. To do this, create a FLA and then go to the library pane. In that pane, choose "New font..." and choose the font you would like to embed and which face, i.e., normal, bold, bold-italic or italic. Now select the font's symbol's linkage, turn on "Export for ActionScript" and set the class name to some name, say, "MyFont." Repeat this for each face of the font that you want to embed. (To get '<b>' and '<i>' tags to work in 'text' tags then you will need to embed the font two more times - one with "bold" checked and once with "italic" checked.) Publish the FLA. Let's assume you published it to "MyFont.swf" in the same folder as the Frontal-enabled SWF.

To use this font SWF in your Frontal definition, you use the "include" tag. With this tag we can do several things and one is to pull external font classes into our list of registered fonts. Here is how we would do that in this case: 

<include rel="assets" type="application/x-shockwave-flash" src="MyFont.swf" fontClasses="MyFont" />

What this line does is load the external font SWF, look for a font class named MyFont in that SWF and then register that font in the Frontal-enabled SWFs font registry. (This is all done using the Flash Font class and its methods.) Now we can add a text tag that uses the font we embedded. Regardless of the name we chose for the font class, we must use the actual name of the font that was embedded this way. Let's say we had embedded Avenir. 

<include rel="assets" type="application/x-shockwave-flash" src="MyFont.swf" fontClasses="MyFont" />
<text onClick="com.frontalcode.Debugger.msg(resolveFont('Avenir').isEmbedded);" style="font-family: Avenir;">This is Avenir.</text>

If the embedding worked correctly, first we'll see an anti-aliased version of the text in the correct font. And secondly, when we click the text we'll see "true" reported.

A problem with this approach is that we can't limit the glyphs that get embedded with the font. This can result in very heavy SWFs particularly if, say, we are embedding a Japanese font.

In Flash CS4, things get better as we can use the Flex "[Embed...]" construct. This is an alternative to doing "New font..." in the library and is done with ActionScript instead. Embedding a font would look something like this: 

[Embed(systemFont="Avenir", fontName="Avenir", mimeType="application/x-font", unicodeRange="U+0041-U+005A")]
var Avenir:Class;
Font.registerFont ( Avenir );

This approach has the advantages of only embedding the characters you wish to be embedded and also being able to set the font name to anything you like. (It is fontName in the Embed construct that you would use as the value for the font-family style in the Frontal definition.)

Remember that embedding a font SWF is like embedding any other kind of SWF and so permissions must be considered. If you are having difficulties using an embedded font from an external SWF then try using the Security.allowInsecureDomain() or Security.allowDomain() API in the font SWF (see the Flash documentation for details) as well as those calls in a script tag of the Frontal definition prior to the include tag. You may also try adding the style "load-in-current-app-and-sec-domains: true;" to the include tag.

Creating a Link with a text Tag

A common need is to create a link from a Frontal text tag. Using the frLink style class in the Frontal default style sheet it is quite straightforward. Here is an example: 

<text  class="frLink" href="http://frontalcode.com/" target="_blank">Frontal</text>

The value for the "target" attribute may be the name of a specific browser window or it may be one of the standard HTML names "_self," "_blank," "_parent" or "_top." If target is not specified, the behavior is the same as if you had specified a target of "_blank."


Running Interactions from Links in text Tags

Adding links in a Flash TextField is not special to Frontal but as Frontal's scripting feature is unique, it is perhaps worth a quick discussion about how this is done.

In Flash, a link may be added to a TextField by using the anchor tag. For example, here we use it to create a link to the Frontal website. 

<text style="condense-white: true;"><![CDATA[
<a href="http://frontalcode.com/" target="_blank">Frontal</a>
]]></text>

Now let us create a link to the text that will call an interaction in Frontal. 

<style><![CDATA[
    #linkedText
        {
            @onRender
                {
                    if ( ! dynamic.linkEventHandlerAdded )
                    {
                        function linkEventHandler ( event )
                        {
                            var randomColor = Math.floor ( 0xffffff * Math.random ( ) );
                            if ( event.text == "link1" ) sS ( "color", randomColor );                          
                            if ( event.text == "link2" ) sS ( "background-color", randomColor );
                        }
 
                        addListener ( textField, flash.events.TextEvent.LINK, linkEventHandler );
 
                        dynamic.linkEventHandlerAdded = true;
                    }
                }
        }
]]></style>
<text id="linkedText" style="condense-white: true;"><![CDATA[
<a href="event:link1">Click me.</a><br />
<a href="event:link2">No, click me!</a>
]]></text>

We again use the anchor tag but now we use the special Flash protocol "event:" in the href attribute along with a text parameter for the link. Then we use the onRender interaction as a convenient place to add an event listener to the Flash TextField instance. We're careful to do this just once (onRender may be called many times) by setting a flag once we're done.

A Flash TextField will dispatch a TextEvent.LINK event whenever a link with the "event:" protocol is clicked and so the event listener we added in the onRender interaction will be called. Because of closure, it will run in the context of the text tag and so the calls to sS (short for "setStyle") will be to the text tag. Here we randomly change the color of the text when we click the first link (identified with "link1" since the href is "event:link1") and the color of the background when we click the second link (identified with "link2").

As an aside, note that we use addListener instead of Flash's addEventListener. This is a Frontal DocumentElement method that tracks event listeners such that if the listening tag is destroyed, all of its listeners will be automatically removed. This can prevent resource leaks in your Flash movie.

Retrieved from "http://www.frontalcode.com/wiki/index.php/Text"
Personal tools
Get Adobe Flash player