TeaTimer should run on Touch and Keyboard devices, so I just did a first implementation and here are my experiences.

Redesign Layout Homescreen for Q10

Q10 has less space available: 720×720 instead of 768×1280. It’s worth rethinking the layout. Some screens worked out-of-the-box, but the startscreen got a redesign for Q10.

first decisions:

Moving the DropDown on top over the images

Making the ActionBar as Overlay to avoid distortion of images.

You have to reserve 96 Pixel for the DropDown UI Control.

If you expand the DropDown, it doesn’t use the complete space of the screen – only 50% were used from my experiences. Setting the height to a higher value doesn’t work. My first idea to make the Images invisible if DropDown is expanded, doesn’t look good with only half screen occupied by the DrowDown.

My solution: move the Image 360 px down (TranslateY) and all is perfect. I also hide the ActionBar to only display the DropDown where the user has make his/her choice.

To avoid flickering I’m reusing the DropDown area to show the progress while brewing the tea and placed a ‘Stop’ button to cancel the process:

Here are the Screenshots how it looks now on BlackBerry Q10:

Homescreen with Tip-of-the-day:

Selecting Tea (DropDown expanded):

Animated progress of brewing:

Tea is ready:

That’s it !

Most Screens working out-of-the-box

All other screens are working without any changes. the secret to get this: use of

ScrollView

ListView

DockLayout

Here some examples:

Minimized Views (ActiveFrame / SceneCover)

As you know, the TeaTimer is running in the background and minimized Screens have three states: stopped, brewing, ready.

Thanks to the tips from Staffan Lincoln I already have changed the minimized views for Z10 using the ‘Header’ template, so minimized is also working out-of-the-box for me:

Text is readable inside Header and it’s ok only to see 50% of the Images compared with Z10.

More work ?

As soon as I’m getting the DevAlpha C I will add some more comfort for the keyboard using shortcuts. But for now I’m having an App supporting both devices.

even the smallest utility app should follow the BlackBerry 10 Design Guides

… to provide the cool UX of this platform.
as you probably know, I just switched my main device from i to z and I’m searching to find all the apps I need for my Z10 to be satisfied.

one of these (for me important and) useful apps is a Tea Timer and I looked around at BlackBerry World, but didn’t found a TeaTimer providing BlackBerry 10 UX.

so I decided to develop my own 😉

here’s a short video to get first impressions:

edited: 2013-03-07 (begin)

I got really valuable feedback from Staffan Lincoln (Designer at TAT/Cascades) and changed the minimized views (ActiveFrame / SceneCover) and also replaced the animated Slider by an own custom animation – of course all using Cascades. (see below some more infos)

here’s the new Video demonstrating minimized Views and new animations:

ekkes TeaTimer for Z10 + DevAlpha at BlackBerry World

I started this app small (only counting a timer) but after some days of work I realized that even in this small app I’m using all concepts and frameworks of BlackBerry10 Cascades Apps.

So I got the idea to use this app as a case study to demonstrate to other users and developers what’s important to develop a BlackBerry 10 Quality App and to provide the unique BlackBerry 10 UX.

While thinking about this the next idea was born: I will use the TeaTimer as a template to develop another app, which can be used in my Cascades Trainings and also an upcoming BlackBerry Cascades book. The TeaTimer is a .99 $ app, but be prepared that next months there will be an OSS (Apache 2 licensed) sister project (egg-cooking-timer) helping you to understand how it works and to follow my trainings and the book.

The documentation of Cascades is really good and you’ll find many sample apps and cascades-projects and cascades-community-projects at Github. But you know: if you’re working on real-world-apps then all the samples are only samples and you always miss some more infos or the glue code between different parts / samples. The goal of my trainings is to fill this gap and to help you to create cool and outstanding apps with Cascades.

OK – let’s take a look …

… behind the scenes of ekkes TeaTimer:

UI Design Guide

most important if developing BlackBerry 10 applications: follow the design guidelines. perhaps it’s some more work for you but your apps will be seamless integrated into the BlackBerry 10 UX.

for me it doesn’t matter if developing a small utility like this one or a complex business application for customers: they all are following the UI Design guidelines.

Now let’s go through some parts of the TeaTimer APP and see what I did there to follow the BlackBerry 10 UI Design Guides and to develop a TeaTimer different to others.

