Text input modes

The two text input fields, TextField and  TextArea, include predefined behavior to allow users to type in them. When a user taps one of these fields, the virtual keyboard is displayed automatically. The keyboard that's displayed is the default keyboard for the device, which is the most flexible keyboard and is suitable for typing most kinds of text.


Screen showing the how the virtual keyboard appears when a user taps a valid text entry field.

There are several other types of virtual keyboards that your app can display, and these keyboards are designed to make it easy for users to type more specific kinds of text. For example, your app might display an email address keyboard that contains the at (@) sign, so that users can enter email addresses more easily. Each keyboard behaves differently depending on the kind of text input it's designed to support. For example, the password keyboard enables character masking for the control, meaning that characters that users type don't appear in the text field or text area. Instead, a bullet (*) is displayed for each typed character.

You can use the  TextFieldInputMode::Type and  TextAreaInputMode::Type enumerations to specify the virtual keyboard to show when users tap a TextField or TextArea, respectively. Below is a list of the different types of virtual keyboards you can display and some of the unique behaviors of each type. Note that TextField controls support all of these keyboard types, but TextArea controls support only the Text and Chat types. You can also use TextFieldInputMode::Default or  TextAreaInputMode::Default to display the default keyboard on the device.

Text

The Text input mode is suitable for typing a wide variety of text. This mode provides the most flexibility of all the virtual keyboard modes and includes word suggestions to help users type faster.

Email address

The EmailAddress input mode provides an at (@) sign on the first keyboard screen, so users can type email addresses more easily without having to switch to the symbols keyboard screen.

Screen showing the text input mode of the virtual keyboard.
Screen showing the email input mode of the virtual keyboard.

Password

The Password input mode is similar to the Text mode, but adds a row of numbers at the top and enables character masking. Many passwords include numbers, and this mode lets users type these passwords faster.

Chat

The Chat input mode automatically changes certain character combinations into emoticons. For example, when a user types :), this text is changed automatically to a smiling face emoticon.

Screen showing the password input mode of the virtual keyboard.
Screen showing the chat input mode of the virtual keyboard.

URL

The Url input mode provides a ".com" button, instead of the button for a comma (,), on the first keyboard screen. The .com suffix is one of the most common URL suffixes, and so it's included for easy access.

Phone number

The PhoneNumber input mode replaces text characters with numbers, as well as common symbols that are used in phone numbers. This mode also lets users insert waits and pauses into phone numbers that they type.

Screen showing the URL input mode of the virtual keyboard.
Screen showing the phone number input mode of the virtual keyboard.

Numbers and punctuation

The NumbersAndPunctuation input mode includes numbers and symbols instead of letters. Users can tap the button with the blue dot on the left side of the keyboard to view additional symbols.

Numeric password / PIN

The NumericPassword and PIN input modes are designed to let users type text that consists of numbers and a limited set of letters. The NumericPassword mode also provides character masking.

Screen showing the numbers and punctuation input mode of the virtual keyboard.
Screen showing the numeric password input mode of the virtual keyboard.

Here's how to specify the text input mode for a TextField and TextArea, in QML. You use the inputMode property and provide a mode from the TextFieldInputMode::Type or TextAreaInputMode::Type enumerations, depending on which control you're using.

import bb.cascades 1.0
  
Page {
    content: Container {
        TextField {
            hintText: "Tap here to display a password keyboard"
             
            inputMode: TextFieldInputMode.Password
        }
         
        TextArea {
            hintText: "Tap here to display a chat keyboard"
             
            inputMode: TextAreaInputMode.Chat
        }
    } // end of Container
} // end of Page

Here's how to do the same thing in C++.

// Create the root page and top-level container
Page *root = new Page;
Container *topContainer = new Container;
 
// Create the text field and text area, specifying the input mode for each
TextField *textField = TextField::create()
                        .hintText("Tap here to display a password keyboard")
                        .inputMode(TextFieldInputMode::Password);
TextArea *textArea = TextArea::create()
                        .hintText("Tap here to display a chat keyboard")
                        .inputMode(TextAreaInputMode::Chat);
 
// Add the text field and text area to the top-level container
topContainer->add(textField);
topContainer->add(textArea);
 
// Set the content of the page
root->setContent(topContainer);

Content flags and input flags

