Application Development : Text Controls (part 1) – TextField

TextField

A TextField is a single-line control that accepts text input. A TextField has fixed height and variable width. Just like a label, you can control the text styling using a TextStyleDefinition object (in other words, all the techniques described in the previous sections apply to text fields). You can specify how the text field behaves in relation to its text input by specifying its inputMode property. The following are some common values:

• TextFieldInputMode.Default: This is the default input mode.
• TextFieldInputMode.Text: An input mode for a wide variety of text.
• TextFieldInputMode.EmailAddress: An input mode for e-mail addresses.
• TextFieldInputMode.Password: An input mode for passwords.
• TextFieldInputMode.NumericPassword: An input mode for numeric passwords.
• TextFieldInputMode.Url: An input mode for URLs.
• TextFieldInputMode.PhoneNumber: An input mode for phone numbers.

In fact, a TextFieldInputMode corresponds to default values for input and content flags. Input flags determine how the text that users type is parsed and interpreted by the text field. Content flags determine how the text that users type is displayed. In practice, using one of the default TextFieldInputMode types to preset the flags is more than adequate, and you should rarely need to set the input and content flags directly. The inputMode property value also determines the kind of virtual keyboard displayed to the user when entering text. For example, TextFieldInputMode.Text is the most flexible and suitable for a wide variety of text. This mode also includes word suggestions to help users type faster. The other input modes are optimized for specific tasks such as writing e-mails or entering numeric values. For example, Figures 1 and 2 illustrate the TextFieldInputMode.EmailAddress and TextFieldInputMode.NumericPassword respectively.

Figure 1. A virtual keyboard corresponding to an e-mail address input (image source: BlackBerry)

Figure 2. A virtual keyboard corresponding to numeric password input (image source: BlackBerry)

You can capture a TextField’s input using its input grouped property, as illustrated in Listing 5.

Listing 5.  Text Capture

import bb.cascades 1.2
 
Page {
    Container {
        TextField {
            id: myField
            inputMode: TextFieldInputMode.EmailAddress
            hintText: "Enter email address"
            input{
                submitKey: SubmitKey.Go
                onSubmitted: {
                    // handle input when submit key is pressed
                    // by extracting text from myField.text
                }
            }
        }
    }
}

The submitKey property controls the text that will appear on the virtual keyboard’s Submit key (the Submit key is always located on the lower-right side of the virtual keyboard). The property can take one of the following values: SubmitKey.Go, SubmitKey.Join, SubmitKey.Next, SubmitKey.Search, SubmitKey.Send, SubmitKey.Submit, SubmitKey.Done, SubmitKey.Connect, SubmitKey.EnterKey, and SubmitKey.Replace.

You can also use a TextField’s hintText property to suggest the purpose of the field to the user when there is no input (see Listing 5).