BTW: all my previous apps are using the light theme – TeaTimer will use a dark theme.

Portrait / Landscape

In all my applications I’m always trying to have all (or most) screens available in Landscape and Portrait because from my POV an APP should not dictate the users HowTo hold the device 😉

Sometimes it’s easy and you have to do nothing – sometimes it’s more difficult or even impossible. here are some samples from ekkes TeaTimer:

I decided to use an image of 720×720 which will fit perfect for Z10 from width in portrait, height in landscape and also Q10. In Portrait the DropDown is placed below the image and in Landscape besides. I’m using a DockLayout and put all the fields without the images into a Container.

Hint: in Portrait I noticed if the DropDown was placed on the bottom of the Page even inside a ScrollView the expanded DropDown was partially invisible under the ActionBar, so I hide the ActionBar if DropDown is exanded. positive side-effecrt: the user only sees the important thing: the options of available Teas.

Another hint: if you’re using long-running animations as I’m doing with the images (see below) be aware: if orientation changes the animation is stopped, so you have to freeze the orientation while animation is running or to save and restore the values.

To be a good citizen in Portrait and Landscape isn’t always an easy job for your app – I will go into the details at my trainings.

ApplicationMenu

Swipe down from the top bezel and there should be your ApplicationMenu. Place Help, Settings or seldom used functionality there.

ekkes teaTimer added to the ApplicationMenu:

Help

About

List of Teas

Settings

Don’t forget: if you open a Menu from ApplicationMenu you have to disable this Menu or the complete ApplicationMenu until the User goes back !

Implementing these Menus I used some different technologies:

Help gives the user access to a Video (using InvocationFramework – MediaPlayer)

About opens a website (using Cascades WebView)

List of Teas is a ListView with a JSON datasource bound to a GroupDataModel

Settings are stored using QSettings. AccountService was used to select default Notebook. InvocationFramework was used

forFourSquare OAuth

to give easy Access to Notifications – Settings

MediaPlayer (through InvocationFramework)