Each of the text input modes described above includes default features that make it easier for users to type specific kinds of text. For example, a TextField that uses the TextFieldInputMode::Chat input mode includes features such as word prediction, automatic word correction, and automatic capitalization. These features can make it easier and quicker for users to type chat text, and so they're enabled by default when you use the Chat input mode. However, a TextField that uses the TextFieldInputMode::EmailAddress input mode doesn't include these features (that is, these features aren't enabled by default for this input mode). Email addresses can contain unusual strings of text, so these features might make it difficult to type email addresses accurately.

The following tables indicate which features are enabled by default for TextArea and TextField controls. Features are listed in the left column, and text input modes are listed in the top row. Text input modes are defined in the TextAreaInputMode::Type and TextFieldInputMode::Type enumerations, as appropriate. A check mark (Enabled by default.) indicates that the feature is enabled by default for an input mode. A circle (Disabled by default.) indicates that the feature is disabled by default. An X (Not available.) indicates that the feature is not available for an input mode (that is, the feature is disabled and cannot be enabled).

TextArea

Feature Default Chat Text
Active text
Enabled by default.


Enabled by default.


Enabled by default.

Emoticons
Disabled by default.


Enabled by default.


Disabled by default.

Spelling checker
Enabled by default.


Disabled by default.


Enabled by default.

Word prediction
Enabled by default.


Enabled by default.


Enabled by default.

Automatic word correction
Enabled by default.


Enabled by default.


Enabled by default.

Automatic capitalization
Enabled by default.


Enabled by default.


Enabled by default.

Automatic period insertion
Enabled by default.


Enabled by default.


Enabled by default.

Word substitution
Enabled by default.


Disabled by default.


Enabled by default.

TextField

Feature Default Chat Text EmailAddress Password
Active text
Disabled by default.


Enabled by default.


Disabled by default.


Disabled by default.


Not available.

Emoticons
Disabled by default.


Enabled by default.


Disabled by default.


Disabled by default.


Not available.

Spelling checker
Disabled by default.


Disabled by default.


Disabled by default.


Disabled by default.


Not available.

Word prediction
Enabled by default.


Enabled by default.


Enabled by default.


Disabled by default.


Not available.

Automatic word correction
Enabled by default.


Enabled by default.


Enabled by default.


Disabled by default.


Not available.

Automatic capitalization
Enabled by default.


Enabled by default.


Enabled by default.


Disabled by default.


Not available.

Automatic period insertion
Enabled by default.


Enabled by default.


Enabled by default.


Disabled by default.


Not available.

Word substitution
Enabled by default.


Disabled by default.


Enabled by default.


Disabled by default.


Not available.

Feature NumericPassword URL PhoneNumber NumbersAndPunctuation
Active text
Not available.


Disabled by default.


Disabled by default.


Disabled by default.

Emoticons
Not available.


Disabled by default.


Disabled by default.


Disabled by default.

Spelling checker
Not available.


Disabled by default.


Disabled by default.


Disabled by default.

Word prediction
Not available.


Disabled by default.


Disabled by default.


Disabled by default.

Automatic word correction
Not available.


Disabled by default.


Disabled by default.


Disabled by default.

Automatic capitalization
Not available.


Disabled by default.


Disabled by default.


Disabled by default.

Automatic period insertion
Not available.


Disabled by default.


Disabled by default.


Disabled by default.

Word substitution
Not available.


Disabled by default.


Disabled by default.


Disabled by default.

Cascades uses two types of flags to indicate which features to enable for TextArea and TextField controls:

  • Text input flags: These flags determine how the text that users type is parsed and interpreted by the control. For example, text input flags represent features such as spelling checker, word prediction, and word substitution. Text input flags are defined in the TextInputFlag::Type enumeration (TextInputFlag::SpellCheck, TextInputFlag::WordSubstitution, and so on).
  • Text content flags: These flags determine how the text that users type is displayed by the control. For example, text content flags represent features such as active text and emoticons. Text content flags are defined in the TextContentFlag::Type enumeration (TextContentFlag::ActiveText, TextContentFlag::Emoticons, and so on). You can also apply text content flags to Label controls.

You can use these flags to specify which features you want to enable for text controls in your app. The TextArea and TextField controls include a content property (to specify text content flags) and an input property (to specify text input flags). Each property accepts an object of the appropriate type: TextContentProperties for the content property, and TextInputProperties for the input property.

The easiest way to specify flags is by defining the TextContentProperties object or TextInputProperties object implicitly in QML. This approach is similar to how you can define a TextStyleDefinition object implicitly to apply a text style to a control. Here's how to create a TextField with an input mode of TextFieldInputMode::Text. This field uses a text content flag to enable the display of emoticons.

import bb.cascades 1.0
 
Page {
    content: TextField {
        inputMode: TextFieldInputMode.Text
        
        content {
            flags: TextContentFlag.Emoticons
        }
    }
}

Each feature (emoticons, word prediction, and so on) has two associated flags. You use one flag to enable the feature, and you use the other flag to disable the feature. For example, the word prediction feature includes the flags TextInputFlag::Prediction and TextInputFlag::PredictionOff, which enable and disable word prediction, respectively.

You should make sure to specify only one of the two flags for a particular feature at a time. If you specify both flags for a feature at the same time (for example, both Prediction and PredictionOff), the behavior is undefined. If you don't specify either flag, the default behavior for the control and input mode are used (as outlined in the tables above).

To enable or disable multiple features at the same time, you can specify multiple flags in the content or input properties. You can bitwise OR flags together by using a vertical bar (|) symbol. Here's how to create a TextField that uses the TextFieldInputMode.Text input mode. Flags are used to enable emoticons and active text, as well as disable word prediction and automatic word correction.

import bb.cascades 1.0
 
Page {
    content: TextField {
        inputMode: TextFieldInputMode.Text
        
        content {
            flags: TextContentFlag.Emoticons |
                   TextContentFlag.ActiveText
        }
        
        input {
            flags: TextInputFlag.PredictionOff |
                   TextInputFlag.AutoCorrectionOff
        }
    }
}

If you want to disable the virtual keyboard for a text field, which prevents the keyboard from being displayed when users tap inside the field, you can use the TextInputFlag::VirtualKeyboardOff flag. This approach can be useful if you want to handle text input in a customized way in your app (for example, by creating and displaying your own keyboard or input UI).

Even if you disable the virtual keyboard for a text field in your app, users can still display the keyboard manually by swiping up from the bottom of the screen with two fingers.

Last modified: 2013-12-21

comments powered by Disqus