Prompts

A prompt is similar to a dialog box, but it adds an input field to collect information from the user. For example, you could use a prompt to ask the user to rename a file.

A prompt has two buttons (Cancel and OK) and a title, but no body text. You can set a prompt to be dismissed automatically when the user taps one of the buttons. If you define the prompt so that it isn't dismissed automatically, the prompt remains on top of the UI until you explicitly dismiss the prompt.

You can customize the default text and empty text of the prompt. The default text is the text that appears when the prompt is first displayed, and the empty text is the text that appears in the input field when the user taps a button but doesn't enter text. If nothing is entered in the input field, the user can't tap the OK button.

Before you create a prompt, see Prerequisites.

Creating a prompt

The code samples below create the prompt that's shown in the image to the right.

A prompt has the same default buttons as a dialog box. You can use the signals and events of the prompt to find the user's input (the button that the user tapped and the text that the user entered). For more information, see Extracting the user input from a prompt.

Screen showing a prompt.

Not available

#include <bb/system/SystemPrompt>
#include <bb/system/SystemUiResult>

using namespace bb::cascades;
using namespace bb::system;
    // Set up the prompt with a title, a default for your
    // inputField, and some text to present to the user to 
    // remind them to enter text. This prompt will be 
    // dismissed automatically when the button is tapped.

    SystemPrompt* m_prompt;
    m_prompt = new SystemPrompt(this);

	m_prompt->setTitle("Enter a new file name");
	m_prompt->setDismissAutomatically(true);
	m_prompt->inputField()->setDefaultText("abc123456");
	m_prompt->inputField()->setEmptyText("Please enter a new filename ...");

    // Connect the finished() signal to the onPromptFinished() slot.

	bool success = QObject::connect(m_prompt,
	   	 SIGNAL(finished(bb::system::SystemUiResult::Type)),
	   	 this,
	   	 SLOT(onPromptFinished(bb::system::SystemUiResult::Type)));

	if (success) {
	    // Signal was successfully connected.
		// Now show the prompt in your UI.

		m_prompt->show();
	} else {
        // Failed to connect to signal.
        // This is not normal in most cases and can be a critical situation
        // for your app! Make sure you know exactly why this has happened.
        // Add some code to recover from the lost connection below this line.
        m_prompt->deleteLater();
	}

Extracting the user input from a prompt

You can use the signals and events of a prompt to get the user's input (that is, the text that the user entered and the button that the user tapped).

When the finished() signal is emitted, you can use the following properties to get the results of the user's action:

You can use various functions to extract the user's input. For more information, see the C++ tab.

When the finished() signal is emitted, you can extract the text that the user entered in the prompt by calling inputFieldTextEntry(). You can extract other information by calling the following functions:

Here's an example of a public slot that you can define in your applicationui.hpp header file:

#include <bb/system/SystemPrompt>
#include <bb/system/SystemUiResult>

public:
    // ... 
  Q_INVOKABLE void showPrompt();

public slots:
  void onPromptFinished(bb::system::SystemUiResult::Type type);

private:

    SystemPrompt* m_prompt;

In the code sample above, the m_prompt variable is defined in the applicationui.hpp header file so that it is available to use in the public slot.

You can implement the slot in your applicationui.cpp file as follows:

void ApplicationUI::onPromptFinished(
    bb::system::SystemUiResult::Type type)
{
	if (type == SystemUiResult::ConfirmButtonSelection)
	{
        // The user accepted the prompt
	    qDebug() << "Prompt Accepted:" << m_prompt->inputFieldTextEntry();
	} else {
		// The user rejected the prompt
		qDebug() << "Prompt Rejected";
	}
}

Creating a credentials prompt

The code samples below create the credentials prompt that's shown in the image to the right.

A credentials prompt (or login prompt) lets you collect a username and password in your app. The prompt also provides a toggle button to allow the user to display the password as it is typed (or have it masked) and a check box to specify whether to remember the credentials.

