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 system prompt to ask the user to rename a file in your app.

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, you must dismiss the prompt explicitly otherwise the prompt remains on top of the UI forever.

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

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

Screen showing a prompt.

Not available

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

using namespace bb::cascades;
using namespace bb::system;
// A public function to display a SystemPrompt in your UI
void App::showPrompt() 
{

    // 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 *prompt = new SystemPrompt();
	prompt->setTitle("Enter a new file name");
	prompt->setDismissAutomatically(true);
	prompt->inputField()->setDefaultText("abc123456");
	prompt->inputField()->setEmptyText("Enter a new ...");

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

	bool success = QObject::connect(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.

        prompt->show();

    } else {
        // Failed to connect to signal.
        prompt->deleteLater();
	}
}

You must create a slot for the finished() signal. You can define this slot as a public slot in your App.hpp header file.

public:
  App();

  Q_INVOKABLE void showPrompt();

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

And you need to implement the slot in your App.cpp file. Here's an example:

void App::onPromptFinished(
    bb::system::SystemUiResult::Type type) 
{
	if (type == SystemUiResult::ConfirmButtonSelection)
	{
		qDebug() << "Prompt Accepted:" << text;
        // The user accepted the prompt.
	}
	else {
		qDebug() << "Prompt Rejected";
		// The user rejected the prompt.
	}
}

Creating a credentials prompt

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

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.

Screen showing a credentials prompt.

Not available

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

using namespace bb::cascades;
using namespace bb::system;
void App::showCredentialsPrompt() 
{

	// Set up the credentials prompt with a title and a body
	// with some instructions.

	SystemCredentialsPrompt *credentialsPrompt = 
		new SystemCredentialsPrompt();

	credentialsPrompt->setTitle("Authentication");
	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.

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

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

	bool success = QObject::connect(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.
		credentialsPrompt->show();
	} else {
        // Failed to connect to signal.
        credentialsPrompt->deleteLater();
	}
}

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: 2014-09-30



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

comments powered by Disqus