Welcome to part six 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
Application Icons
In 10.2 you only needed one application Icon of 114×114 px – now with 10.3 and supporting more devices with high density and larger screens, you need some more:
- Z10: 110×110 px
- Z3 / Z30: 96×96 px
- Q5 / Q10: 90×90 px
- Passport: 144×144 px
Your application will still work using your old 114×114 px application icon, but it’s recommended to provide 4 Icons.
To add the Icons copy them into your project folder as you did with the app Icon before. Please open your bar-descriptor.xml, go to ‘Application’ tab and add the Icons.
Cascades will select the right one. Find more on Application Icons from Cascades docs here.
In-App Icons
In 10.2 we used 81×81 px Icons for Tabs and ActionItems in ActionBar and 61×61 px Icons in components.
You can still run your App with these Icons, but because of higher density some Pages won’t look good on BlackBerry Passport. (Images too small)
I already described that you can use a workaround and scale the Icons by yourself: check if device is Passport and set minWidth, maxWidth, minHeight, maxHeight to a higher value and let Cascades upscale the image:
ImageView {
property int imageSize: app.isPassport()?92:61
imageSource: "asset:///images/server_color.png"
minWidth: imageSize
maxWidth: imageSize
minHeight: imageSize
maxHeight: imageSize
scalingMethod: ScalingMethod.AspectFit
verticalAlignment: VerticalAlignment.Top
horizontalAlignment: HorizontalAlignment.Center
}
This works as a starting point but isn’t optimal. To be prepared for the future and to provide a great looking UI you have to design Icons in different sizes.
Cascades groups Devices by density (ppi – pixel per inch) and instead of Pixel we’re now using ‘du’ Design Units, where one ‘du’ always has the same size on a screen: 10 pixels on a Z10 are the same as 8 pixels on a Z30, 9 pixels on a Q10 or 12 pixels on BlackBerry Passport. The grouping is done by ‘ppd’ (Pixel per Design Unit), so we have these groups:
- 10 ppd: Z10 (768×1280 px, 356 ppi)
- 8 ppd: Z3 / Z30 (720×1280 px, 295 ppi)
- 9 ppd: Q5/Q10 (720×720 px, 330 ppi)
- 12 ppd: Passport (1440×1440 px, 453 ppi)
Here are the recommended sizes for 10.3:
- ActionItems, Menus, Tabs: 8×8 du
- Components: 7×7 du
- Small Buttons: 6×6 du
Let’s take a look at the ActionItems. What does 8×8 mean in reality – what sizes must your Icons have ?
- 10 ppd (Z10): 80×80 px
- 8 ppd (Z3 / Z30): 64×64 px
- 9 ppd (Q5 / Q10): 72×72 px
- 12 ppd (Passport): 96×96 px
BlackBerry 10 App development started with Z10 and 81×81 pixels. Now the Z10 belongs to the 10 ppd buckets where 8×8 du is the same as 80×80 px because 1 du == 10 px.
Please take a look at the excellent documentation from Cascades to learn more.
Supporting different resolution / density is a pain
… but you’re not alone 😉
If all this density and screen size – stuff is new to you, it’s a good idea to read about it from other platforms, too.
Android
Developing for Android ? Then you have to deal with dp (Density Pixel) and much more different sized devices out there.
Here’s the Android documentation HowTo support multiple screen sizes
Android also groups devices per density: ldpi, mdpi, hdpi, xhdpi, xxhdpi, xxxhdpi. All is measured in ‘dp’ (density pixel) which is similar to ‘du’ design units.
iOS
iOS developers also started easy supporting only one screen size and density. Then it goes on larger devices and also higher density (Retina displays).
There’s one difference: iOS developers started using ‘points’ and not ‘pixel’. At the beginning with first iPhone one point == one pixel on a 320×480 px screen.
For the higher resolution devices like iPhone 6 there’s a scale-factor of 2 which means 375 × 667 points were rendered as 750 x 1334 px to fit on a 326 ppi screen. With iPhone 6+ it’s even more complicated: now the scale-factor is 3: iPhone 6+ has 375 × 667 points, rendered as 1242 × 2208 px where the device in reality has 1080 × 1920 px, so there’s a downsampling / 1.15. Here’s a site from Paint Code explaining this in detail.
Perhaps now you understand why there are x1, x2, x3 Icon sets available for iOS developers. Great looking Icons in x1, x2 and now x3 are available from Glyphish – some are also looking great on BlackBerry 10.
BlackBerry 10.3
There’s a reason why I wrote about Android and iOS: you can see it’s a common challenge to support devices of different physical sizes and different density. Now with BlackBerry 10.3 and the BlackBerry Passport we also must prepare our apps and this means:
- more work
- perhaps more costs to design Icons, Images, Backgrounds
- restructuring of layouts
- and much more.
Because of this the first three parts of this series was HowTo go on with 10.2 as a first step to get some more time to port your apps to 10.3 carefully without pressure. Comparing Cascades with other platforms the Cascades team did a great job. I will write some more blogs next weeks to provide tips and tricks HowTo port your apps.
The real hard work is porting complex apps from 10.2 to 10.3 – creating a new 10.3 app from scratch is much more easier.
Let’s go on with the ActionItem / Menu / Tab – Icons. All Icons will be stored in special folders:
- assets/8ppd
- assets/9ppd
- assets/10ppd
- assets/12ppd
- assets/16ppd
Inside these folders it’s the same as with static assets: use exactly same subfolders and names as before. Of course it may take some time to get all your Icons designed for all sizes. Don’t worry – you can do your work step-by-step. Cascades uses a fallback strategy to find an Icon not provided in optimal size. Perhaps you’re wondering about the 16ppd folder ? There’s no device currently with such a high density but in Cascades documentations sometimes 16ppd was mentioned. So it may be a good idea to also provide Icons for 16ppd – it’s less work do design them now then in a year or so. (16 ppd means 128×128 px)
1st step: move all from root to assets/10ppd
All your Icons were designed for Z10 originally – so you should move them to the 10ppd folder. It’s important to move them out of the assets root folder – this will make it easier for Cascades to pick the right one. As soon as you start using ppd folders all Icons inside a ppd folder should not be in assets root !
In my app only some special background images are now inside assets/images and also inside device-specific folders like 1440×1440 or 720×720.
2nd step: create assets/12ppd folder
We want to start supporting BlackBerry Passport because it’s the first new Device – so we need Icons for 12 ppd.
3rd step: copy Icons from Cascades Icon Set
If you’re using Icons provided by Cascades as Icon Set for BlackBerry 10, please download the new one for 10.3 from here.
You’ll notice that all Icons are now 96×96 px instead of 81×81 from 10.2. 96×96 fits perfect for BlackBerry Passport, so copy the ones you’re using into assets/12ppd/images.
Now you have a good starting point and can add more ppd-specific Icons when they’re ready.
How does Cascades select Icons
With all these folders it’s a good idea to look behind the scenes and to know how Cascades will pick the right Icon. There are some rules you should know:
- Cascades downscales Icons from higher density
- Cascades can use, but doesn’t upscale Icons from lower density
Having all Icons in assets/10ppd and some Icons also in assets/12ppd: what happens running the App on BlackBerry Passport ?
At first Cascades looks into the assets/12ppd/images folder and picks the Icon if found.
As next Cascades checks if there are Icons with a higher density – so if you placed the Icon with 128×128 px into assets/16ppd/images Cascades will take this one and downscale to 96×96 px automatically.
If nothing found with higher density, Cascades will go down one step and finds the Icon inside assets/10ppd/images. This is lower density so the Icon will be used unchanged as 81×81.
Knowing that Cascades downscales it makes sense to start with one Icon in highest density and to test if it looks good on all devices. If all is Ok you don’t have to design all the other ones. For new Apps running under 10.3 this will be the way-to-go. To port Apps from 10.2 take the steps from above.
Icons from C++ missing ?
All I described above works perfect from QML with images referencing assets/images.
If you set Icons from C++ you have to change your code !
Probably there are some use-cases where you assigned Icons similar to this:
QString imageSource = QDir::currentPath() + "/app/native/assets/images/titlebar/";
.....
imageSource += "wifi.png";
.....
image->setImageSource(imageSource)
This works well with static assets folders used before. Static assets are merged at startup, so th assets are available from root.
Now having more then one folder with same images this won’t work anymore.
There’s a new method ‘resolveAssetPath(Url)‘ at Application class for 10.3:
QString imageSource = "images/titlebar/";
.....
imageSource += "wifi.png";
.....
image->setImageSource(Application::instance()->resolveAssetPath(imageSource));
While developing and running your app on Device from your Momentics IDE take a look at the Console where Cascades logs some info about images and pathes.
No best path found for images/titlebar/wifi.png , will use fallback path
AssetPathResolver::resolveAssetPath: Did not find any asset for basePath= /apps/xxx/native/assets/ ,
filePath= 10ppd/images/titlebar/wifi.png
In this case Cascades is looking inside default 12ppd for the image and didn’t found one. So uses fallback path and found Icon from 10ppd path.
Next parts will be on ActiveFrames and layouting using ‘du’ (Design Units)
stay tuned …
Like this:
Like Loading...
business apps 