Application Development : Text Controls (part 2) – Validator, TextArea

Validator

You can make sure that the user’s input conforms to a certain set of rules by specifying a Validator class for the TextField using its validator property. For example, for a password field you could ensure that it is of a certain length and that it contains at least a digit. You can use the validator’s mode property to specify when text validation should occur. For example, by setting the mode property to ValidationMode.Immediate, the user’s input will be validated as the user types along, and by setting the property to ValidationMode.FocusLost, the user’s input will be validated once the TextField has lost focus.  During validation, you can update the validator’s state by setting its state property, which can take one of the following values:

• ValidatationState.Unknown: Validation state is unknown. This state is used for cases where the validation process has not been initiated.
• ValidationState.InProgress: Validation is currently in progress.
• ValidationState.Valid: Validation has succeeded.
• ValidationState.Invalid: Validation has failed.

You should implement the actual validation in JavaScript by handling the validator’s validate signal, as illustrated in Listing 6.

Listing 6.  JavaScript Validation Using a Regular Expression

import bb.cascades 1.2
 
Page {
    Container {
        TextField {
            id: myField
            inputMode: TextFieldInputMode.NumbersAndPunctuation
            input {
                submitKey: SubmitKey.Go
                onSubmitted: {
                    // handle input when submit key is pressed
                    // by extracting value text from myField.text
                }
            }
            validator: Validator {
                mode: ValidationMode.Immediate
                errorMessage: "Invalid integer!"
                onValidate: {
                   // regexp for valid integer including optional sign
                    var regexp = /^\s*(\+|-)?\d+\s*$/;
                    var isValidInteger = regexp.test(myField.text);
                    if (regexp.test(myField.text))
                        state = ValidationState.Valid;
                    else
                        state = ValidationState.Invalid;
                }
            }
        }
    }
}

The regexp variable defines a valid integer (for example, 10, -99, and 0 are valid expressions, but 10.0 would be considered as invalid). The important point is that I am using the regexp variable to toggle the validator’s validation state.

Finally, here a few best practices to consider:

• Use a text field to let users input a single line of text, such as an e-mail address, a password, or a contact name.
• Include hint texts in text fields (by doing so, you won’t need to add a label describing the text field’s purpose).
• Don’t use word prediction in e-mail, password, and contact name fields. Using word prediction in these cases will simply get in the user’s way.
• Provide clear error messages when using validators.

TextArea

A TextArea is very similar to a TextField and shares many of its properties (which they both inherit from AbstractTextControl). The main difference comes from the fact that a TextArea can handle multiple lines of text, whereas a TextField provides a single line. You can set the TextArea’s inputMode using a TextAreaInputMode object (the possible values are TextAreaInputMode.Default, TextAreaInputMode.Text, TextAreaInputMode.Chat, TextAreaInputMode.Email, and TextAreaInputMode.Custom). Finally, you can also use the TextArea’s editor object to track the current cursor position or the current selected text (see Listing 4-13).

Listing 4-13.  TextArea Signal Handling

import bb.cascades 1.2
Page {
    Container {
        layout: DockLayout {
             
        }
        leftPadding: 20
        rightPadding: 20
         
        TextArea {
            id: myField
            inputMode: TextAreaInputMode.Chat
            hintText: "Enter some text"
            verticalAlignment: VerticalAlignment.Center
            preferredHeight: 500
             
            scrollMode: TextAreaScrollMode.Elastic
            onTextChanging: {
                console.log("text changing: "+text)
            }
             
            editor.onSelectionStartChanged: {
                console.log("selection start: "+selectionStart);
            }
            editor.onSelectionEndChanged: {
                console.log("selection end: "+selectionEnd);
            }
            editor.onSelectedTextChanged: {
                console.log("selectedTextChanged: " + selectedText)
            }
            editor.onCursorPositionChanged: {
                console.log("cursorPositionChanged: " + cursorPosition)
            }
        }
    }
}

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

Application Development : Controls – Button

Button

You can use buttons in order to capture touch events in your application. A Button can display some text, an image, or both. You can set the following properties on a Button:

• For sizing, you can set the preferredWidth, minWidth, and maxWidth properties. A button’s height is fixed and you cannot change it. The button’s width is increased automatically in order to fit text and images. A button will truncate its text if the text content is wider than the maxWidth property.
• The button’s text property specifies the text that will be displayed on the Button.
• You can use the image or imageSource properties for specifying an image to be displayed on the Button. In most cases, you will use the imageSource property, which will usually correspond to the URL of an image located in a subfolder of your application’s assets folder (you can also use the image property to specify a Image wrapped as a QVariant).

