| | 04-20-2011, 03:57 PM Thread Author #1
How to compile themes by hand
When creating my theme Reflex, instead of sticking purely to theme builder and adding my own hand-coded SVG within it, I took the approach of writing my homescreen.svg completely from scratch and then compiling the theme by hand. Following this method is definitely more tedious and prone to mistakes, however, it does allow a lot more control over the home screen objects. For example, the cutoff GPS icon in 6.0 themes was not an issue and I was not limited to only being able to manipulate objects that theme builder adds an ID tag to in it's generated SVG. It also allows for much more efficient svg resulting in a faster, more fluid theme.
I have been asked by some other theme builders to share the method used to do this, hence this thread. I should also add that I'm sure I'm not the only person who is using this method and don't consider it to be my discovery, however, I have had to learn quite a few things about the packaging of the theme files by trial and error and want to share these tips also.
To break down the steps I used initially in building Reflex:
1) I created everything except the home screen in Theme Builder in the usual manner, including the home screen banner as this is used on other screens such as the lock screen.
2) After saving and naming the theme file, I removed delete permissions from the temp folder and exported an OTA version of the theme.
3) From the windows temp folder, I located and copied the directory containing the theme files to my theme directory and named the folder 'source'.
4) Again, from the temp folder, I located the xxxxxx.properties file and copied that into my newly created source folder and renamed it 'build.properties'.
5) I opened up the 'build.properties' file in notepad and modified the .contentDir to point to my 'source' directory and the .outFileDir to point to where I wanted the compiled theme to be placed.
Here's an example properties file:
6) Next, I created a batch file in the source dir called 'build.bat' with the following contents:
7) After deleting the homescreen.svg from the source dir and writing my own I simply ran the build.bat to compile the theme into a jad and cod files. Note that you must watch the output of the batch file to ensure that your svg files compiled into pme files with no errors.
"c:\Program Files\Research In Motion\BlackBerry Theme Studio 6.0\bin\svgc.exe" *.svg
"c:\Program Files\Research In Motion\BlackBerry Theme Studio 6.0\bin\tbbundle.exe" build.properties
The above process is actually quite straightforward.
Here are some tips I've picked up while using this method:
Making further Theme Builder changes after the fact
You may want to make further changes to the initial theme builder work after the fact without going through the entire process again (especially if you did more than just editing / re-writing of a few svg files). You can bring over any changes like this:
1) Load up Theme Builder and make the changes you require, then export the theme again with the delete permissions removed from the temp folder.
2) From the temporary export directory copy the following files and paste them into your 'source' folder:
"*" will be the name of your theme file.
3) If you modified anything on any of the following screens, you will need to also copy over the relevant svg as listed:
activecallscreen.svg - Active call screen
application-menu.svg - Application menu screen
banner.svg - Application banner
incomingcallscreen.svg - Incoming call screen
lockscreen.svg - Lock screen
4) Run your build.bat file again to recompile your theme.
Can I use this with OS5.0 themes?
Yes! Just make sure that you change the build.bat file to point to svgc.exe and tbbundle.exe in the 5.0 version of theme builder instead.
You can easily change the thumbnail image associated with your theme in the theme chooser screen and the dialog that pops up when a new theme is installed by creating your own thumbnail.png in the source directory. I used the same dimensions as Theme Builder for this file, which is 192x144 but I haven't experimented to see if different sizes will work.
How do I use my own graphics in the SVG?
If you use your own graphics, such as a dock background on your homescreen, just place the .png file in the source directory and refer to it by name in your svg, for example:
How do I test in the simulator?
Use the 'Load application or theme' menu option on the simulator and select all the .cod files to load the theme. You will need to 'reset' the simulator each time you want to load a new build.
"Gotchas" to be aware of
Don't try and rename your theme by editing the build files
I tried this early on and caused myself a major headache when my testers tried to download the OTA version, they were getting weird errors about an invalid version number. If you want to rename your theme, rename the original theme builder .thm file, re-export it from theme builder and copy over the theme.xml and theme_manifest.mf, then remake your build.properties file from the newly exported version.
Font sizes / styles wrong in your theme
As I mentioned above, make sure that you *always* replace the files mentioned above when you make any changes in Theme Builder or you may end up with some messed up fonts in your theme.
Files in your source directory
This file list below is the entire contents of an exported 9650 OS6 theme, there are a few files from other device versions as I did manage to mix and match quite a few of them to lighten the load with creating each device version of Reflex. In this section I am going to try and build a list of the different files and their purpose:
These two files are core to the theme, theme.xml seems to hold all the settings chosen within Theme Builder. The theme_manifest.mf file is important to include along with the theme.xml each time as without the correct one, the theme won't build properly. It contains a checksum hash against the theme.xml. I would love to be able to decode the theme.xml file, but it appears to be in binary format which makes the job much harder. Perhaps someone who is good at this kind of thing can help out here?
These sets of files are created for the custom fonts used in Theme Buidler, there is a utility in TB's bin dir called make_rim_bitmap_font.exe which creates them. So far I've had no issues creating these files and putting them into my source directories so I can reference them in my svg's.
This is the animated gif file used for the hourglass.
- activecallscreen.svg - Active call screen
- application-menu.svg - App menu screen
- banner.svg - App banner
- homescreen.svg - Home screen
- incomingcallscreen.svg - Incoming call screen
- lockscreen.svg - Lock screen
SVG files with their accompanying pme's (compiled svg's via svgc.exe) for the different screens. Pretty straightforward stuff. You can edit these to your hearts content, just make sure that any custom fonts or graphics they reference are available in your source dir.
These are the button graphics and menu and dialog backgrounds from the controls section of TB.
These are the button graphics used on the call screens. Storm and Torch naturally have a few more of these.
Banner background graphics for app and homescreen banners.
Three graphics from the group box section in TB.
These are the icon underlay and focus graphics from the app screen section in TB.
- net_rim_bb_messaging_app.Messages.service.bes~focu s.png
- net_rim_bb_messaging_app.Messages.service~focus.pn g
- net_rim_bb_passwordkeeper.net_rim_bb_passwordkeepe r.png
- net_rim_bb_passwordkeeper.net_rim_bb_passwordkeepe r~focus.png
- net_rim_bb_voicenotesrecorder.VoiceNotesRecorder.p ng
- net_rim_bb_voicenotesrecorder.VoiceNotesRecorder~f ocus.png
- net_rim_device_apps_games_brickbreaker.BrickBreake r.png
- net_rim_device_apps_games_brickbreaker.BrickBreake r~focus.png
These are the icons and their focus variants from the app screen section in TB. You can pretty much just drop these into the source dir, although the usual sizing issues are still relevant.
This is the overlay used for icons that have new unread items.
Focus graphic used for the profiles icon on the homescreen.
Search field background graphic from the controls section in TB.
Main wallpaper from the home screen.
Thumbnail image used for the theme in the theme chooser list and in the popup when the BB detects a new theme was loaded.
These are files generated by rapc, the java cod file compiler. Not of much use that I've found so far.
Focus highlight graphic for your today displays, although you can use any name you like and just adjust the SVG accordingly.
I'll get to these later.
As I've already mentioned, I'm sure I'm not the first person to work out how to use this method, but hopefully by sharing we can do even more cool things past those already discovered in the hand coded svg thread.
I should also point out that while I went ahead and re-wrote my entire homescreen.svg from scratch for Reflex, you can always just make changes to the homescreen.svg exported by Theme Builder and still initially create your homescreen in TB.
Additionally, you can play with the other .svg files also and make some unique looking themes. I did play around a lot with the ribbon manager x-object on the app screen, but found it to be very intolerable to changes.
If I can think of anything else I missed or if any relevant questions come up I'll update this post. Hopefully, everyone can get something useful out of it.