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.
import bb.cascades 1.0
import bb.system 1.0
// Create one page with a button
Page {
    Container {
        layout: StackLayout {}
        
        Button {
            
            text: "Show Prompt"
            onClicked: {               
                prompt.show()            
            }
            attachedObjects: [
                // Set up the prompt with a title, default
                // text for your inputField, and some text  
                // to present to the user to remind them to 
                // enter something 
                // This prompt is dismissed automatically 
                // when the button is tapped.
                SystemPrompt {
                    id: prompt
                    title: "Enter a new file name"
                    dismissAutomatically: true
                    inputField.defaultText: "abc123456"
                    inputField.emptyText: "Please enter a new filename"
                }
            ]
        }
    }
}
#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.
	}
#include <bps/bps.h>
#include <bps/dialog.h>
dialog_instance_t prompt_dialog = 0;

const char *txt_msg = "Enter a new file name";

dialog_create_prompt(&prompt_dialog);
dialog_set_prompt_message_text(prompt_dialog, txt_msg);
dialog_add_button(prompt_dialog, DIALOG_CANCEL_LABEL, true, NULL, true);
dialog_add_button(prompt_dialog, DIALOG_OK_LABEL, true, NULL, true);

dialog_show(prompt_dialog);

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";
	}
}

You can extract the text that the user entered in the prompt by calling dialog_event_get_prompt_input_field(). You can extract other information by calling the following functions:

For example, in your event loop in your main.c file, handle all input on the screen by calling a handle_event() function.

show_prompt_dialog();

while (!shutdown)
{
    /* Handle user input */
    handle_event();
}

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.

static void handle_event()
{
    int domain;
    bps_event_t *event = NULL;

    if (BPS_SUCCESS != bps_get_event(&event, -1))
    {
        fprintf(stderr, "bps_get_event() failed\n");
        return;
    }

    if (event)
    {
        domain = bps_event_get_domain(event);

        /* Determine if this event is a dialog event */
        if (domain == dialog_get_domain())
        {
            /* Handle the dialog event */
            handle_dialog_event(event);
        }
    }
}

In your handle_dialog_event() function, capture the data that the user entered in the prompt by calling dialog_event_get_prompt_input_field().

/*
 * This function captures dialog information and user input
 */
static void handle_dialog_event(bps_event_t *event)
{
     if (event == NULL) return;

    /* Get the dialog instance that triggered the event */
    current_dialog = dialog_event_get_dialog_instance(event);

    /* Capture the index of the button that was tapped */
    int selected_button_idx= dialog_event_get_selected_index(event);

    /* Capture the label of the button that was tapped */
    const char* buttonLabel = dialog_event_get_selected_label(event);

    /* Create a buffer to hold the data in the dialog box */
    char output[1024];

    /* Determine what type of dialog box triggered the event */
    if (current_dialog == prompt_dialog)
    {
        /* Capture the prompt dialog data */
        const char* userInput = dialog_event_get_prompt_input_field(event);

        /* Store the dialog data in a buffer */
        snprintf(output, 1024,
                "Selected Button Index: %d\nButton Label: %s\nInput: %s",
                selectedBtnIndx,
                buttonLabel ? buttonLabel : "n/a",
                userInput ? userInput : "-- none --");
    }

    /* Output the dialog data to the console */
    fprintf(stderr, output);

    /* Clean up */
    dialog_destroy(current_dialog);
    current_dialog = 0;
}

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.

import bb.cascades 1.0
import bb.system 1.0

// Create one page with a button
Page {
    Container {
        layout: StackLayout {}

        Button {
            
            text: "Show Credentials Prompt"
            onClicked: {               
                credentialsPrompt.show()            
            }
            attachedObjects: [
                // Set up the credentials prompt with a title
                // and a body with some instructions
                SystemCredentialsPrompt {
                    id: credentialsPrompt
                    title: "Authentication"
                    body: "This server requires authentication." +
                          "Enter your username and password."
                    includeShowPassword: true
                    includeRememberMe: true                  
                    dismissAutomatically: true
                }
            ]
        }
    }
}
#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();
	}
#include <bps/bps.h>
#include <bps/dialog.h>
dialog_instance_t login_dialog = 0;

/* Create a login dialog box with placeholders
 * for username and password fields
 */

dialog_create_login(&login_dialog);
dialog_set_title_text(login_dialog, "Authentication");

char *login_message = "This server requires authentication.\n"
            "Enter your username and password.\n";

dialog_set_login_message_text(login_dialog, login_message);
dialog_set_login_username_placeholder(login_dialog, "Username");
dialog_set_login_password_placeholder(login_dialog, "Password");

/* Set the default behavior to remember the information that
 * was entered by the user
 */
dialog_set_login_remember_me_label(login_dialog, "Remember Me");
dialog_set_login_remember_me(login_dialog, true);