The button will emit the clicked signal that you can handle in QML using the onClicked signal handler (see Listing 1).

Listing 1.  Button Clicked Signal

Button{
   id: button
   text: "mybutton"
   onClicked: {
      console.log("I was clicked!")
   }
}

The following best practices apply to buttons:

• Set the button that users are most likely to tap as the default button. Also, don’t make a button associated with a destructive action as the default button.
• Use single-word labels when possible.
• Use verbs that describe the associated action (for example: Login, Cancel, Delete, or Save).

Application Development : Controls – Slider

Slider 

A Slider is a control that allows the selection of a value from a range of values (see Figure 1). You can set the range using the fromValue and toValue properties. You can handle the value using the onImmediateValueChanged signal handler. In practice, you will have to round to the closest integer the immediateValue passed to the handler (see Listing 1).

Figure 1. Slider

Listing 1.  Slider

import bb.cascades 1.0
Page {
    Container {
        TextField {
           id: texfield
        }
        Slider{
            id: slider
            fromValue: 0
            toValue: 100
            onImmediateValueChanged: {
                texfield.text = Math.round(immediateValue)
            }
        }
    }
}

Use a slider when a user needs to quickly set a value from a predetermined range of values.

Application Development : Selection Controls – RadioGroup

RadioGroup

A RadioGroup can be used to group a set of options together. However, only one option can be selected at a time. Options are displayed as radio buttons, with an optional text describing their purpose (see Figure 2).

Figure 2. RadioGroup

You can handle option selection by responding to the RadioGroup’s selectedOptionChanged signal (or alternatively, you could also directly handle the Option’s selectedChanged signal; see Listing 2).

Listing 2.  RadioGroup

// Create a RadioGroup with three options
Page {
    RadioGroup {
        Option {
            id: option1
            text: "Easy"
            onSelectedChanged: {
                if (selected) {
                    console.log("Easy selected");
                }
            }
        }
        Option {
            id: option2
            text: "Hard"
            selected: true
            onSelectedChanged: {
                if (selected) {
                    console.log("Hard selected");
                }
            }
        }
        Option {
            id: option3
            text: "Very Hard"
            onSelectedChanged: {
                if (selected) {
                    console.log("Very hard selected");
                }
            }
        }
    }
}

Use a RadioButton when users can choose between more than two mutually exclusive options.

Application Development : System Dialogs, Prompts, and Toasts – SystemToast

SystemToast

A toast is a simple pop-up message that is displayed for a predefined amount of time. The toast is for information purposes only and the user does not need to interact with it. Listing 4 shows you how to use a SystemToast to display a toast to the user.

Listing 4.  SystemToast

import bb.cascades 1.2
import bb.system 1.2
 
Page {
    Container {
        layout: DockLayout {
        }
        Button {
            text: "Show Dialog!"
            verticalAlignment: VerticalAlignment.Center
            horizontalAlignment: HorizontalAlignment.Center
            onClicked: {
                myToast.show();
            }
        }
        attachedObjects: [
            SystemToast {
                id: myToast
                body: "Happy New Year!"
            }
        ]
 
    }
}

Application Development : Controls – ScrollView

ScrollView:

A ScrollView is a container allowing the scrolling and zooming of its content. A ScrollView provides a viewport, which displays an area of the entire content. You can use a ScrollView when the content will not fit the UI entirely (for example, that would be the case if a container included many controls). Note that a ScrollView’s content can also be an ImageView or a WebView (for example, you can use a ScrollView to zoom in or out of a picture). You can control the scrolling behavior by setting the ScrollView’s scrollViewProperties property. Listing 1 shows you how to include a WebView in a ScrollView.

Listing 1.  ScrollView

Page {
    ScrollView {
        WebView {
            url: "http://www.nrcreddy.blogspot.com"
        }
        scrollViewProperties {
            scrollMode: ScrollMode.Vertical
            pinchToZoomEnabled: true
        }
    }
}

Use a ScrollView when

• A control’s content does not fit the screen and you need to provide a viewport that you can navigate (by scrolling horizontally and/or vertically).
• You need to zoom in or out of content using a pinch gesture.