Text controls

Cascades includes a few different options for handling text in your app: Label, TextField, and TextArea.

Labels

A Label is a non-interactive control used to display read-only text to the user. A Label supports single and multiple line display, and you can change the appearance of the displayed text using the textStyle property. A Label also supports inline HTML styling and internal CSS definitions. In addition, you can also use emoji (a type of emoticon) in a label. For more information on rich text, see Text styles.

The image below shows Label controls with the standard and bold variants of the default text styles that are available in Cascades.


Five Label controls showing the available default text styles.

You specify the text for a Label using the text property. Label text can be set explicitly using quotation marks, or by referencing a QString object.

You can set the multiline property to true to enable multiple line display. Line breaks and word wrapping are handled automatically by the system.

You can't use images in a Label.

Sizing

Text fields

A TextField is a single-line control that accepts text input. Typically, this control is used for entering short strings of information, such as a username or email address. A TextField control has a fixed height and a variable width.


Screen showing a TextField control with input.

You can specify the hint text that appears in a TextField by using the hintText property. Hint text is displayed in a TextField when there is no input in the field. The hint text should suggest the purpose of the field to the user. By default, the hint text is "Enter text".

A TextField supports several input modes that determine the characters a text field accepts, such as phone numbers, passwords, and emoticons.

You can change the appearance of the displayed text using the textStyle property, and you can also apply inline HTML styling, and internal CSS definitions. In addition, you can also use emoji (a type of emoticon) in a text field. For more information on rich text, see Text styles.

You can test the text that's entered in a text field to make sure it conforms to a certain set of criteria. For more information on text validation, see Validating text input.

Sizing

Text areas

A TextArea is a control that accepts mutliple lines of text input. Typically, this control is used for entering longer strings of information, such as chat conversations, descriptions, or user feedback.


Screen showing a TextArea control with input.

You can specify the hint text that appears in a TextArea by using the hintText property. Hint text is displayed in a TextArea when there is no input in the field. The hint text should suggest the purpose of the field to the user. By default, the hint text is "Enter text".

A TextArea supports a number of input modes that determine the characters a text field will accept, such as phone numbers, passwords, and emoticons.

You can change the appearance of the displayed text using the textStyle property, HTML styling, and internal CSS definitions. In addition, you can also use emoji (a type of emoticon) in a text area. For more information on rich text, see Text styles.

Text entered in a text area can be tested to make sure it conforms to a certain set of criteria. For more information on text validation, see Validating text input.

Sizing

Responding to text changes

When the text in a Label, TextField, or TextArea changes, the respective control emits a textChanging() signal.

In QML, you can use the onTextChanging signal handler to respond to text changes. The following example updates the text in a Label with text that is entered in a TextField or TextArea.

// A label with label text
Label {
    id: myLabel
    text: "My text"
}
// A text field
TextField {
    onTextChanging: {
        // Update the text in the Label
        // with the text entered in the text field
        myLabel.text = text
    }
}
// A text area
TextArea {
    onTextChanging: {
        // Update the text in the Label with
        // the text entered in the text area
        myLabel.text = text
    }
}

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

#include <bb/cascades/Label>
#include <bb/cascades/TextField>
#include <bb/cascades/TextArea>
//...

// Create a label and set the label text. The mMyLabel object
// is declared in the header as follows:
// Label *mMyLabel;
mMyLabel = new Label();
mMyLabel->setText("My text");

// Create a text field
TextField *myTextField = new TextField();

// If any Q_ASSERT statement(s) indicate that the slot failed 
// to connect to the signal, make sure you know exactly why this
// has happened. This is not normal, and will cause your
// app to stop working
bool connectResult;

// Since the variable is not used in the app, this is added to avoid a 
// compiler warning
Q_UNUSED(connectResult);

// Connect the textChanging() signal to the handleTextChanging() slot
connectResult = QObject::connect(myTextField,
                                 SIGNAL(textChanging(const QString)),
                                 this, 
                                 SLOT(handleTextChanging(const QString)));
                                 
// This is only available in Debug builds
Q_ASSERT(connectResult);

