BlackBerry Screen Shot Utility ... Torch 9850 ... a how to guide on creating your own capture script/tool

I am providing this for everyone to hopefully save you some brain damage in finding this yourself.

As I'm working on a BlackBerry project that will run on various devices I ran into an issue grabbing screenshots from the handset (including the Torch 9850 ... not quite as good as my iPhones or开发者_运维技巧 my Android EVO or Infuse, but much better than the Storm and finally starting to look like a real smartphone - great performance and battery life too).

Normally I'd use my trusty BBScreenShooter and everything would be fine, but it kept crashing when attempting to capture images on the 9850. I posted a couple of requests for help on this site, but nobody could tell me why my BBScreenShooter was crashing or why I'd get "Retrieving screen <active> data ... Error: buffer too small" when using RIM's JavaLoader utility directly.

For those who didn't know BBScreenShooter delegates the "heavy lifting" to JavaLoader to grab the images.

With the help of Mark Sohm (easily one of the most knowledgable BB guys I know walking the planet) he asked me to verify I was using JavaLoader that is included in the v7 SDK. Turns out I wasn't. Good catch Mark, and thanks!

From the looks of things it appears the earlier versions of the JavaLoader utility have byte[] buffers they use for image capture that are hardcoded ... and too small.

So, for all those who need to capture screen shots from RIM's new 480 x 800 based handsets I have included a quick "how to" guide to help you get productive ASAP.

Step 1 - Make sure you have the v7.0 SDK downloaded (doesn't have to be installed, though I cannot think of a good reason not to). For Eclipse users:

Step 1a) Go to the Help menu

Step 1b) Install New Software menu choice

Step 1c) Add the "BlackBerry - http://www.blackberry.com/go/eclipseUpdate/3.6/java" items in your "work with" field.

Step 1d) Under the "BlackBerry Java Plug-in Category", look for the "BlackBerry Java SDK v7.0.0.X" checkbox and click NEXT.

Step 1e) Accept the license agreements and continue the download and installation process.

Step 2 - Go to the installation directory for your newly added SDK. We're going to grab a copy of the path to the JavaLoader utility and use it within a BAT file that will automate the capture and naming of screen shots. This will be found at /plugins/net.rim.ejde.componentpack7.0.0_7.0.0.28/components/bin/JavaLoader.exe

Step 3 - Create a folder you'd like to use to save screen captures. This will also hold your BAT file as the BAT file is specific to this particular project.

Step 4 - Create the BAT file. In my example here I keep all my IDEs, SDK, ... effectively all development environments on a different hard drive than my OS. I keep these on drive D, but modify your BAT to reflect the location and needs of your configuration.

Step 4a) It's important to turn the echo off, otherwise you will probably be unable to use the icon on the desktop to launch this script/utility.

Step 4b) If your BAT file is running locally (same folder) as JavaLoader then this step will be unnecessary. On the other hand if your JavaLoader is on a different hard drive and tucked away deep in folders then you'll have to "change directory" to get to it. Notice the "/D" switch that is used with the "change directory - cd" command so that we can change drives and paths in the same step.

Step 4c) As I like to use timestamps for part of my file names ... set local variables to represent the current date and time.

step 4d) The following "for" statements parse out the current date and time from my Windows 7 computer into a format that I want to include as the file names for my screen captures ... file name == BlackBerry_<date image was taken>_<time image was taken>.bmp.

Step 4e) Copy the newly created device screen shot that JavaLoader captured to your target folder and use the file name we've just created.

Step 4f) Now that we've successfully got a copy of the screenshot saved in our desired target folder we can delete the temporary image that JavaLoader created.

Step 4g) I echo a little statement that lets me know it all worked.

Example BAT file:

@echo off

cd /D D:\Program Files (x86)\EclipseBlackBerry\plugins\net.rim.ejde.componentpack7.0.0_7.0.0.28\components\bin

JavaLoader screenshot tempImage.bmp

set timestampdate=%date%

set timestamptime=%time%

For /f "tokens=2-4 delims=/ " %%a in ('date /t') do (set timestampdate=%%c-%%a-%%b)

For /f "tokens=1-2 delims=/:" %%a in ('time /t') do (set timestamptime=%%a%%b)

copy tempImage.bmp "C:\Users\CirrusFlyer\Desktop\<project name>\Testing\Screenshots\BlackBerry_%timestampdate%_%timestamptime%.bmp"

DEL tempImage.bmp

echo Completed "...\<project name>\Testing\Screenshots\BlackBerry_%timestampdate%_%timestamptime%.bmp"

Step 5 - Close and save your BAT file. I kept the BAT in my actual project folder, then created a shortcut and placed it on my desktop. This way I can have my Eclipse up and running and be debugging the application on my handset, and when I want to grab a screen shot simply double-click the shortcut to execute the capture.

This will create screen shots and place them in the target directory: BlackBerry_2011-10-07_1015 PM.bmp, for example.

Step 6 - Your done. Happy coding. Hope this helps.

My next project: extending Eclipse so that I can do screen captures directly from within the IDE the same way I can when doing Android based programming.