Tech Note 04c: Tutorial: How to Create Transparent Icons and Bitmaps

This Tech Note gives detailed instructions for creating and using transparent Icons and bitmaps in an NS Basic project. It assumes you have POSE and a handheld with Palm OS 3.5 or greater. To use transparent bitmaps in a PRC file, there are 4 steps that are required. Here is the overview:

Step 1: Use an image editor to create a set of BMP files that will serve as a bitmap family. Choose a transparent background color and note its Red, Green, Blue values. These values will be necessary later on.

Step 2: Using NS Basic, compile a PRC file using the desired BMP files. At this point, those bitmaps are opaque.

Step 3: Use PilRC (Pilot Resource Compiler) to create a set of binary (*.BIN) files from the BMP files. These files have transparent backgrounds.

Step 4: Use PAR (Palm Database Archiver) to delete the original BMP files from the PRC file, and then use PAR again to add the binary files that were created in step 3.

For demonstration purposes, we will create and install 3 families of transparent images into a PRC file:

A family of 8-bit LoRes and HiRes Large Icons
A family of 8-bit LoRes and HiRes Small Icons
A family of 8-bit LoRes and HiRes Bitmaps

2.) Creating Bitmap Images

Use your favorite image editor and save the images as BMP files. There are some important things to know about them:

Standard (LoRes) Large icons should be either 22x22, 32x22, or 32x32. Small Icons should be 15x9. Large HiRes Icons are double the size - 44x44, 64x44, 64x64. Small HiRes Icons should be 30x18.

Size other bitmap images to the appropriate height and width for your application. Remember to include HiRes bitmap files that are exactly twice the width and height of the LoRes ones.

Save all images as BMP files. This is the only format supported by PilRC at this time.

Choose a transparent background color. Pick a color that will not be used for other elements of the bitmaps, and one thatís not too hard on your eyes! Again, remember to note the color's RGB values. You will need those values when you use PilRC to convert the BMP files to transparent BIN files.

Now, go ahead and create 6 bitmaps, representing 3 families, and save them as 8-bit BMP files into your NS Basic Bitmaps folder:

SmallIcon15x9.bmp  & SmallIcon30x18.bmp  A family of 8-bit LoRes and HiRes Small Icons
LargeIcon22x22.bmp & LargeIcon44x44.bmp  A family of 8-bit LoRes and HiRes Large Icons
Bitmap30x30.bmp    & Bitmap60x60.bmp     A family of 8-bit LoRes and HiRes Bitmaps

3.) Creating the Project and PRC File

We will now create an NS Basic project, add the 6 bitmaps as resources, and compile a PRC file. At this point, the BMP files all have an opaque background. Note the ID# of the Bitmap family; you will need that number later. Donít worry about the ID# for the family of Large and Small icons.

3a.) Create a New Project

TransBit

TraB

Transparent Demo

TransBit.prj

3b.) Add the Bitmap Resources to the Project

Choose Project | Add Bitmap and add the following BMP files in exactly the same order as listed below:

    SmallIcon15x9.bmp
    LargeIcon22x22.bmp
    Bitmap30x30.bmp

Now look at the Project Explorer. It should look like this:

Notice that we added the LoRes bitmaps as resources to our project. We will deal with the HiRes versions shortly. Also, pay attention to the ID of Bitmap30x30, which is 1007. We will need to remember that ID a little bit later. Now save your project file.

3c.) Create 3 Families of Bitmaps

Now its time to add the other bitmap resources to our project. In the Project Explorer, click on the 1005/Bitmap 1005 entry. Then, in the Properties - Bitmap 1005 window, click on Path, 8-bit and add SmallIcon15x9.bmp. Then click on Path, HiRes 8-bit and add SmallIcon30x18.bmp. Weíve just created a family of bitmaps which we will use for our Small Icon. The properties window should now look like this:

Notice that NS Basic set Path, 1-bit to point to one of the 2 bitmaps. Go ahead and delete this entry. Now click on 1006/Bitmap 1006 and set Path, 8-bit to LargeIcon22x22.bmp, and set Path, HiRes 8-bit to LargeIcon44x44.bmp. Delete the Path, 1-bit entry. Click on 1007/Bitmap 1007 and set Path, 8-bit to Bitmap30x30.bmp, and Path, HiRes 8-bit to Bitmap60x60.bmp. Again, delete the Path, 1-bit entry. Save your project. Now that we have setup our 3 families of bitmaps, its time to tell NS Basic what to do with them.

