Prompts

A SystemPrompt is similar to a SystemDialog, but it adds an inputField property to collect information from the user. A prompt has two buttons (Cancel and OK) and a title, but no body text. You can also set a prompt to be dismissed automatically when one of the buttons is tapped. If you set the dismissAutomatically property to false, you must dismiss the prompt with the cancel() function otherwise the prompt will remain on top of your UI forever.

You can use the SystemUiInputField class to customize the defaultText and emptyText properties. The defaultText property is the text that appears when the prompt is first displayed, and the emptyText property is the text that appears when the user taps a button but does not enter text. The user can't tap the OK button if nothing is entered in the input field.

You can use the SystemUiInputMode class to specify which type of text you are asking 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, the finished() signal is emitted with the text that the user entered in the inputField.

Creating a system prompt in C++

The code sample below creates a SystemPrompt in C++ that is shown in the image to the right. For example, you could use a system prompt like this to ask the user to rename a file in your app.

A SystemPrompt has the same default buttons as a SystemDialog. You'll notice that the finished() signal also provides a SystemUiResult object that contains the user's input (the button that the user tapped).

Screen showing a Cascades system prompt.
// 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 filename ...");

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

You must create a slot for the finished() signal. You'll need this slot defined as a public slot in your App.hpp header.

public:
    App();

    Q_INVOKABLE void showPrompt();

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

And you will need to implement them 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 system credentials prompt in C++

A SystemCredentialsPrompt lets you collect a username and password in your app. The SystemCredentialsPrompt 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 system credentials prompt provides a Log In and a Cancel button. If the user taps Log In, the finished() signal provides a QString object for the user name, a QString object for the password, and a Boolean value to indicate whether your app should remember the user's password.

Screen showing a system credentials prompt.

The code sample below demonstrates how to create a SystemCredentialsPrompt in C++:

void App::showCredentialsPrompt() 
{

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

	SystemCredentialsPrompt *credentialsPrompt = 
		new SystemCredentialsPrompt();

	credentialsPrompt->setTitle("Authentication Required");
	credentialsPrompt->setBody("This server requires authentication. "
			"Please 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.
        // 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.
        credentialsPrompt->deleteLater();
	}
}

Last modified: 2014-06-24



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

comments powered by Disqus