RichTextEditor control
The RichTextEditor control lets users enter, edit, and format text. Users apply text formatting and URL links by using subcontrols that are located at the bottom of the RichTextEditor control.
For complete reference information, see the Adobe Flex Language Reference.
About the RichTextEditor control
The RichTextEditor control consists of a Panel control with two direct children:
- A TextArea control in which users can enter text
- A tool bar container with format controls that let a user specify the text characteristics. Users can use the tool bar subcontrols to apply the following text characteristics:
- Font family
- Font size
Note: When using the RichTextEditor control, you specify the actual pixel value for the font size. This size is not equivalent to the relative font sizes specified in HTML by using the size attribute of the HTML <font> tag.
- Any combination of bold, italic and underline font styles
- Text color
- Text alignment: left, center, right, or justified
- Bullets
- URL links
The following image shows a RichTextEditor control with some formatted text:
For the source for this example, see Creating a RichTextEditor control.
You use the RichTextEditor interactively as follows:
- Text that you type is formatted as specified by the control settings.
- To apply new formatting to existing text, select the text and set the controls to the required format.
- To create a link, select a range of text, enter the link target in the text box on the right, and press Enter. You can only specify the URL; the link always opens in a _blank target. Also, creating the link does not change the appearance of the link text; you must separately apply any color and underlining.
- You can cut, copy, and paste rich text within and between Flash HTML text fields, including the RichTextEditor control's TextArea subcontrol, by using the normal keyboard commands. You can copy and paste plain text between the TextArea and any other text application, such as your browser or a text editor.
Creating a RichTextEditor control
You define a RichTextEditor control in MXML by using the <mx:RichTextEditor> tag, as the following example shows. Specify an id value if you intend to refer to a control elsewhere in your MXML, either in another tag or in an ActionScript block.
<?xml version="1.0"?> <!-- textcontrols/RichTextEditorControl.mxml --> <mx:Application xmlns:mx="http://www.adobe.com/2006/mxml"> <mx:RichTextEditor id="myRTE" text="Congratulations, winner!" /> </mx:Application>The executing SWF file for the previous example is shown below:
You can use the text property to specify an unformatted text string, or the htmlText property to specify an HTML-formatted string. For more information on using these properties, see Using the text property, and Using the htmlText property. For information on selecting, replacing, and formatting text that is in the control, see Selecting and modifying text.
The following example shows the code used to create the image in About the RichTextEditor control:
<?xml version="1.0"?>
<!-- textcontrols/RichTextEditorControlWithFormattedText.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml">
<!-- The HTML text string used to populate the RichTextEditor control's
TextArea subcontrol. The text is on a single line. -->
<mx:Script><![CDATA[
[Bindable]
public var htmlData:String="<textformat leading='2'><p align='center'><b><font size='20'>HTML Formatted Text</font></b></p></textformat><br><textformat leading='2'><p align='left'><font face='_sans' size='12' color='#000000'>This paragraph contains<b>bold</b>, <i>italic</i>, <u>underlined</u>, and <b><i><u>bold italic underlined </u></i></b>text.</font></p></textformat><br><p><u><font face='arial' size='14' color='#ff0000'>This a red underlined 14-point arial font with no alignment set.</font></u></p><p align='right'><font face='verdana' size='12' color='#006666'><b>This a teal bold 12-pt.' Verdana font with alignment set to right.</b></font></p><br><li>This is bulleted text.</li><li><font face='arial' size='12' color='#0000ff'><u> <a href='http://www.adobe.com'>This is a bulleted link with underline and blue color set.</a></u></font></li>";
]]></mx:Script>
<!-- The RichTextEditor control. To reference a subcontrol prefix its ID with the RichTextEditor control ID. -->
<mx:RichTextEditor id="rte1"
backgroundColor="#ccffcc"
width="500"
headerColors="[#88bb88, #bbeebb]"
footerColors="[#bbeebb, #88bb88]"
title="Rich Text Editor"
htmlText="{htmlData}"
initialize="rte1.textArea.setStyle('backgroundColor', '0xeeffee')"
/>
</mx:Application>
The executing SWF file for the previous example is shown below:
Sizing the RichTextEditor control
The control does not resize in response to the size of the text in the TextArea control. If the text exceeds the viewable space, by default, the TextArea control adds scroll bars. If you specify a value for either the height or width property but not both, the control uses the default value for the property that you do not set.
If you set a width value that results in a width less than 605 pixels wide, the RichTextEditor control stacks the subcontrols in rows.
Programming RichTextEditor subcontrols
Your application can control the settings of any of the RichTextEditor subcontrols, such as the TextArea, the ColorPicker, or any of the ComboBox or Button controls that control text formatting. To refer to a RichTextEditor subcontrol, prefix the requested control's ID with the RichTextEditor control ID. For example, to refer to the ColorPicker control in a RichTextEditor control that has the ID rte1, use rte1.colorPicker.
Inheritable styles that you apply directly to a RichTextEditor control affect the underlying Panel control and the subcontrols. Properties that you apply directly to a RichTextEditor control affect the underlying Panel control only.
For more information, see the RichTextEditor in the Adobe Flex Language Reference.
Setting RichTextEditor subcontrol properties and styles
The following simple code example shows how you can set and change the properties and styles of the RichTextEditor control and its subcontrols. This example uses styles that the RichTextEditor control inherits from the Panel class to set the colors of the Panel control header and the tool bar container, and sets the TextArea control's background color in the RichTextEditor control's creationComplete event member. When users click the buttons, their click event listeners change the TextArea control's background color and the selected color of the ColorPicker control.
<?xml version="1.0"?>
<!-- textcontrols/RTESubcontrol.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml"
height="420">
<!-- The RichTextEditor control. To set the a subcontrol's style or property, fully qualify the control ID. The footerColors style sets the ControlBar colors. -->
<mx:RichTextEditor id="rte1"
backgroundColor="#ccffcc"
headerColors="[#88bb88, #bbeebb]"
footerColors="[#bbeebb, #88bb88]"
title="Rich Text Editor"
creationComplete="rte1.textArea.setStyle('backgroundColor','0xeeffee')"
text="Simple sample text"
/>
<!-- Button to set a white TextArea background. -->
<mx:Button
label="Change appearance"
click="rte1.textArea.setStyle('backgroundColor', '0xffffff');rte1.colorPicker.selectedIndex=27;"
/>
<!-- Button to reset the display to its original appearance. -->
<mx:Button
label="Reset Appearance"
click="rte1.textArea.setStyle('backgroundColor', '0xeeffee');rte1.colorPicker.selectedIndex=0;"
/>
</mx:Application>
The executing SWF file for the previous example is shown below:
Removing and adding RichTextEditor subcontrols
You can remove any of the standard RichTextEditor subcontrols, such as the alignment buttons. You can also add your own subcontrols, such as a button that pops up a find-and-replace dialog box.
- Create a function that calls the removeChildAt method of the editor's tool bar Container subcontrol, specifying the control to remove.
- Call the method in the RichTextEditor control's initialize event listener.
The following example removes the alignment buttons from a RichTextEditor control, and shows the default appearance of a second RichTextEditor control:
<?xml version="1.0"?>
<!-- textcontrols/RTERemoveAlignButtons.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml">
<mx:Script><![CDATA[
public function removeAlignButtons():void {
rt1.toolbar.removeChild(rt1.alignButtons);
}
]]></mx:Script>
<mx:HBox>
<mx:RichTextEditor id="rt1"
title="RichTextEditor With No Align Buttons"
creationComplete="removeAlignButtons()"
/>
<mx:RichTextEditor id="rt2"
title="Default RichTextEditor"
/>
</mx:HBox>
</mx:Application>
The executing SWF file for the previous example is shown below:
- Create an ActionScript function that defines the subcontrol. Also create any necessary methods to support the control's function.
- Call the method in the RichTextEditor control's initialize event listener, as in the following tag:
<mx:RichTextEditor id="rt" initialize="addMyControl()"
The following example adds a find-and-replace dialog box to a RichTextEditor control. It consists of two files: the application, and a custom TitleWindow control that defines the find-and-replace dialog (which also performs the find-and-replace operation on the text). The application includes a function that adds a button to pop up the TitleWindow, as follows:
<?xml version="1.0"?>
<!-- textcontrols/CustomRTE.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml">
<mx:Script>
<![CDATA[
import mx.controls.*;
import mx.containers.*;
import flash.events.*;
import mx.managers.PopUpManager;
import mx.core.IFlexDisplayObject;
/* The variable for the pop-up dialog box. */
public var w:IFlexDisplayObject;
/* Add the Find/Replace button to the Rich Text Editor control's
tool bar container. */
public function addFindReplaceButton():void {
var but:Button = new Button();
but.label = "Find/Replace";
but.addEventListener("click",findReplaceDialog);
rt.toolbar.addChild(but);
}
/* The event listener for the Find/Replace button's click event
creates a pop-up with a MyTitleWindow custom control. */
public function findReplaceDialog(event:Event):void {
var w:MyTitleWindow = MyTitleWindow(
PopUpManager.createPopUp(this, MyTitleWindow, true)
);
w.height=200;
w.width=340;
/* Pass the a reference to the textArea subcontrol
so that the custom control can replace the text. */
w.RTETextArea = rt.textArea;
PopUpManager.centerPopUp(w);
}
]]>
</mx:Script>
<mx:RichTextEditor id="rt" width="95%"
title="RichTextEditor"
text="This is a short sentence."
initialize="addFindReplaceButton();"
/>
</mx:Application>
The executing SWF file for the previous example is shown below:
The following MyTitleWindow.mxml file defines the custom myTitleWindow control that contains the find-and-replace interface and logic:
<?xml version="1.0"?>
<!-- A TitleWindow that displays the X close button. Clicking the close button
only generates a CloseEvent event, so it must handle the event to close the control. -->
<mx:TitleWindow xmlns:mx="http://www.adobe.com/2006/mxml"
title="Find/Replace"
showCloseButton="true"
close="closeDialog();"
>
<mx:Script>
<![CDATA[
import mx.controls.TextArea;
import mx.managers.PopUpManager;
/* Reference to the RichTextArea textArea subcontrol.
It is set by the application findReplaceDialog method
and used in the replaceAndClose method, below. */
public var RTETextArea:TextArea;
/* The event handler for the Replace button's click event.
Replace the text in the RichTextEditor TextArea and
close the dialog box. */
public function replaceAndClose():void{
RTETextArea.text = RTETextArea.text.replace(ti1.text, ti2.text);
PopUpManager.removePopUp(this);
}
/* The event handler for the TitleWindow close button. */
public function closeDialog():void {
PopUpManager.removePopUp(this);
}
]]>
</mx:Script>
<!-- The TitleWindow subcontrols: the find and replace inputs,
their labels, and a button to initiate the operation. -->
<mx:Label text="Find what:"/>
<mx:TextInput id="ti1"/>
<mx:Label text="Replace with:"/>
<mx:TextInput id="ti2"/>
<mx:Button label="Replace" click="replaceAndClose();"/>
</mx:TitleWindow>