Screen showing a credentials prompt.

A credentials prompt provides a Log In and a Cancel button. If the user taps Log In, you can retrieve the username, the password, and a Boolean value to indicate whether your app should remember the user's password. For more information, see Extracting the username and password.

Not available

#include <bb/system/SystemCredentialsPrompt>
#include <bb/system/SystemUiResult>

using namespace bb::cascades;
using namespace bb::system;
	// Set up the credentials prompt with a title and a body
	// with some instructions.

    SystemCredentialsPrompt* m_credentialsPrompt;
    m_credentialsPrompt = new SystemCredentialsPrompt();

	m_credentialsPrompt->setTitle("Authentication");
	m_credentialsPrompt->setBody(
		"This server requires authentication. "
		"Enter your username and password.");

	// For this credentials prompt, we will show the
	// password, include a check box to remember the
	// password, and automatically dismiss this prompt
	// when any button is tapped.

	m_credentialsPrompt->setIncludeShowPassword(true);
	m_credentialsPrompt->setIncludeRememberMe(true);
	m_credentialsPrompt->setDismissAutomatically(true);

	// Connect the finished() signal to the 
	// onCredentialsFinished() slot.

	bool success = QObject::connect(m_credentialsPrompt,
	     SIGNAL(finished(bb::system::SystemUiResult::Type)),
	     this,
	     SLOT(onCredentialsFinished(
			bb::system::SystemUiResult::Type)));

	if (success) {
	    // Signal was successfully connected.
		// Now show the credentials prompt in your UI.
		m_credentialsPrompt->show();
	} else {
        // Failed to connect to signal.
        m_credentialsPrompt->deleteLater();
	}

Extracting the username and password

You can use the signals and events of a credentials prompt to get the user's input (that is, the username and password that the user entered).

When the finished() signal is emitted, you can use the following properties to get the results of the user's action:

You can use various functions to extract the user's input. For more information, see the C++ tab.

When the finished() signal is emitted, you can extract the username and password that the user entered in the credentials prompt by calling usernameEntry() and passwordEntry(). You can use the following functions to extract other information:

Here's an example of a public slot that you can define in your applicationui.hpp header file:

#include <bb/system/SystemCredentialsPrompt>
#include <bb/system/SystemUiResult>

public:
    // ... 

    Q_INVOKABLE void showCredentialsPrompt();

public slots:
    void onCredentialsFinished(bb::system::SystemUiResult::Type type);

private:
    SystemCredentialsPrompt* m_credentialsPrompt;

In the code sample above, the m_credentialsPrompt variable is defined in the applicationui.hpp header file so that it is available to use in the public slot.

You can implement the slot in your applicationui.cpp file as follows:

void ApplicationUI::onCredentialsFinished(
    bb::system::SystemUiResult::Type type)
{
	if (type == SystemUiResult::ConfirmButtonSelection)
	{
        // The user accepted the credentials prompt
		qDebug() << "Credentials Login:" << m_credentialsPrompt->usernameEntry();
		qDebug() << "Credentials Password:" << m_credentialsPrompt->passwordEntry();
		qDebug() << "Credentials Remember Me:" << m_credentialsPrompt->rememberMeSelection();
	} else {
		// The user rejected the credentials prompt
		qDebug() << "Credentials Rejected";
	}
}

Qdebug() is used for demonstration purposes only. Your app shouldn't output user credentials to the console.

Creating a password change prompt

Not available

If you are creating a C++ or QML app, you can use the SystemUiInputMode class to specify which type of text you are prompting the user for. The type triggers the most appropriate keyboard for user input.

For example, you can use SystemUiInputMode::Password to display a keyboard that adds a row of numbers at the top of the keyboard and includes character masking. For more information about text input modes, see Text. When the user taps the confirmButton on the prompt, the finished() signal is emitted with the text that the user entered in the inputField.

Last modified: 2015-01-22



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

comments powered by Disqus