dialog_add_button(login_dialog, DIALOG_CANCEL_LABEL, true, NULL, true);
dialog_add_button(login_dialog, "Login", false, NULL, true);

dialog_show(login_dialog);

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.

You can extract the credentials that the user entered in the prompt by calling dialog_event_get_login_username() and dialog_event_get_login_password(). You can extract additional information by calling the following functions:

For example, in your event loop in your main.c file, handle all input on the screen by calling a handle_event() function.

show_login_dialog();

while (!shutdown)
{
    /* Handle user input */
    handle_event();
}

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.

static void handle_event()
{
    int domain;
    bps_event_t *event = NULL;

    if (BPS_SUCCESS != bps_get_event(&event, -1))
    {
        fprintf(stderr, "bps_get_event() failed\n");
        return;
    }

    if (event)
    {
        domain = bps_event_get_domain(event);

        /* Determine if this event is a dialog event */
        if (domain == dialog_get_domain())
        {
            /* Handle the dialog event */
            handle_dialog_event(event);
        }
    }
}

In your handle_dialog_event() function, capture the data that the user entered in the prompt by calling dialog_event_get_login_username() and dialog_event_get_login_password().

/*
 * This function captures dialog information and user input
 */
static void handle_dialog_event(bps_event_t *event)
{
    if (event == NULL) return;

    /* Get the dialog instance that triggered the event */
    current_dialog = dialog_event_get_dialog_instance(event);

    /* Capture the index of the button that was tapped */
    int selected_button_idx= dialog_event_get_selected_index(event);

    /* Capture the label of the button that was tapped */
    const char* buttonLabel = dialog_event_get_selected_label(event);

    /* Create a buffer to hold the data in the dialog box */
    char output[1024];

    /* Determine what type of dialog box triggered the event */
    if (current_dialog == login_dialog)
    {
        /* Capture the login dialog data */
        const char* username = dialog_event_get_login_username(event);
        const char* password = dialog_event_get_login_password(event);
        bool rememberMe = dialog_event_get_login_remember_me(event);

        /* Store the dialog data in a buffer */
        snprintf(output, 1024,
                "Selected button index: %d\nButton Label: %s\nUsername: %s\n"
                "Password: %s\nRemember me: %s",
                selectedBtnIndx,
                buttonLabel ? buttonLabel : "n/a",
                username ? username : "username is empty",
                password ? password : "password is empty",
                rememberMe ? "true" : "false");
    }

    /* Output the dialog data to the console */
    fprintf(stderr, output);

    /* Clean up */
    dialog_destroy(current_dialog);
    current_dialog = 0;
}

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.

import bb.cascades 1.0
import bb.system 1.0
// Create one page with a button
Page {
    Container {
        layout: StackLayout {}

        Button {
            
            text: "Show Password Change Prompt"
            onClicked: {               
                passwordPrompt.show()            
            }
            attachedObjects: [
                // Set up the password prompt with a title
                // and a body with some instructions
                // Change the mode of this prompt to use
                // the password input mode 
                SystemPrompt {
                    id: passwordPrompt
                    title: "Password Change"
                    body: "Please reset your password." 
                    includeRememberMe: true 
                    dismissAutomatically: true
                    inputField.emptyText: "Please enter a new password"
                    inputField.inputMode: SystemUiInputMode.Password
                }
            ]
        }
    }
}

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.

#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 change their password

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

	m_passwordPrompt->setTitle("Password Change");
    m_passwordPrompt->setBody("Please reset your password.");
	m_passwordPrompt->setDismissAutomatically(true);
	m_passwordPrompt->setIncludeRememberMe(true);
	m_passwordPrompt->inputField()->setEmptyText("Please enter a new password");
    m_passwordPrompt->inputField()->setInputMode(SystemUiInputMode::Password);

    // 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_passwordPrompt->show();
	} else {
        // Failed to connect to signal

        m_passwordPrompt->deleteLater();
	}
#include <bps/bps.h>
#include <bps/dialog.h>
dialog_instance_t password_change_dialog = 0;

dialog_create_password_change(&password_change_dialog);
dialog_set_title_text(password_change_dialog, "Password Change");
dialog_set_prompt_message_text(password_change_dialog, "Please reset your password.");

dialog_set_password_change_username(password_change_dialog, "MyUsername");
dialog_set_password_change_old_password_placeholder(password_change_dialog, "Old Password");
dialog_set_password_change_new_password_placeholder(password_change_dialog, "New Password");
dialog_set_password_change_confirm_password_placeholder(password_change_dialog, "Confirm Password");

dialog_add_button(password_change_dialog, DIALOG_CANCEL_LABEL, true, NULL, true);
dialog_add_button(password_change_dialog, DIALOG_OK_LABEL, true, NULL, true);

dialog_show(password_change_dialog);

Last modified: 2015-04-16



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

comments powered by Disqus