3d.) Assign the Families of Bitmaps

Open the Properties - TransBit window. Set ID, Large Icon to 1006, and ID, Small Icon to 1005.
The properties window should now look like this:

Weíve just told NS Basic to use the Bitmap 1006 family (LargeIcon22x22.bmp & LargeIcon22x22.bmp) for our Large Icons, and the Bitmap 1005 family(SmallIcon15x9.bmp & SmallIcon30x18.bmp) for our Small Icons. Now click the Bitmap Object on our form. In its properties window, set Bitmap ID to 1007. The program will now display a member of the Bitmap 1007 family when the application is run. Again, save your project. Now its time to compile and test our PRC file.

3e.) Compile and Test TransBit.prc

Compile the project. Start POSE and load TransBit. If everything went as planned, you should see your LoRes Large Icon. Switch to List View to check out the LoRes Small Icon. Then run TransBit to see the LoRes bitmap. Now, HotSync TransBit.prc. The 44x44 Large Icon should look much better in HiRes. Switch to List View to see the HiRes version of the Small Icon, and again load the application to see the HiRes bitmap displayed on the form. Note that, in all views, the icons and bitmaps are opaque. If you followed my earlier advice, they will all sport an unattractive beige background color. Weíre going to give all the images transparent backgrounds in just a bit.

4.) Using PilRC to Generate Bitmap Resources

The Pilot Resource Compiler (PilRC) is an application that takes a resource script file and generates one or more binary resource files that can be used when developing for the Palm Computing Platform. For example, PilRC can compile a group of BMP files into a PRC database. It can also compile BMP files into binary (*.BIN) files. These can then can be used to replace the original BMP files that were used in our NS Basic project. PilRC is a command line utility that uses an .rcp file with information about what resources to compile, and what kind of resource file to generate. This .rcp file is created with a text editor, like Notepad. The syntax for the commands within the file are covered in the PilRC manual. Read the manual carefully, and pay special attention to the section on Bitmaps. PilRC is a free utility that was created by Wes Cherry and Aaron Ardiri, and can be found on the internet.

4a.) Understanding the RCP File Syntax

Again, read the PilRC manual for details. My approach is to use PilRCís Flexible Bitmap Syntax. This has a bitmap family feature that allows us to put several bitmaps together at different color depths and resolution combinations, similar to the way NS Basic handles bitmaps in the application. According to the PilRC manual, this is the only way to specify HiRes bitmaps. A much-simplified version of the syntax for the RCP file is as follows:

For regular bitmaps:

BITMAP [ìResTypeî] ID Resource Id#
BEGIN
BITMAP ìFilenameî BPP Depth#  [TRANSPARENT R# G# B#]  [DENSITY Density#]
... etc
END

For Large and Small Icons:

ICON (or SMALLICON)  [ID Resource Id#]
BEGIN
BITMAP  ìFilenameî  BPP Depth# [TRANSPARENT R# G# B#]  [DENSITY Density#]
... etc
END

BITMAP [ìRes Typeî]:
This keyword starts a bitmap family. The ìRes Typeî (Resource Type) is optional, and defaults to ìTbmpî. However, you must specify a resource ID. Make sure the ID# is the same as your corresponding bitmap or bitmap family in PRJ file.

ICON or SMALLICON:
These keywords start a Large Icon or Small Icon family. Definitions starting with any of the ICON (Large Icon) or SMALLICON (Small Icon) keywords are always given type 'tAIB', and may include an optional ResId#. All ICONs have a default ID# of 1000; SMALLICONs default to 1001.

ID Resource ID#:
As noted above, it is the Resource ID#. If you are replacing bitmaps your PRC file, this number must match the Resource ID# of the corresponding bitmaps. However, in the PRC file, Large Icons (ICON) have an ID=1000, and Small Icons (SMALLICON) have an ID=1001 regardless of their actual ID # in the project (PRJ) file.

BEGIN...END:
Defines a bitmap family, all with the same resource ID. You must include at least one LoRes bitmap or else you will get errors in your program.

BPP Depth#:
The depth of the bitmap (Bits Per Pixel). Depth# must equal 1, 2, 4, 8, or 16. Typically, I deal only with 8-bit (256 colors) icons and bitmaps (BPP 8).

DENSITY Density#: >br> The density of the bitmap or icon file. What PilRC refers to as single density bitmaps, NS Basic calls LoRes. What PilRC refers to as double density bitmaps, NS Basic calls HiRes. Density# = 1 or 72 for LoRes images. Density# = 2 or 144 for HiRes images. Generally a bitmap family must contain at least one single-density member. By default, the sizes of icons are checked: for LoRes, Large Icons should be either 22x22, 32x22, or 32x32 and Small Icons should be 15x9. Double the sizes of the HiRes files in the family (44x44, 64x44, 64x64, and 30x18).

TRANSPARENT R# G# B#:
Ahhh! This is the whole reason for this exercise! This keyword tells PilRC how to treat the bitmap or icon file. TRANSPARENT 204 204 153 tells the compiler to make every pixel holding Red:204, Green:204, Blue:153 transparent. Thatís why you need to pick a transparent color and remember its RGB values when you create the image file.

4b.) Creating an RCP File

