Use the soft keyboard in a mobile application

Auto-correction is a behavior of the OS that attempts to fix spelling mistakes and apply predictive typing to a user’s input. Depending on the device, the behavior can be implemented as a bubble over the text, an extension of the soft keyboard, or in some other way.

You can use auto-correction for soft keyboards in a mobile application by setting the text input control’s autoCorrect property to true. This is the default value.

<?xml version="1.0" encoding="utf-8"?>
<!-- mobile_keyboard/views/AutoCorrectionExample.mxml -->
<s:View xmlns:fx="http://ns.adobe.com/mxml/2009" 
        xmlns:s="library://ns.adobe.com/flex/spark" title="Auto-Correction">
    <fx:Declarations>
        <!-- Place non-visual elements (e.g., services, value objects) here -->
    </fx:Declarations>
    
    <s:layout>
        <s:VerticalLayout/> 
    </s:layout>
    
    <s:TextInput prompt="Enter your text" autoCorrect="{myCB.selected}"/> 
    <s:CheckBox id="myCB" label="Enable auto-correct" enabled="true"/>
    
</s:View>

Not all devices support auto-correction. If you enable or disable the autoCorrect property on a device that does not support it, the runtime ignores the value and uses the device’s default behavior.

Auto-capitalization is a setting that instructs the text input control to capitalize certain words or letters when the user enters text. For example, you can have all letters capitalized, or you can have just the first word of each sentence capitalized automatically. It is a convenience for the user to not have to worry about capitalization while entering text in a mobile application.

You use auto-capitalization in soft keyboards by setting the value of the autoCapitalize property on the text input control. The possible values are none, word, sentence, and all. The AutoCapitalize class defines the possible values. The default value is none.

<?xml version="1.0" encoding="utf-8"?>
<!-- mobile_keyboard/views/AutoCapitalizeExample.mxml -->
<s:View xmlns:fx="http://ns.adobe.com/mxml/2009" 
        xmlns:s="library://ns.adobe.com/flex/spark" title="Auto-Capitalization">
    <fx:Declarations>
        <!-- Place non-visual elements (e.g., services, value objects) here -->
    </fx:Declarations>
    
    <s:layout>
        <s:VerticalLayout/> 
    </s:layout>
    
    <s:Label text="Select a capitalization setting:"/>
    <s:SpinnerListContainer>
        <s:SpinnerList id="capTypeList" width="300" labelField="name" fontSize="12">
            <s:ArrayCollection>
                <fx:Object name="All" value="all"/>
                <fx:Object name="None" value="none"/>
                <fx:Object name="Sentence" value="sentence"/>
                <fx:Object name="Word" value="word"/>
            </s:ArrayCollection>                        
        </s:SpinnerList>
    </s:SpinnerListContainer>
    
    <s:TextInput autoCapitalize="{capTypeList.selectedItem.value}"/> 
    
</s:View>

Not all devices support auto-capitalization. If you set the value of the autoCapitalize property on a device that does not support it, the runtime ignores the value and uses the device’s default.

The SoftKeyboardType class defines the types of soft keyboards for mobile applications. You select the keyboard type with the softKeyboardType property on the text input control.

The differences among most of the keyboards such as email and contact are only slight. For example, the email keyboard presents the user with all the same keys as the contact keyboard, except replaces the microphone with the “@” symbol. The url keyboard uses the “/” symbol. The exception to this is the number keyboard. This keyboard looks like a calculator screen with a focus on numbers and operators.

<?xml version="1.0" encoding="utf-8"?>
<!-- mobile_keyboard/views/KeyboardTypes.mxml -->
<s:View xmlns:fx="http://ns.adobe.com/mxml/2009" 
        xmlns:s="library://ns.adobe.com/flex/spark" title="Keyboard Types">
    <fx:Declarations>
        <!-- Place non-visual elements (e.g., services, value objects) here -->
    </fx:Declarations>
    
    <s:layout>
        <s:VerticalLayout/> 
    </s:layout>
    
    <s:Label text="Select a keyboard type:"/>
    <s:SpinnerListContainer>
        <s:SpinnerList id="keyboardTypeList" width="300" labelField="name">
            <s:ArrayCollection>
                <fx:Object name="Contact" value="contact"/>
                <fx:Object name="Default" value="default"/>
                <fx:Object name="Email" value="email"/>
                <fx:Object name="Number" value="number"/>
                <fx:Object name="Punctuation" value="punctuation"/>
                <fx:Object name="URL" value="url"/>
            </s:ArrayCollection>                        
        </s:SpinnerList>
    </s:SpinnerListContainer>
    
    <s:TextInput softKeyboardType="{keyboardTypeList.selectedItem.value}" text=""/> 
    
</s:View>

Not all soft keyboard types are supported on all devices. If you specify a type that is not supported, then the runtime ignores the value and uses the device’s default.

