Use text in a mobile application
Guidelines for text in a mobile application
Some Spark text controls have been optimized for use in mobile applications. When possible, use the following text controls:
• Spark TextArea
• Spark TextInput
• Spark Label (unless you must use an embedded font; then use the Spark TextArea or TextInput controls)
There are some special considerations when working with text controls in an iOS application. Flex engineer Jason SJ describes these on his blog.
TLF in a mobile application
In general, avoid text controls that use Text Layout Framework (TLF) in mobile applications. The mobile skins of the TextArea and TextInput controls are optimized for mobile applications and do not use TLF as their desktop counterparts do. TLF is used in desktop applications for providing a rich set of controls over text rendering.
Avoid the following text controls in a mobile application, because they use TLF and their skins are not optimized for mobile applications:
• Spark RichText
• Spark RichEditableText Skins for mobile text controls
When you create a mobile application, Flex automatically applies the mobile theme. As a result, text-based controls use the mobile skins. These skins are optimized for mobile applications, but they do not support the following features of the standard Spark skins:
• TLF
• Bi-directionality or mirroring
• Compact Font Format (CFF) fonts for embedding
• RichEditableText for text rendering (instead, mobile skins use StyleableTextField) Input with soft keyboards
When a user places the focus on a text control that takes input, mobile devices without keyboards display a soft keyboard on the screen. Developers currently do not have control over the configuration of this soft keyboard.
Use the Spark Label control in a mobile application
The Spark Label control is ideally suited to single lines of non-editable, non-selectable text.
The Label control uses FTE, which is not as performant as text controls that have been optimized for mobile applications such as TextInput and TextArea. However, the Label control does not use TLF, so it generally performs better than controls such as RichText and RichEditableText, which do implement TLF.
In general, use Spark Label controls in mobile applications sparingly. Do not use the Spark Label control in skins or item renderers.
Do not use the Label control when you embed fonts in a mobile application, because the Label control uses CFF. Use the TextArea control instead. For more information, see “Embed fonts in a mobile application” on page 136.
Use the Spark TextArea control in a mobile application
The Spark TextArea control is a text-entry control that lets users enter and edit multiple lines of text. The Spark TextArea control has been optimized for mobile applications.
In a mobile application, the TextArea control uses the spark.skins.mobile.TextAreaSkin class for its skin. This skin uses the StyleableTextField class rather than the RichEditableText class for rendering text. As a result, the TextArea control does not support TLF. It supports only a subset of styles that are available on the TextArea control with the desktop Spark skin.
Because the TextArea control does not support TLF, you cannot use the textFlow, content, or selectionHighlighting properties. In addition, you cannot use the following methods:
• getFormatOfRange()
• setFormatOfRange()
Use the Spark TextInput control in a mobile application
The Spark TextInput control is a text-entry control that lets users enter and edit a single line of text. It has been optimized for mobile applications.
In a mobile application, the TextInput control uses the spark.skins.mobile.TextInputSkin class for its skin. This skin uses the StyleableTextField class rather than the RichEditableText class for rendering text. As a result, the TextInput control does not support TLF. It supports only a subset of styles that are available on the TextInput control with the desktop Spark skin.
In some cases (such as when you want to use an embedded font), replace a Label control with a TextInput control. To make the TextInput control act more like a Label control, set the editable and selectable properties to false. You can also remove the border around a TextInput control by creating a custom skin. For more information, see “Basics of mobile skinning” on page 137.
Use the RichText and RichEditableText controls in a mobile application
Try to avoid using the RichText and RichEditableText controls in mobile applications. These controls do not have mobile skins, and they are not optimized for mobile applications. If you do use these controls, you are using TLF, which is computationally expensive.
MX text controls
You cannot use MX text controls such as MX Text and MX Label in mobile applications. Use the Spark equivalents instead.
Text styles in a mobile application
The styles supported by the StyleableTextField class determine which styles are supported by text controls in the mobile theme.
The following styles are the only styles supported by the TextInput and TextArea classes in a mobile application:
• textAlign
• fontFamily
• fontWeight
• fontStyle
• color
• fontSize
• textDecoration
• textIndent
• leading
• letterSpacing
When you use the mobile theme, the Label control supports its standard set of styles.
Text controls in skins and item renderers in a mobile application
Text controls in a mobile application use the mobile theme. In the mobile theme, skins use the StyleableTextField class to render text. This class is in the spark.components.supportClasses.* package.
For example, the mobile TextAreaSkin class defines the the textDisplay property as follows:
textDisplay = StyleableTextField(createInFontContext(StyleableTextField));
When you render text in a custom mobile skin, or create an ActionScript item renderer for use in a mobile application, use the StyleableTextField class. It is optimized for mobile applications.
The StyleableTextField class is a lightweight subclass of the Flash TextField class. It implements the IEditableText interface (which itself extends IDisplayText).
The StyleableTextField class does not implement the IUIComponent or ILayoutElement interfaces, so it cannot be used in MXML directly. It is designed for use in ActionScript skins and ActionScript item renderers.
For more information about skinning mobile components, see “Basics of mobile skinning” on page 137. For more information about ActionScript item renderers, see Create a Spark item renderer in ActionScript.
User interactions with text in a mobile application
You can use gestures such as swipe with text controls. The following example listens for a swipe event, and tells you in which direction the swipe occurred:
<?xml version="1.0" encoding="utf-8"?>
<!-- mobile_text/views/TextAreaEventsView.mxml -->
<s:View xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:s="library://ns.adobe.com/flex/spark" title="TextArea swipe event"
viewActivate="view1_viewActivateHandler(event)">
<fx:Declarations>
protected function swipeHandler(event:TransformGestureEvent):void {
// event.offsetX shows the horizontal direction of the swipe (1 is right, -1
protected function view1_viewActivateHandler(event:FlexEvent):void {
swipeText.addEventListener(TransformGestureEvent.GESTURE_SWIPE,swipeHandler);
} ]]>
</fx:Script>
<s:VGroup>
<s:TextArea id="swipeText" height="379"
editable="false" selectable="false"
Touch+drag gestures always select text, but only if the text control is selectable or editable. In some cases, you might not want to select text when the user performs a touch+drag or swipe gesture on a text control. In this case, either set the selectable and editable properties to false or reset the selection with a call to the selectRange(0,0) method in the swipe event handler.
If the text is inside a Scroller, the Scroller will only scroll if the gesture is outside the text component.
Support the screen keyboard in a mobile application
Many devices do not include a hardware keyboard. Instead, these devices use a keyboard that opens on the screen when necessary. The screen keyboard, also called a soft or virtual keyboard, closes after the user enters information, or when the user cancels the operation.
The following figure shows an application using the screen keyboard:
Because the keyboard takes up part of the screen, Flex must ensure that an application still functions in the reduced screen area. For example, the user selects a TextInput control, causing the screen keyboard to open. After the keyboard opens, Flex automatically resizes the application to the available screen area. Flex then scrolls the application so that the selected TextInput control is visible above the keyboard.
Blogger Peter Elst blogged about controlling the soft keyboard in Flex Mobile applications.
User interaction with the screen keyboard
The screen keyboard opens automatically when a text input control receives focus. The text input controls include the TextInput and TextArea controls.
You can configure other types of controls to open the keyboard, such as a Button or ButtonBar control. To open the keyboard when a control other than a text input control receives focus, set the control’s needsSoftKeyboard property to true. All Flex components inherit this property from the InteractiveObject class.
Note: The text input controls always open the keyboard when receiving focus. They ignore the needsSoftKeyboard property, and setting it has no effect on the text input controls.
The keyboard stays open until one of the following actions occurs:
• The user moves focus to a control that does not receive text input.
If focus moves to another text input control, or to a control with needsSoftKeyboard set to true, the keyboard stays open.
• The user cancels input by pressing the back button on the device.
Configure the application for the screen keyboard
To support the screen keyboard, the application can perform the following actions when the keyboard opens:
• Resize the application to the remaining available screen space so that the keyboard does not overlap the application.
• Scroll the parent container of the text input control that has focus to ensure that the control is visible.
Configure your system for the screen keyboard
The screen keyboard is not supported in applications running in full screen mode. Therefore, in your app.xml file, ensure that the <fullScreen> attribute is set to false, the default value.
Ensure that the rendering mode of the application is set to CPU mode. The rendering mode is controlled in the application’s app.xml descriptor file by the <renderMode> attribute. Ensure that the <renderMode> attribute is set to cpu, the default value, and not to gpu.
Note: The <renderMode> attribute is not included by default in the app.xml file. To change its setting, add it as an entry in the <initialWindow> attribute. If it is not included in the app.xml file, then it has the default value of cpu.
Resize the application when the screen keyboard opens
The resizeForSoftKeyboard property of the Application container determines the application resizing behavior. If true, then the application resizes itself to fit the available screen area when the keyboard opens. The application restores its size when the keyboard closes.
The example below shows the main application file for an application that supports application resizing by setting the resizeForSoftKeyboard property to true:
<?xml version="1.0" encoding="utf-8"?>
<!-- containers\mobile\SparkMobileKeyboard.mxml -->
<s:ViewNavigatorApplication xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:s="library://ns.adobe.com/flex/spark"
firstView="views.SparkMobileKeyboardHomeView"
resizeForSoftKeyboard="true">
</s:ViewNavigatorApplication>
To enable application resizing, ensure that the <softKeyboardBehavior> attribute in the application’s app.xml descriptor file is set to none. The default value of the <softKeyboardBehavior> attribute is none. This default configures AIR to move the entire Stage so that the text component with focus is visible.
Scroll the parent container when the screen keyboard opens
To support scrolling, wrap the parent container of any text input controls in a Scroller component. When a component that opens the keyboard gets focus, the Scroller automatically scrolls the component into view. The component can also be the child of multiple, nested containers of the Scroller component.
The parent container must be a GroupBase or SkinnableContainer container, or a subclass of GroupBase or SkinnableContainer. The component gaining focus must implement the IVisualElement interface, and must be focusable.
By wrapping the parent container in a Scroller component, you can scroll the container while the keyboard is open.
For example, a container holds multiple text input controls. You then scroll to each text input control to enter data.
The keyboard remains open as long as you select another text input control, or until you select a component with the needsSoftKeyboard property set to true.
When the keyboard closes, the parent container can be smaller than the available screen space. If the container is smaller than the available screen space, then the Scroller restores the scroll positions to 0, the top of the container.
The following example shows a View container with multiple TextInput controls and a Scroller component:
<?xml version="1.0" encoding="utf-8"?>
<!-- containers\mobile\views\SparkMobileKeyboardHomeView.mxml -->
<s:View xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:s="library://ns.adobe.com/flex/spark"
title="Compose Email">
<s:Scroller width="100%" top="10" bottom="50">
<s:VGroup paddingTop="3" paddingLeft="5" paddingRight="5" paddingBottom="3">
<s:TextInput prompt="To" width="100%"/>
<s:TextInput prompt="CC" width="100%"/>
<s:TextInput prompt="Subject" width="100%"/>
<s:TextArea height="400" width="100%" prompt="Compose Mail"/>
</s:VGroup>
</s:Scroller>
<s:HGroup width="100%" gap="20"
bottom="5" horizontalAlign="left">
<s:Button label="Send" height="40"/>
<s:Button label="Cancel" height="40"/>
</s:HGroup>
</s:View>
The VGroup container is the parent container of the TextInput controls. The Scroller wraps the VGroup so that each TextInput control appears above the keyboard when it receives focus.
For more information on the Scroller component, see Scrolling Spark containers.
Handle screen keyboard events
The following table describes the events associated with the keyboard:
All Flex components inherit these events from the flash.display.InteractiveObject class.
In an event handler, use the softKeyboardRect property of the flash.display.Stage class to determine the size and location of the keyboard on the screen.
Event When dispatched
softKeyboardActivating Just before the keyboard opens softKeyboardActivate Just after the keyboard opens softKeyboardDeactivate After the keyboard closes
On Android, the screen keyboard dispatches KEY_UP and KEY_DOWN events as the user interacts with it. On iOS, the KEY_UP and KEY_DOWN events are not dispatched. Instead, you can listen for the CHANGE event on the associated text control to respond to keyboard input.
Embed fonts in a mobile application
When you compile a mobile application with embedded fonts, Flex uses non-CFF fonts by default. CFF fonts use FTE.
In general, avoid using FTE in a mobile application.
Because the Label control uses FTE (and therefore CFF fonts), use the TextArea or TextInput controls when embedding fonts in a mobile application.
In your CSS, set embedAsCFF to false, as the following example shows:
<?xml version="1.0" encoding="utf-8"?>
<!-- mobile_text/Main.mxml -->
<s:ViewNavigatorApplication xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:s="library://ns.adobe.com/flex/spark"
firstView="views.EmbeddingFontsView">
<fx:Style>
@namespace s "library://ns.adobe.com/flex/spark";
@font-face {
src: url("../assets/MyriadWebPro.ttf");
fontFamily: myFontFamily;
embedAsCFF: false;
} .customStyle {
fontFamily: myFontFamily;
fontSize: 24;
} </fx:Style>
</s:ViewNavigatorApplication>
The TextArea control in the EmbeddingFontView view applies the type selector:
<?xml version="1.0" encoding="utf-8"?>
<!-- mobile_text/EmbeddingFontsView.mxml -->
<s:View xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:s="library://ns.adobe.com/flex/spark" title="Embedded Fonts">
<s:TextArea id="ta1"
width="100%"
styleName="customStyle"
text="This is a TextArea control that uses an embedded font."/>
</s:View>
If you use class selectors (such as s|TextArea) to apply styles (or to embed fonts), define the class selector in the main application file. You cannot define class selectors in a view of a mobile application.
For more information, see Using embedded fonts.