// Create a text area                      
TextArea *myTextArea = new TextArea();

// Connect the textChanging() signal to the handleTextChanging() slot
connectResult = QObject::connect(myTextArea, 
                                SIGNAL(textChanging(const QString)), 
                                this, 
                                SLOT(handleTextChanging(const QString)));
        
// This is only available in Debug builds
Q_ASSERT(connectResult);       
        
//...

// Create the handleTextChanging() slot to capture the textChanging()
// signal emitted by the TextField and TextArea      
void TextRecipe::handleTextChanging(const QString text)
{
    // Update the Label text
    mMyLabel->setText(text);
}

For more information on responding to signals, see Signals and slots.

Text controls example

The following example consists of a Label, TextField, and TextArea.

When the app is started, the user is prompted to type "Activate" into the TextField. When "Activate" is entered into the TextField, the TextArea becomes enabled. Typing in the TextArea updates the Label text with the text that is being typed.

Typing "Reset" in the TextField resets all controls to their original state.

Animation showing input in a TextField enabling a TextArea, and input in the TextArea updating the text in a Label.

main.qml

import bb.cascades 1.0

Page {
    titleBar: TitleBar {
        title: "Text controls"
    }
    Container {
        topPadding: 20
        bottomPadding: 20
        rightPadding: 20
        leftPadding: 20
        
        // Create a Label and set the label text
        Label {
            id: label
            text: "Activate the TextArea and start typing, 
                  your text will appear here."
            multiline: true
            bottomMargin: 100
        }
        
        Container {
            layoutProperties: StackLayoutProperties {
                spaceQuota: 1.0
            }
            // Create a TextField and set the hint text
            TextField {
                id: textField
                bottomMargin: 20
                hintText: "Type 'Activate'"
                inputMode: TextFieldInputMode.Default
                textStyle.base: SystemDefaults.TextStyles.BodyText
                horizontalAlignment: HorizontalAlignment.Center
                onTextChanging: {
                    // Use an if statement to control the enabled 
                    // state of the TextArea
                    if (textField.text == "Activate" | 
                    		textField.text == "'Activate'") {
                        textField.hintText = "Type 'Reset'";
                        textArea.enabled = true;
                        textField.text = ("");
                    } else if (textField.text == "Reset" | 
                    		textField.text == "'Reset'") {
                        textArea.enabled = false;
                        textArea.text = "";
                        textField.hintText = "Type 'Activate'";
                        textField.text = "";
                        label.text = "Text controls";
                    }
                }
            
            }
            // Create a TextArea and set the input mode
            TextArea {
                id: textArea
                inputMode: TextFieldInputMode.Default
                horizontalAlignment: HorizontalAlignment.Center
                enabled: false
                preferredHeight: 1000
                onTextChanging: {
                    // Update the Label text with the text
                    // entered in the text area
                    label.text = textArea.text;
                }
            }
        }
    }
    attachedObjects: [
        TextStyleDefinition {
            id: textStyleBoldBig
            base: SystemDefaults.TextStyles.BigText
            fontWeight: FontWeight.Bold
        }
    ]
}

TextRecipe.h

#ifndef TEXTRECIPE_H_
#define TEXTRECIPE_H_

#include <QObject>
#include <bb/cascades/Label>
#include <bb/cascades/TextField>
#include <bb/cascades/TextArea>

namespace bb { namespace cascades { class Application; }}

class TextRecipe: public QObject
{
    Q_OBJECT

public:
    TextRecipe(bb::cascades::Application *app);

private slots:

	void handleTextFieldChanging(const QString text);

	void handleTextAreaChanging(const QString text);

private:
	bb::cascades::Label *myLabel;
	bb::cascades::TextField *myTextField;
	bb::cascades::TextArea *myTextArea;

};

#endif /* TEXTRECIPE_H_ */

TextRecipe.cpp

#include "TextRecipe.h"

