Welcome to part eight of my article series on ‘Supporting BlackBerry Passport and 10.3 SDK / API’
First three parts of this article series help you to support the BlackBerry Passport from SDK / API 10.2 – the other ones are using SDK 10.3
Please read these articles before going on:
- Supporting BlackBerry Passport – step one 10.2
- Supporting BlackBerry Passport – Keyboard Shortcuts
- Supporting BlackBerry Passport – Fonts, Layouts, Logic
- Supporting BlackBerry Passport – Git, Colors and ActionBar
- Supporting BlackBerry Passport – Themes, SignatureAction, Touch on Keyboard
- Supporting BlackBerry Passport – Icons for different Resolution and Density
- Supporting BlackBerry Passport – Active Frames
As a long time Cascades Developer you always have used Pixels to define sizes, margins or paddings – so the challenge is to rethink and use ‘du’.
A ‘Design Unit’ always has the same physical size on all devices, which means for higher density you need more pixel to fill the same space. Devices are grouped into ‘buckets’ by density:
- 295 ppi (Z3, Z30): 8 buckets
- 330 ppi (Q5, Q10): 9 buckets
- 358 ppi (Z10): 10 buckets
- 453 ppi (Passport): 12 buckets
8 buckets means you need 8 Pixel for each Design Unit (du) on a Z30, but 12 Pixel on a Passport. Now it’s easy to understand, why a Padding value of 48 Pixels looks different on the devices: 48 Pixel on Z30 are 6 du (48 / 8), but only 4 du (48 / 12) on a Passport.
Let’s take a look at the screen sizes in Design Units:
- Z3/Z30: 90×160 du
- Q5/Q10: 80×80 du
- Z10: 76.8×128 du
- Passport: 120×120 du
Most of us started development for Z10, so as a first step try to get the ‘du’ dividing the Pixel by 10: an Icon for ActionBars now is 8×8 du instead of 81×81 Pixel before on a Z10, but 64×64 Pixel on a Z30, 72×72 Pixel on a Q5/Q10 and 96×96 Pixel on a Passport. If you don’t want to design all sizes, provide the one with the highest density: 96×96 Pixel or to be prepared for more future devices with even higher density use 16 buckets ( 128×128 Pixel)
Images in ActionBar, Tabs, menus
In part 6 we already discussed how Cascades is looking for Images from density-dependent folders like 10ppd, 12ppd, … These folders are important if you need images for ActionBar, Tabs, Menus … where Images are only defined by their name.
Looking for an Image like ‘edit.png’ Cascades tries to find the Image from the folder bound to density:
- Z3/Z30: 8ppd
- Q5/Q10: 9ppd
- Z10: 10ppd
- Passport: 12ppd
- <future>: 16ppd
For Images not found, Cascades is looking if there’s an Image with higher density and scales it down. If there’s only an Image found with lower density or from root, this one is used without upscaling !
Content – Images (ImageView)
What about your Images defined by ImageView ?
If you only provide the ImageSource, Cascades will try to find the right one – which means looking into your ppd folder and use the Image found without scaling. If not found, Cascades takes a look at ppd folders with higher density: if the Image was found, Cascades will scale it down. If not found Cascades takes a look at ppd folders with lower density: if found the Image will be scaled up ! This is different from ActionBar / Tab / Menu – Images where Cascades only scales down !
Attention: If the Image was found in the root folder, Cascades will use it without any scaling ! This can cause Images to become larger or smaller as expected. It’s always a golden rule: place all your Images into ppd folders ! Only Images used with fixed Pixel Size can remain in the root.
If you have to leave your Images in assets root, there’s a workaround. To guarantee same size on all devices set minWidth, maxWidth and minHeight,maxHeight for ImageView – of course using ‘du’. The example above (240×240 Pixel on passport) can be defined as an ImageView with 20 du width / height. Now Cascades knows: this Image should be 240×240 Pixel on Passport and 160×160 Pixel on Z30. Same story again: find the Image from 12ppd folder only Cascades will scale down to 160×160 Pixel on Z30 – finding the Image only as 160×160 inside 8ppd, Cascades will scale up to 240×240 Pixel on Passport ! Don’t forget to set the ScalingMethod !
Sounds confusing ? Only the first time !
Sample Project at Github
To understand it better: here’s a Cascades Project at Github to play with 🙂
In my sample I’m using three Images:
- Image ‘A’ placed into 8ppd, 9ppd, 10ppd and 12ppd as 20×20 du
- Image ‘B’ the same but only placed into 8ppd
- Image ‘C’ the same but only available from 12ppd
To see what happens if ‘B’ or ‘C’ are NOT inside ppd folders – only at root – I placed a renamed copy at assets/root and displayed it ‘as-is’ vs scaled using min/max width/height
Here’s the result from BlackBerry Passport (12ppd):
From ‘B’ in the middle you see 160×160 px are smaller then 20 du (240×240) if used unscaled from root.
… and here’s how it looks from Z30 (8ppd):
From ‘C’ in the middle you can see the too large image with 240×240 unscaled on Z30.
The ActionBar on Z30 is OK because ‘C’ was downscaled automatically – on Passport ‘B’ is too small because Cascades doesn’t upscale for ActionBar Images.
You still need some Images Device-specific for Absolute Layouts or fine-tunied backgrounds or special Covers ? Place them inside static assets folders like 1440×1440 for the BlackBerry Passport.
Have fun with BlackBerry Passport and 10.3