Using the Label component
Requirements
User level
Beginning
Required products
- Flash Professional (Download trial)
The Label component in Flash Professional displays a single line of text. It is typically used to identify some other element or activity on a web page. You can specify that a label be formatted with HTML to take advantage of its text formatting tags. You can also control the alignment and size of a label. Label components don't have borders and cannot be focused.
A live preview of each Label instance reflects the changes made to parameters in the Property inspector or the Component inspector during authoring. Since the label doesn't have a border, the only way to see a live preview is to set the text parameter.
The next sections describe the most popular and useful ways to use this feature.
Note: The following examples require that a Label component exists in your document's library.
Tip: The following examples display a light gray background behind each of the Label instances to help illustrate the dimensions of the Label component. However, by default the Label instance's background is transparent. You can enable background colors by setting the background property to true and the backgroundColor property to a color value by using the Label instance's textField property, as seen in the following snippet:
import fl.controls.Label;
var myLabel:Label = new Label();
// add background color to internal text field.
myLabel.textField.background = true;
myLabel.textField.backgroundColor = 0xDDDDDD;
addChild(myLabel);
Creating a new Label instance
To create a new instance of the Label class using ActionScript, drag a copy of the component from the Components panel into your current Flash document's library. Next, import the fl.controls.Label class using the import statement. This step is required because the component files are not implicitly imported, like the other flash.* packages. Once you import the Label class into your current document, you can create a new Label instance using the new operator. Finally, add the new Label instance to the display list using the addChild() method.
Note: To see which files are implicitly imported, see the following XML file: C:\Program Files\Adobe\Adobe Flash CS4\Common\Configuration\ActionScript 3.0\implicitImports.xml
Example
The following example creates a new Label component instance and adds it to the display list:
import fl.controls.Label;
var myLabel:Label = new Label();
myLabel.text = "Hello world";
myLabel.move(10, 10);
addChild(myLabel);
Result
Download the source files for this example:
Changing the Label instance's text
To change the text of a Label instance, set either the text or htmlText properties. Similar to working with text fields, setting the text property sets the plain-text , and setting the htmlText property sets the HTML formatted text displayed by the Label. For more information on HTML formatted labels, see Creating an HTML-enabled Label instance.
Note: If you are displaying large amounts of text using a Label instance, you'll need to either set the width and height properties manually to accommodate the text, or use the autoSize and wordWrap properties to have the label auto-size to match the displayed text. For more information on automatically resizing labels, see Automatically resizing a Label instance and Creating a multi-line Label instance.
Example
The following example creates a Label instance with a large amount of text, and sets the width property to 240 pixels:
import fl.controls.Label;
var myLabel:Label = new Label();
myLabel.text = "The quick brown fox jumped over the lazy dog";
myLabel.width = 240;
myLabel.move(10, 10);
addChild(myLabel);
Result
Download the source files for this example:
Automatically resizing a Label instance
If you do not know the width or length of the text, set the label instance's autoSize property to one of the constants in the TextFieldAutoSize class. By setting the autoSize property, the label is resized automatically to match the contents.
Note: Whenever a Label instance is resized, the resize event (represented by the fl.events.ComponentEvent.RESIZE constant) is dispatched.
The following are valid values for the autoSize property:
TextFieldAutoSize.NONE(default): The label is not resized or aligned to fit the text.TextFieldAutoSize.LEFT: The right and bottom sides of the label are resized to fit the text. The left and top sides are not resized.TextFieldAutoSize.CENTER: The left and right sides of the label resize to fit the text. The horizontal center of the label stays anchored at its original horizontal center position.TextFieldAutoSize.RIGHT: The left and bottom sides of the label are resized to fit the text. The top and right sides are not resized.
Example
The following example resizes a Label instance automatically by setting the autoSize property to TextFieldAutoSize.LEFT:
import fl.controls.Label;
var myLabel:Label = new Label();
myLabel.text = "The quick brown fox jumped over the lazy dog";
myLabel.autoSize = TextFieldAutoSize.LEFT;
myLabel.move(10, 10);
addChild(myLabel);
Result
Download the source files for this example:
Example
The following example resizes a Label instance automatically by setting the autoSize property and listens for the resize event to be dispatched:
// Import the required component classes.
import fl.controls.Label;
import fl.events.ComponentEvent;
/* Create a new Label component instance, set the text and autoSize properties,
and add the label to the display list. */
var myLabel:Label = new Label();
myLabel.text = "The quick brown fox jumped over the lazy dog";
myLabel.autoSize = TextFieldAutoSize.LEFT;
myLabel.move(10, 10);
myLabel.addEventListener(ComponentEvent.RESIZE, resizeHandler);
addChild(myLabel);
/* Create a new Label component instance, set the autoSize property, and add the
label to the display list. This label is used to display the width and height
of the myLabel instance. */
var debugLabel:Label = new Label();
debugLabel.text = "";
debugLabel.autoSize = TextFieldAutoSize.LEFT;
debugLabel.move(10, 30);
addChild(debugLabel);
/* Handler function for the myLabel instance. This function gets called when the
myLabel instance is resized, and sets the text in the debugLabel instance
with the width and height of the myLabel instance. */
function resizeHandler(event:ComponentEvent):void {
var lbl:Label = event.currentTarget as Label;
debugLabel.text = "[" + event.type + "] width:" + myLabel.width + ", height:" + myLabel.height;
}
Result
Download the source files for this example:
Creating a multi-line Label instance
If you need to display longer amounts of text but don't want to use a TextArea or TextField, set the label instance's wordWrap property to true to enable multi-line text labels.
Example
The following example creates a new multi-line label instance by setting the wordWrap property to true. This example sets the height of the Label instance manually. The previous examples automatically resize the label instance by setting the autoSize property:
// Import the required component classes.
import fl.controls.Label;
/* Create a new Label component instance, set the wordWrap and height properties,
and add the label to the display list. */
var myLabel:Label = new Label();
myLabel.text = "The quick brown fox jumped over the lazy dog";
myLabel.wordWrap = true;
myLabel.height = 60;
myLabel.move(10, 10);
addChild(myLabel);
Note: Even with the wordWrap property set to true you must either set the height property or set the label instance's autoSize property to resize the label vertically; otherwise, the text may be cropped off.
Result
Download the source files for this example:
Example
The following example creates a multi-line label instance and sets the autoSize property, which causes the instance to automatically resize vertically:
// Import the required component classes.
import fl.controls.Label;
/* Create a new Label component instance, set the wordWrap and autoSize properties,
and add the label to the display list. */
var myLabel:Label = new Label();
myLabel.text = "The quick brown fox jumped over the lazy dog";
myLabel.wordWrap = true;
myLabel.autoSize = TextFieldAutoSize.LEFT;
myLabel.move(10, 10);
addChild(myLabel);
Result
Download the source files for this example:
Example
The following example creates a multi-line Label instance, sets the width property to 150 and sets the autoSize property, which causes the instance to automatically resize vertically:
// Import the required component classes.
import fl.controls.Label;
/* Create a new Label component instance, set the wordWrap, autoSize,
and width properties, and add the label to the display list. */
var myLabel:Label = new Label();
myLabel.text = "The quick brown fox jumped over the lazy dog";
myLabel.wordWrap = true;
myLabel.autoSize = TextFieldAutoSize.LEFT;
myLabel.width = 150;
myLabel.move(10, 10);
addChild(myLabel);
Note: By setting the width property in the previous example, the label wraps at 150 pixels instead of the default label width of 100 pixels.
Result
Download the source files for this example:
Creating a selectable Label instance
By default, the text in a Label component instance isn't selectable by the user. If you want to allow a user to select the text in a label, set the label's selectable property to true.
Example
The following example creates a selectable Label instance by setting the selectable property to true:
// Import the required component classes.
import fl.controls.Label;
/* Create a new Label component instance, set the selectable property, and add
the label to the display list. */
var myLabel:Label = new Label();
myLabel.text = "The quick brown fox jumped over the lazy dog";
myLabel.wordWrap = true;
myLabel.autoSize = TextFieldAutoSize.LEFT;
myLabel.width = 150;
myLabel.selectable = true;
myLabel.move(10, 10);
addChild(myLabel);
Result
Download the source files for this example:
Example
The following example creates two Label component instances. Both instances have their selectable and alwaysShowSelection properties set to true, which allows the instance to display the currently selected text even if the label doesn't currently have focus:
// Import the required component classes.
import fl.controls.Label;
/* Create a new Label component instance, set the selectable and textField.alwaysShowSelection
properties, call the setSelection() method on the textField property, and add the label to
the display list. */
var myLabel:Label = new Label();
myLabel.text = "The quick brown fox jumped over the lazy dog";
myLabel.wordWrap = true;
myLabel.autoSize = TextFieldAutoSize.LEFT;
myLabel.width = 150;
myLabel.selectable = true;
myLabel.textField.alwaysShowSelection = true;
myLabel.textField.setSelection(16, 19);
myLabel.move(10, 10);
addChild(myLabel);
/* Create a new Label component instance, set the selectable and textField.alwaysShowSelection
properties, call the setSelection() method on the textField property, and add the label to
the display list. */
var secondLabel:Label = new Label();
secondLabel.text = "The quick brown fox jumped over the lazy dog";
secondLabel.wordWrap = true;
secondLabel.autoSize = TextFieldAutoSize.LEFT;
secondLabel.width = 150;
secondLabel.selectable = true;
secondLabel.textField.alwaysShowSelection = true;
secondLabel.textField.setSelection(41, 44);
secondLabel.move(170, 10);
addChild(secondLabel);
Note: The alwaysShowSelection property can't be set directly on the Label instance. In order to set this property you must set it on the Label instance's textField property, which contains a reference to the Label instance's internal text field.
Result
Download the source files for this example:
Creating an HTML-enabled label instance
When using the Label component, you aren't limited to plain-text formatting. By setting the label instance's htmlText property, you can apply rich, HTML formatting such as bold, italic, underlined or linked text.
Example
The following example displays an HTML formatted string in a Label component instance:
// Import the required component classes.
import fl.controls.Label;
/* Create a new Label component instance, set the htmlText property, and add the
label to the display list. */
var myLabel:Label = new Label();
myLabel.htmlText = "The <b>quick brown fox jumped</b> over the <i>lazy dog</i>";
myLabel.wordWrap = true;
myLabel.autoSize = TextFieldAutoSize.LEFT;
myLabel.width = 150;
myLabel.move(10, 10);
addChild(myLabel);
Result
Result
Download the source files for this example:
Using embedded fonts
Working with embedded fonts in a Label component instance is very similar to working with a TextField instance. The main difference is that instead of using the embedFonts or defaultTextFormat properties of the TextField class, set the embedFonts or textFormat styles. In order to set the Label instance's anti-alias type, set the antiAliasType property on the Label instance's textField property, which contains a reference to the label's internal text field.
For more information on embedding fonts, see the Embedding Fonts quick start.
Example
The following example demonstrates how to use embedded fonts and advanced anti-aliasing with a Label instance:
// Import the required component classes.
import fl.controls.Label;
// Create a new instance of the Font1 symbol from the document's library.
var myFont:Font = new MyFont();
// Create a new TextFormat object, and set the font and size properties.
var myTextFormat:TextFormat = new TextFormat();
myTextFormat.font = myFont.fontName;
myTextFormat.size = 8;
/* Create a new Label component instance, set the textField.antiAliasType property,
set the embedFonts and textFormat styles, and add the label to the display list. */
var myLabel:Label = new Label();
myLabel.text = "The quick brown fox jumped over the lazy dog";
myLabel.autoSize = TextFieldAutoSize.LEFT;
myLabel.move(10, 10);
myLabel.textField.antiAliasType = AntiAliasType.ADVANCED;
myLabel.setStyle("embedFonts", true);
myLabel.setStyle("textFormat", myTextFormat);
addChild(myLabel);
Note: The previous example requires a font in your Flash document's library with a linkage class of "MyFont".
Result
Download the source files for this example:
Loading an external text file into a label instance
When building dynamic sites or applications, you may want to load text from an external file instead of hard-coding the text directly into the Flash document. One advantage of dynamically loading content is that you can update the welcome message on your homepage without opening an FLA file, republishing the SWF file or uploading a new SWF file to the server. Instead, you edit the text/HTML document on the server and the updated content is used next time the SWF file is loaded.
Example
The following example displays the contents of a remote text file in a Label component instance:
// Import the required component classes.
import fl.controls.Label;
/* Create a new Label component instance, set the wordWrap and autoSize properties,
and add the label to the display list. */
var myLabel:Label = new Label();
myLabel.text = "loading...";
myLabel.width = 530;
myLabel.wordWrap = true;
myLabel.autoSize = TextFieldAutoSize.LEFT;
myLabel.move(10, 10);
addChild(myLabel);
// Create a new UILoader instance, add an event listener, and load the remote text file.
var myURLLoader:URLLoader = new URLLoader();
myURLLoader.addEventListener(Event.COMPLETE, completeHandler);
myURLLoader.load(new URLRequest("http://www.helpexamples.com/flash/lorem.txt"));
/* Handler function for the URLLoader object. This function sets the text in the label
instance to the contents of the remote text file. */
function completeHandler(event:Event):void {
var txt:String = URLLoader(event.currentTarget).data as String;
myLabel.text = txt;
}
Result
Download the source files for this example:
For more information
For more information about this topic, see the Label class in ActionScript 3.0 Reference for the Adobe Flash Platform and Using the Label component in Using ActionScript 3.0 Components.
Related Flash Quick Starts
- Using the Button component
- Getting started with Flash CS4 user interface components
- Creating, populating, and resizing the DataGrid component
- Customizing and sorting the DataGrid component
- Filtering and formatting data in the DataGrid component
- Displaying images with the TileList component
More Like This
- Display list programming in ActionScript 3
- Using ActionScript 3 drawing commands
- Programming with the Vector class
- Creating, populating, and resizing the DataGrid component
- Customizing and sorting the DataGrid component
- Filtering and formatting data in the DataGrid component
- Getting started with the ActionScript 3 FLVPlayback component
- Getting started with Flash CS4 user interface components
- Loading images and Library assets with ActionScript 3
- Displaying images with the TileList component
