Digging Deep: Understanding BlackBerry Theme Builder – Part 3: Manipulating Themes

Theme Development

As mentioned in Part 1 of our “Understanding BlackBerry® Theme Builder” series, when BlackBerry Theme Builder exports themes, it dumps all image and SVG files to the Windows® temp directory, uses them to compile the theme, then deletes the files. The SVG files need to be customized to provide a layout for the target device’s resolution. This portion of the process is done manually and is very difficult, so read this blog post closely!

The first thing that needs to be done is to retrieve the pz_ directory and the pz_ properties file from the Windows temp directory after BlackBerry Theme Builder exports these files , but before the files can be deleted. Doing this manually would likely not work ; it happens very quickly, so you may need to apply permissions to the directory to prevent file deletion.

(Note: When changing any system permissions it is extremely important to fully understand the repercussions and only make changes at your own discretion.)

After you have these files saved to a safe place, such as your desktop of a common development directory, you can copy the pz_ properties file to the pz_ directory to keep them all in one place.

Next you will need to open the various SVG files in the directory you save and make manual changes to support the resolution and desired layout on the target device. For example, the main SVG wrapper element has width and height attributes; these can be set to the width and height of the target device’s resolution. For any other elements, the width, height, x and y values may need to be set. Here is a list of some elements which can be accessed and modified:

  • xlink:href
    • CurrentDateTime
    • AlarmIndicator
    • BatteryLevel
    • Coverage
    • SystemStatus
    • GridIndicators
    • Roaming
    • SignalLevel
    • WLANSignalLevel
    • GPSMode
    • Image
    • OwnerInfo
    • ProfileIndicator
  • Id
    • hs_profile_underlay
    • hs_profile_entry_icon
    • hs_profile_focus_entry_icon
    • Id
    • wifi_bullets

A forum post will be started where users can contribute additional elements and attributes in the BlackBerry® Themes & Animated Graphics board.

After you have modified all of the SVG files, you will need to compile the theme files into CODs that can be installed to your device.

First, you will need to modify the ThemeBundler.contentDir element of the pz_.properties file to point to the current directory. Then you can run the following two commands from a command prompt:

\bin\svgc.exe *.svg
\bin\tbbundle.exe pz_.properties

Make sure to watch the console for any errors when parsing the SVG. If all is successful then the theme CODs should be output to the directory specified in the ThemeBundler.outFileDir element of the pz_.properties file.

Your theme is now ready to be loaded for testing onto an actual BlackBerry smartphone!

However, this method of theme creation is not an exact science. The layout of all elements and items will take some time to get right and not all portions of the theme will be fully supported. It may take some time to get it right with several testing iterations:

while (theme != perfect)
modify SVG → compile code → load onto device → test thoroughly

It would be a good idea to progress with a small number of modifications until you reach the desired theme state. A few things to note:

    1. There is a 5MB file size limit for themes on the smartphone , any themes greater than this will be rejected by the target device
    2. All images exported by Theme Studio using this method will be of an incorrect size as you are targeting a different handheld. To optimize the user experience you will need to change each image to the size expected by the target device.

Once you are satisfied, you can then distribute your theme using your preferred distribution channels, including the BlackBerry App World storefront.

Have you had success creating themes this way? Let us know in the comments!

About garett

Garett is a member of the Developer Relations team and has been with BlackBerry since 2008. He specializes in app monetization (Payment, Advertising, Analytics SDKs) and Push development. He is one of the individuals involved with the forums (gbeukeboom), Issue Tracker and can be found tweeting from @BlackBerryDev with the ^GB signature.

Join the conversation

Show comments Hide comments
+ -
blog comments powered by Disqus