SystemProgressDialog

December 2, 2012 — Leave a comment

Beta 4 of BlackBerry 10 Cascades provides some new classes for dialogs and toast.

These dialogs are really cool: easy to use, comfortable to customize and will support many different usecases.

Here’s one example how you can use this dialog:

As you probably know I’m developing the Open Source (Apache 2 License) Client application for OpenDataSpace – a secure cloud for BB10.

LogIn to the server and synchronize your data model will be done in some steps:

  • Authenticate the User
  • Receive user-spedific data
  • Receive user-specific settings
  • Receive structure and info about all files and folders
  • Receive a list of Users (if you are an Admin and allowed to manage users)

All these steps are Http Post Requests and you’ll get the response asynchron into a slot. It’s all like a ping-pong. While requesting and receiving your informations errors may happen and you want the user to wait until login and sync is done.

So we need a application – modal dialog and we want to display the progress.

It’s a perfect match for the new Cascades SystemProgressDialog. In this case I’m doing all the work from C++ and not in QML. There are many different cases where I have to display this dialog: from inside the app while LogIn, later from different Pages up/downloading data from the cloud or even invoked as a Card from another application. So it’s not easy to find the best place to attach this specific dialog in QML. You’ll see it’s really easy work.

At first we need an instance of the SystemProgressDialog defined in the headerfile:

#include <bb/system/SystemProgressDialog.hpp>
using namespace bb::system;
private:
    SystemProgressDialog* mProgressDialog;

… from constructor of cpp:

mProgressDialog = new SystemProgressDialog(this);

Now let us define the SystemprogressDialog:

mProgressDialog->setState(SystemUiProgressState::Active);
mProgressDialog->setEmoticonsEnabled(true);
mProgressDialog->setTitle(tr("Sync with OpenDataSpace"));
mProgressDialog->setStatusMessage(mBaseUrl);
mProgressDialog->setIcon(QUrl("asset:///images/download-icon.png"));
mProgressDialog->cancelButton()->setLabel(tr("Stop synchronization"));
mProgressDialog->confirmButton()->setLabel(QString::null);
mProgressDialog->setProgress(15);
mProgressDialog->setBody(tr("connect Server, authenticate user..."));
mProgressDialog->show();

So we have a title bar ‘Sync with OpenDataSpace’. Don’t forget to internatialize the Strings: tr() will does it by underlying Qt Translator.

Below the TitleBar an Icon is displayed. It’s up to you to decide if you need an Icon. I’m using 3 different Icons for ‘Download’, ‘Error’ and ‘Work Done’.

If you know¬† the percent of progress you have to set setProgress() with a value between 1 and 100. If you don’t set the progress value, an Activity Indicator will be displayed instead of a progress bar.

You can add some text using setBody() setStatusMessage() and there’s also a DetailMessage if you need more.

Your dialog should be friendly to your user ? Use setEmoticonsEnabled(true)

At the bottom there are up to 3 Buttons and you can set the text of the Button (Label). These Buttons are a confirmButton, cancelButton and customButton.

If a Button should not be displayed, set the Label to Null. There must be a minimum of one button, whats a good decision: your user must have a choice to interrupt.

Here you see how this SystemProgressDialog will look like:

—–

sys-pr-dialog-1
while doing some steps of server connections I’m changing the progress value and the displayed text:

mProgressDialog->setProgress(45);
mProgressDialog->setBody(tr("User received, getting Settings..."));
mProgressDialog->show();

important to know: these changes only become visible to the user after show()

sys-pr-dialog-2

next step…

sys-pr-dialog-3

next step…

sys-pr-dialog-4

all works well – all done: change the icon, set emoticon, set the state to inactive and also switch the Buttons.

While communicating with the server the Cancel Button was active, now we’re ready and the OK Button is set.

So it’s easy to connect to the signals for confirmed or canceled.

If the user doesn’t have to hit a button if all the work is done, you can simply do a cancel() instead of show() – it depends from the usecase what’s better for the users workflow.

mProgressDialog->setProgress(100);
mProgressDialog->setState(SystemUiProgressState::Inactive);
mProgressDialog->setBody(tr("Synchronization with Server done :)"));
mProgressDialog->setIcon(QUrl("asset:///images/online-icon.png"));
mProgressDialog->confirmButton()->setLabel(tr("Synchronization done"));
mProgressDialog->cancelButton()->setLabel(QString::null);
mProgressDialog->show();

here you see how it looks now with another Icon and Emoticon:

sys-pr-dialog-5

What if there’s an error ? Server Connection lost or user enters wrong credentials or so ?

Switching the Icon, another Emoticon and setting the ProgressState to ‘Error’ which changes the color to red:

mProgressDialog->setBody(errorText+" :(");
mProgressDialog->setState(SystemUiProgressState::Error);
mProgressDialog->confirmButton()->setLabel(tr("No valid result from Server"));
mProgressDialog->cancelButton()->setLabel(QString::null);
mProgressDialog->setIcon(QUrl("asset:///images/offline-icon.png"));
mProgressDialog->show();

sys-pr-dialog-6

Hopefully you now have an idea HowTo deal with Cascades SystemProgressDialog – there are some more Classes for Dialogs, Toasts and more.

Here’s a short video:

The Video


(c) 2012 Creative Commons License 3.0 (BY-NC-SA) by ekkescorner

No Comments

Be the first to start the conversation!

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s