It seems like the browser you are using has JavaScript disabled. As a result, the site will not function properly. We really want you to enable it so you may experience our site as we intended it. If you have no idea what we are talking about or if you need help, visit http://www.enable-javascript.com×
This website uses cookies. By continuing to browse this site you are agreeing to our use of cookies. Find out more on our cookie page.×

Oops, it seems like you're using an old browser that we do not fully support. If you're able to, please upgrade your browser here.×
This website uses cookies. By continuing to browse this site you are agreeing to our use of cookies. Find out more on our cookie page.×

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.

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.

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

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:

In your handle_event() function, call bps_event_get_domain() and check if the
event that was triggered came from a dialog box. If the event is a dialog box
event, then call your dialog event handler function.

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.

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.

// 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();
}

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:

In your handle_event() function, call bps_event_get_domain() and check if the
event that was triggered came from a dialog box. If the event is a dialog box
event, then call your dialog event handler function.

Creating a password change prompt

If you are creating a 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.

If you are creating a C++ 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.

1. Download the tools

Before you start developing, you'll need to visit the Downloads tab. Here you'll find downloads for the BlackBerry 10 Native SDK, BlackBerry 10 Device Simulator, and some other useful tools.

2. Try the sample apps

Now featuring a filter control, the Sample apps tab allows you to search for samples by name or by feature.

Select either the Core or Cascades radio buttons to display the samples relevant to you.

3. Educate yourself

The Documentation tab contains tons of examples, tutorials, and best practices to guide you along the path towards building an awesome app.

You can access all the documentation that you need in the left-hand navigation.

4. Start developing

The Reference tab is where you'll find essential details about how to use our APIs.

You can use the left-hand navigation to choose how you would like to browse the reference: by module, by topic, or alphabetically. If you have an idea of what you are looking for, start typing it in the Filter box.