Open a text editor, like Notepad, and add the following commands exactly as they appear below. Better yet, Copy and Paste the following code into the file. Then save the file as PilRC-Demo.rcp.


ICON ID 1000
BEGIN
  BITMAP "LargeIcon22x22.bmp" BPP 8 DENSITY 72 TRANSPARENT 204 204 153
  BITMAP "LargeIcon44x44.bmp" BPP 8 DENSITY 144 TRANSPARENT 204 204 153
END

ICON ID 1001
BEGIN
  BITMAP "SmallIcon15x9.bmp" BPP 8 DENSITY 72 TRANSPARENT 204 204 153
  BITMAP "SmallIcon30x18.bmp" BPP 8 DENSITY 144 TRANSPARENT 204 204 153
END

BITMAP ID 1007
BEGIN
  BITMAP "Bitmap30x30.bmp" BPP 8 DENSITY 72 TRANSPARENT 204 204 153
  BITMAP "Bitmap60x60.bmp" BPP 8 DENSITY 144 TRANSPARENT 204 204 153
END

Comments: The above series of commands tells PilRC to create 3 bitmap resources. The first section creates a resource for a family of LoRes and HiRes 8-bit Large Icons (tAIB03e8.bin). The second section creates a resource for a family of LoRes and HiRes 8-bit Small Icons (tAIB03e9.bin). The final section creates a resource for a family of LoRes and HiRes 8-bit bitmaps (Tbmp03ef.bin). Note: For Small or Large Icons, it doesnít matter what their Res ID is in the PRJ file. Large Icons always default to an ID of 1000, and Small Icons default to 1001. However, we must match the Res ID of bitmaps. In this case, the ID of the bitmap in our project is 1007.

4c.) Using PilRC to Compile Bitmap Files.

Now, weíre ready to use PilRC-Demo.rcp to compile our bitmaps into binary resources with transparent backgrounds. PilRC is a DOS command line compiler. A quick look at its manual reveals a rather complex command line syntax. However, for our purposes, the syntax is very simple:

PILRC PilRC-Demo.rcp

To make compiling painless, we will create a BAT file that consists of the one-line command thatís listed above. Create the file with a text editor and name it PilRC-Demo.bat. Now we can compile the bitmaps directly from the Windows Explorer. The final step is simple: make a temp folder and put pilrc.exe, PilRC-Demo.rcp, PilRC-Demo.bat, and all 6 of our BMP files together. Then, from Windows Explorer, double-click on the BAT file. PilRC will open a DOS window and display messages about generating 68k resources from the RCP file and list the binary files that were created.

Each output filename is constructed by appending the hexcode resource ID and ".bin" to the four character resource type. Thus, our family of Large Icons (Resource Type ìtAIBî, ID 1000/Hex 03e8 ) generates a binary file named tAIB03e8.bin. Likewise, the Small Icons (Resource Type ìtAIBî, ID 1001/Hex 03e9 ) results in tAIB03e9.bin. And finally, our family of bitmaps (Resource Type ìTbmpî, ID 1007/Hex 03ef) results in a file named Tbmp03ef.bin. These binary files will be used to replace the corresponding opaque bitmaps in our PRC file. Go ahead and close the DOS window. Now its time to replace our opaque bitmaps with the transparent ones that weíve just created.