Invoking the MediaPlayer is easy done. (You already found examples on this in my Open Source Github project at BlackBerry ‘OpenDataSpace‘.

Using the InvocationFramework the user doesn’t know that you’re calling another APP – it’s integrated into the TeaTimer and you can “peek back” or Go Back by a tap:

I created this Video to explain the APP to the user. Of course before starting the MediaPlayer rthe user gets the info that the Video will be played from Internet, so he/she can cancel to avoid traffic.

WebView (About…)

To include a site from the web you simply use a WebView. Put this WebView inside a ScrollView where scrolling in both directions is enabled, also enable PinchToZoom. There are some signals like onLoadProgressChanged(), where you easy can ad an ActivityIndicator to show the progress while the Page was loading.

The WebPage is seamless integrated into the app now – no use of a Browser:

List of Teas (JSON, GroupDataModel, ListView)

Some more infos HowTo provide data see below. Here’s how the ListView is looking:

In most cases I’m not using standard ListItems, because it’s easy to create custom ListItems. In this case we have an Image, Description and BrewingTime. One Tea can be marked as your favorite Tea – in this sample ‘Assam’ wher you see the Image with the CheckMark. You can now Add, Delete or Edit entries. If you tap on one Item you get this Page with the details:

There’s a TextField for the description, a switch (ToggleButton) to select you favorite Tea and a DateTime Picker to set the brewing time. If you change the value of the Switch, the Images right beside the Switch will also be changed automatically.

Let’s take a look at the DateTimePicker, because handling of dates isn’t always easy.

minimum / maximus are set to avoid that the user does enter wrong values, also we cannot suppress the hours, but we have to be sure that no hours are entered. using min/max is an easy way to solve this.

onValueChanged() gives us the time as value and we can use the built-in Qt.formatDateTime functions to format the value

Last thing to know: HowTo set the Value from your bound DataModel ? we have stored the brewing time as ‘mm:ss’ – the Picker needs ‘hh:mm:ss’ and we can set the value this way:

timePicker.value = timePicker.dateFromTime("00:"+data.duration)

In this case we used the dateFromTime() you can use for a Timer Picker.

Settings (QSettings)

The easiest way to store your settings is using QSettings. All values will be stored in the data directory of your app sandbox:

Settings (Remember – Notebook – Evernote)

I integrated to BlackBerry 10 Notebooks. Notebooks are part of the Remember APP and can be local Notebooks or Evernote Notebooks. Notebooks are an easy way to remember things and while preparing the Tea to be brewed perhaps you notice that you have to buy some new Tea. ekkes teaTimer makes it easy to create an entry for a Notebook. If you’re using the Remember APP with Notebooks heavy (as I’m doing) it would be nice to pre-select the Notebook where you want to store the entries and perhaps also some Tags. Tags are stored in QSettings – also the default Notebook.

To have access to a Notebook you need tqo keys: <Account-Key> and <Notebook-Key>.

Store the AccountKey and NoteBookKey in your settings and you have all we need later to invoke this Notebook (see below)

Settings (Foursquare SSO – InvocationFramework)

Next Settings are for Foursquare. What the hell am I doing with Foursquare inside a TeaTimer you may ask ?

If I’m on-the-go and want to know where’s the next place to buy Tea or to drink a cup of Tea, Foursquare is my friend, always knowing some cool places nearby. So why not integrating Foursquare to get the places with one tap ? Thanks to Kyle Fowler (@kfow35) it’s really easy to integrate Foursquare.

There’s a Github project and using SSO (SingleSignOn) you only need to make your connection between your app and Foursquare once. Then you get an OAuth token, store this token inside your (secured in sandbox) settings – data and use it invoking the Foursqueare App. (see below)

Animations

Most timers are only using a countdown. If you prefer such kind of a timer, it’s already built into the BlackBerry10 OS Clock:

I wanted to use some other kinds of animations. You probably know the Cascades Sample Lightning Crossfades where you have a slider and using this slider you can manually fade from one image to a second image.

Now it becomes difficult: normaly if an animation reaches the end, there’s an onEnded() signal where you can do your stuff. We cannot use this signal, because we want to run our App in the background and if brewing time is finished, we have to notify the user. So: don’t use onEnded() in this case !

As always with Cascades and Qt there’s a solution – in this case attach a QTimer:

Start this Timer together with your animation. QTimer also runs if your app is in the background – so you’ll get the Signal that brewing time is finished.

Fading through the Images is nice, but the User should have an information about the progress. For this I’m using a Slider.

Next question was: HowTo move the Slider on ? There’s no Animation on Sliders. As you can see from the SequentialAnimation above the fading was done changing the Opacity – and that’s the key: there’s a signal from opacity-changes, so you can calculate the value of the slider:

Now we got it: Images are fading from Image 1 … 8 while the Slider is moving forward.

Hint: Of course the user should not be able to move the Slider manually, but on the other side if you disable the Slider it doesn’t look good. I simply placed a 9-slice-image with transparent pixels on top of the slider.

How animation works if the App is minimized and running in the background see below.

begin edited: 2013-03-05

While this works and is looking nice – it’s a mis-use of the Slider. The user normaly expexts to drag a Slider back and force, what’s not possible here because the Slider is a progress indicator and set by the application. Lesson learned after some discussions with Cascades – Designers: never use a UI element in a wrong way – even if it works, it’s a brake of the rules.

In some other applications and also while loading the WebView of the About Page I’m uising a ProgressIndicator, but in this Utility app it should look different.

So I did a custom animation: a trolley with a box of tea is moving from left to right and below a counter displays the remaining time. I solved this with Sequential and ParallelAnimations and some more work at QTimer. I will write another blog on this – here you can see how it looks like now:

end edited: 2013-03-05

Hope you get an idea what you can do with Cascades animations and Qt Signals / Slots to create a cool UI / UX.

You need the details ? Come to one of my trainings.

Dialogs, SystemToast

Cascades provides some System dialogs – I already used many kinds of SystemDialogs, ProgressDialogs and SystemToasts in my OpenDataSpace app. Please take a look at the code in Github.

A typical SystemDialog looks like this one:

For the TeaTimer I added another usecase for a SystemToast: ‘Tip-of-the-Day‘

Every time the user starts the application, he/she will get another Tip-of-the-Day like this one:

This SystemToast has an Icon, Text and an OK Button. Clicking OK or doing something else will hide the SystemToast. From Settings the user can suppress these Tips. Using SystemToasts this way it’s easy to give your users some kind of help or additional informations.

Deliver and store data

It should always easy for users to start with your app. So it makes sense to deliver some data and enable the user to modify the data.

In this case I have some sorts of tea together with brewing times predefined. Cascades and JSON are working together very smooth, so my list of teas is stored as a JSON inside the assets folder of the app. This JSON datamodel looks like this:

To enable the user to change this list (add new entries, edit descriptions or brewing times) you have to copy this file from the assets folder (read-only) into the data folder of your app sandbox. so the data is hidden for the FilePicker and can only be accessed by the app and will be deleted from the phone if the app will be deleted.

Here you can see how I’m getting the data from JSON into the DataModel bound to the ListView:

Because users will only change tea sorts seldom, I placed the ListView into the ApplicationMenu. the user can also mark one tea as his favorite, which will be selected after opening the app. at the main page of the app the user sees a drop down box where he/she can select the tea easy. description and brewing time are displayed as description.

Running in the background (SceneCover, Notifications)

Users shouldn’t have to wait for a task to be finished. While the Tea is brewing they should do other things and be notified when the Tea is ready.

To solve this we have to think about

SceneCover: what should be visible if the App is minimzed

Notifications: HowTo notify the User

Minimized Apps normaly display a scaled-down screenshot from your app – but it’s much better to design the minimzed View by yourself using a SceneCover.

SceneCovers can be used from QML: attach a ComponentDefinition:

ComponentDefinition {
id: appCover
source: "AppCover.qml"
}

The SceneCover itself is defined inside the source (in this case AppCover.qml):

The good thing: now it’s also easier to use this for the Q10 – layout (less changes needed).

Thanks Staffan ! (BTW: if you ever get a chance to attend a Designer + Developer session by Staffan Lincoln and Johan Larsby it’s really worth to go)

… submitted new version to BlackBerry World.

end edited: 2013-03-04

What about the Notification ? At first I tried to notify the user with QML-code only. Was no problem to create a Notification and notify the user.

Notification was also shown in Message HUB, but I didn’t found a way to add the InvokeRequest to the Notification from QML. InvokeRequest is needed if the User should be able to open the TeaTimer APP directly from the Notification inside the HUB – so I did it in C++:

InvocationFramework

We have already seen some parts of the app where I’m using the InvocationFramework. The InvocationFramework is one of the coolest things of BlackBerry 10 and I recommend to use it: your users will get a seamless way to solve their workflows without switching between apps. I also recommend that you provide functionality of your APPs to others, if this makes sense for your use-cases. If you’re thinking about this: please provide Cards where possible and not only Open or Share functionality. …and if you’re providing Cards, try to use Viewer – then users can “peek-back”. I know it’s a kind of re-thinking app-development and it’s not so easy to give away functionality from your app “for-free” to other developers, but it’s really worth thinking of it. (and doing it)

Now let’s see how I intergrated Foursquare as a 3rdParty app and Remember-Notebooks as a native BlackBerry10 OS – App. We have already seen above HowTo do some settings for this.

Foursquare (3rdParty APP integrated)

You’re on-the-go and want to get easy access to places where to buy tea or to drink a cup of tea.

If you take a look at the code: we’re doing a CARD request. If the user has connected our APP with the Foursquare APP we use the token – if not we’re using the ClientID and SecretCode we got from registering the app with Foursquare. Using the token Foursquare will present a more-user-specific query result.

If the user has added keywords for the query in Settings we also use this – otherwise we simply put ‘Tea’ in as query.

This Query will give us a list of Venues nearby:

This Card comes in as a Composer – so user cannot peek back. I already requested some wishes at this Cascades-Forum-Thread.

If the User clicks on one entry, we can open directly from our APP this venue in Foursquare APP, where user can do a Check-In.

most important is creation of correct URI. If user has selected a default notebook we add the AccountKey:NotebookKey, if user has added Tags, we add the Tags. Also the URI must be correct encoded !
The user gets this Page directly integrated into TeaTimer app without leaving the app:

Notebook (Folder) was selected, Title was set, also a description and the Tags. Wasn’t this easy ?

BlackBerry World Reviews (the easy way)

It should be easy for your users to leave a review for your APP at BlackBerry world.