Text input modes

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 () indicates that the feature is enabled by default for an input mode, and no check mark indicates that the feature is disabled by default. An X () 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
Emoticons
Spelling checker
Word prediction
Automatic word correction
Automatic capitalization
Automatic period insertion
Word substitution

TextField

Feature	Default	Chat	Text	EmailAddress	Password
Active text
Emoticons
Spelling checker
Word prediction
Automatic word correction
Automatic capitalization
Automatic period insertion
Word substitution

Feature	NumericPassword	URL	PhoneNumber	NumbersAndPunctuation
Active text
Emoticons
Spelling checker
Word prediction
Automatic word correction
Automatic capitalization
Automatic period insertion
Word substitution

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
        }
    }
}