5.) Using PAR to Replace the Bitmaps

PAR (Palm Database Archiver) is a utility that creates and manipulates PalmOS database (.pdb) and resource (.prc) files. Like PilRC, it is a free utility and can be found on the internet. PAR was written by David Williams.

We will use it to first delete the opaque bitmaps. Then weíll replace them with the corresponding binary files that contain our transparent bitmaps and icons. Again, read the PAR manual carefully to understand the command-line syntax of this DOS utility. Like PilRC, we can make batch files to simplify things. Letís make 3 of them: to List whatís in our PRC file, to Delete the opaque bitmaps, and to Add our newly created binary files. We will name them: ParList.bat, ParDel.bat, & ParAdd.bat. See the next section for instructions on how to create these batch files. After you've written them, copy the batch files, along with the PAR utility (par.exe) to the temp folder containing PilRC and the image files. Then, weíll ready for the final steps.

5a.) A PAR Batch File to List the PRC Contents

While not strictly necessary, it is educational to list the contents of the PRC file. The PAR command line syntax is: par t filename.prc
Our BAT file, ParList.bat consists of one line: par t TransBit.prc
Running this batch file results in a listing of all the resources in the PRC file:

The first column shows the Resource Type, the 2nd column lists the Hex equivalent of the ID, and the 3rd column lists the size. In among the listing are 3 entries (which I highlighted) representing our families of Large and Small Icons, and the Bitmaps. Notice that the PAR's naming scheme is identical to PilRC's.

tAIB 03e8 (ID 1000, our Large Icon family)
tAIB 03e9 (ID 1001, our Small Icon family)
Tbmp 03ef (ID 1007, our Bitmap family)

5b.) A PAR Batch File to Delete the Old Bitmap Resources

The PAR command line syntax for deleting a resource from the PRC file is: par d filename.prc res type id#
Our BAT file, ParDel.bat, tells PAR to delete the current Large/Small Icon families, and the bitmap family. It consists of 3 lines:

par d TransBit.prc tAIB 1000 
par d TransBit.prc tAIB 1001
par d TransBit.prc Tbmp 1007

Just double-click on the batch file, and PAR will delete the opaque bitmaps from the PRC file.

5c.) A PAR Batch File to Add the PilRC Binary Files

The PAR command line syntax for adding a resource to the PRC file is: par d filename.prc resource filename
The final BAT file, ParAdd.bat, tells PAR to add the 3 binary files we created earlier.
Thanks to PilRC, these binary files contain our transparent icons and bitmaps!

par a TransBit.prc tAIB03e8.bin
par a TransBit.prc tAIB03e9.bin
par a TransBit.prc Tbmp03ef.bin

Again, just double-click on the batch file, and PAR will add the new resources to the PRC file.
Done! If everything went right, we can now enjoy icons and bitmaps that have transparent backgrounds.

6.) Testing the New PRC File

Load the new TransBit.prc into both the POSE and your handheld. Check out the Large & Small Icons in Icon View and List View. Then run TransBit and check out the bitmap image. The ugly beige background should now be gone, replaced by a transparent background.

7.) Miscellaneous Tips

Including bitmaps and icons into your project greatly increases the compiling time. If you are actively developing or revising an application, consider waiting until the end of development before adding all your graphics files.

Since Large Icons and Small Icons always default to a Resource ID of 1000 and 1001, there is no need to add them to the PRJ file at all! Wait until youíve compiled the final PRC file. Then use PilRC and PAR to add them to the PRC file. Again, this will save lots of compiling time.

8.) Acknowledgements and Further Information

Special thanks to Adrian Nicolaiev. This Tech Note would never have been possible without his help!

NS Basic Tech Note 04b: Creating an Images Database, by Oscar De Leon. This article demonstrates how to use PilRC to create a database of images from a collection of BMP files. Very helpful reading!

NS Basic Tech Note 24: How to Make Icons: Drawing Characters, by Misuno-Ami. Some nice tips about Icon design.

Link to download PilRC

Link to download PAR