#include <bb/cascades/Application>
#include <bb/cascades/Container>
#include <bb/cascades/Label>
#include <bb/cascades/Page>
#include <bb/cascades/StackLayout>
#include <bb/cascades/StackLayoutProperties>
#include <bb/cascades/SystemDefaults>
#include <bb/cascades/TextStyle>
#include <bb/cascades/TitleBar>

using namespace bb::cascades;

TextRecipe::TextRecipe(bb::cascades::Application *app)
: QObject(app)
{
    Page *page = new Page();

    Container *root = Container::create()
            .top(20)
            .bottom(20)
            .right(20)
            .left(20);

    TitleBar *tbar = TitleBar::create().title("Text controls");

    page->setTitleBar(tbar);

    // Create a Label and set the text
    myLabel = Label::create()
    		.text("Activate the TextArea and start " \
    	            "typing, your text will appear here.")
    	     .bottomMargin(100)
    	     .multiline(true);

    StackLayoutProperties *sl1 = StackLayoutProperties::create()
                .spaceQuota(1.0);

    // The recipe Container
    Container *recipeContainer = Container::create()
            .left(20.0).right(20.0)
            .horizontal(HorizontalAlignment::Center)
            .vertical(VerticalAlignment::Center)
            .layoutProperties(sl1);


    // Create a TextField and set the hint text
    myTextField = TextField::create()
    		.hintText("Type 'Activate'");

    // If any Q_ASSERT statement(s) indicate that the slot failed
    // to connect to the signal, make sure you know exactly why this
    // has happened. This is not normal, and will cause your
    // app to stop working
    bool connectResult;

    // Since the variable is not used in the app, this is added
    // to avoid a compiler warning
    Q_UNUSED(connectResult);

    // Connect the textChanging() signal to the
    // handleTextFieldChanging() slot
    connectResult = connect(myTextField,
                            SIGNAL(textChanging(const QString)),
                            this,
                            SLOT(handleTextFieldChanging(const QString)));

    // This is only available in Debug builds
    Q_ASSERT(connectResult);

    // Create a TextArea and disable it by default
    myTextArea = TextArea::create()
    		.preferredHeight(1000)
    		.enabled(false);

    // Connect the textChanging() signal to the
    // handleTextAreaChanging() slot
    connectResult = connect(myTextArea,
                            SIGNAL(textChanging(const QString)),
                            this,
                            SLOT(handleTextAreaChanging(const QString)));

    // This is only available in Debug builds
    Q_ASSERT(connectResult);

    // Add the controls to the recipe Container and set it as
    // the root component
    recipeContainer->add(myLabel);
    recipeContainer->add(myTextField);
    recipeContainer->add(myTextArea);
    root->add(recipeContainer);
    page->setContent(root);
    app->setScene(page);
}

// Create the handleTextFieldChanging() slot to capture the
// textChanging() signal emitted by the TextField
void TextRecipe::handleTextFieldChanging(const QString text)
{
    // Use an if statement to control the enabled state
    // of the TextArea
    if ((text == "Activate") | (text == "'Activate'")) {
        myTextField->setHintText("Type 'Reset'");
        myTextArea->setEnabled(true);
        myTextField->setText("");
    } else if ((text == "Reset") | (text =="'Reset'")) {
        myTextArea->setEnabled(false);
        myTextArea->setText("");
        myTextField->setHintText("Type 'Activate'");
        myTextField->setText("");
        myLabel->setText("Text controls");
    }
}

// Create the handleTextAreaChanging() slot to capture the
// textChanging() signal emitted by the TextArea
void TextRecipe::handleTextAreaChanging(const QString text)
{
    // Update the Label text with the text entered in
    // the TextArea
    myLabel->setText(text);
}

main.cpp

#include "TextRecipe.h"
 
#include <bb/cascades/Application>
#include <Qt/qdeclarativedebug.h>
 
using namespace bb::cascades;
 
Q_DECL_EXPORT int main(int argc, char **argv)
{
    Application app(argc, argv);
 
    new TextRecipe(&app);
 
    return Application::exec();
}

Last modified: 2013-12-21



Got questions about leaving a comment? Get answers from our Disqus FAQ.

comments powered by Disqus