When the soft keyboard pops up and a user enters text, there must be a way for the user to indicate that they are done and that they want to move to the next field or submit the entered data. On a soft keyboard, this is usually accomplished with the “return” key. This key does not enter a character in the text input, but rather signals to the text input control that the user is done entering text.

The ReturnKeyLabel class defines the possible labels for the return key. The possible values are default, done, go, next, and search. You specify the return key label with the returnKeyLabel property on the text input control.

<?xml version="1.0" encoding="utf-8"?>
<!-- mobile_keyboard/views/ReturnKeyLabels.mxml -->
<s:View xmlns:fx="http://ns.adobe.com/mxml/2009" 
        xmlns:s="library://ns.adobe.com/flex/spark" title="Return Key Labels">
    <fx:Declarations>
        <!-- Place non-visual elements (e.g., services, value objects) here -->
    </fx:Declarations>
    
    <s:layout>
        <s:VerticalLayout/> 
    </s:layout>
    
    <s:Label text="Select a return key label:"/>
    <s:SpinnerListContainer>
        <s:SpinnerList id="returnKeyLabelList" width="300" labelField="name">
            <s:ArrayCollection>
                <fx:Object name="Default" value="default"/>
                <fx:Object name="Done" value="done"/>
                <fx:Object name="Go" value="go"/>
                <fx:Object name="Next" value="next"/>
                <fx:Object name="Search" value="search"/>
            </s:ArrayCollection>                        
        </s:SpinnerList>
    </s:SpinnerListContainer>
    
    <s:TextInput returnKeyLabel="{returnKeyLabelList.selectedItem.value}" text=""/> 
    
</s:View>

There is no difference in events or interaction among the different return key types. Changing the returnKeyLabel property only changes the label of the key.

Not all devices support setting the label of the return key. If you set the value of the returnKeyLabel property on a device that does not support it, then the runtime ignores the value and uses the device’s default.

The soft 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.

The resizeForSoftKeyboard property of the Application container determines the application resizing behavior. If the resizeForSoftKeyboard property is false, the default value, the keyboard can appear on top of the application. If the value is true, then the application is resized to subtract the size of the keyboard.

To support scrolling, the text input controls must use the TextField-based skins and not the StageText-based skins. You do this by pointing the TextInput or TextArea control’s skinClass property to the TextInputSkin or TextAreaSkin class, respectively.

To scroll, 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 class, 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.

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.

<?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"> 
            <!-- Use TextField-based skins so that scrolling works. -->
            <s:TextInput prompt="To" width="100%" skinClass="spark.skins.mobile.TextInputSkin"/> 
            <s:TextInput prompt="CC" width="100%" skinClass="spark.skins.mobile.TextInputSkin"/> 
            <s:TextInput prompt="Subject" width="100%" skinClass="spark.skins.mobile.TextInputSkin"/> 
            <s:TextArea height="400" width="100%" prompt="Compose Mail" skinClass="spark.skins.mobile.TextAreaSkin"/> 
        </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.

If the resizeForSoftKeyboard property of the Application container is 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.

<?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.

While soft keyboard events are reliable enough to allow automatic behaviors to work most of the time, try to avoid positioning critical UI elements where they might be obscured by the soft keyboard should a soft keyboard event fail. For example, avoid placing “OK”, “Login”, or “Submit” buttons in the bottom half of a view.

When a StageText-based control is animated or participates in an animation, the runtime temporarily replaces it with a bitmap so that the text moves in sync with other items. If the control has focus, this causes the control to temporarily lose focus. In some cases, the soft keyboard hides or triggers a softKeyboardDeactivate event without hiding the soft keyboard.

This can be especially problematic when programmatically setting focus to StageText-based components inside popups, which animate changes in size caused by the soft keyboard. To avoid this, try to use StageText-based components in popups that do not resize because of the soft keyboard.

If you must use StageText-based components in popups that resize, try to show the soft keyboard first and wait for the popup’s animation to complete before programmatically setting focus to the StageText-based component. As an alternative, avoid setting focus programmatically inside popups.

A Callout container appears as a popup on top of a mobile application. The Callout container can hold one or more components that take keyboard input. For more information on the Callout container, see Use the Callout container to create a callout.

Use properties of the SkinnablePopUpContainer container, the parent class of Callout, to configure the popup’s interaction with a keyboard:

If a SkinnablePopUpContainer’s moveForSoftKeyboard or resizeForSoftKeyboard properties are set to true, the container might move or resize whenever the soft keyboard’s visibility changes. Both of these automatic behaviors can cause other components to change size or move.

The simplest way to avoid this scenario is to not set resizeForSoftKeyboard to true. If the application does not resize for the soft keyboard, the soft keyboard cannot cause a component to move out from under a user’s finger. However, this can cause the soft keyboard to hide some of the application’s UI.