Drawing a Bitmap Family Member

This description is specific to Palm OS 3.5 and later, but for information on earlier Palm OS versions, see the [CompatNote compatibility notes] below.

# Use Constructor for Palm OS to open the form that will contain the bitmap.

# In the Project Window, create a new Bitmap Family.

# Open the Bitmap Family resource and set the values for the properties.

# Note that every member of the Bitmap Family must have the same Width and Height.

# You can set one of the colors to be transparent when the bitmap is drawn to the screen.

# You can add bitmaps of different depths to the bitmap family by selecting Edit > New Family Member(also by using Ctrl-K on Windows or Cmd-K on Macintosh). You can use up to five bitmap depths in one bitmap family, but bitmap images must be stored in increasing order of bit depth, and the bit depths must be unique. For backward compatibility, you should always have a 1-bit black and white bitmap as the first bitmap in the bitmap family.

# Do not add a Form Bitmap to the form. Rather, use the following code to draw the correct member of the bitmap family for the handheld's bit depth at runtime:

MemHandle hRsc = DmGetResource(bitmapRsc, TestBitmapFamily);

BitmapType* bitmapP = (BitmapType*) MemHandleLock(hRsc);

WinDrawBitmap(bitmapP, topLeftCoordX, topLeftCoordY);

MemHandleUnlock(hRsc);

DmReleaseResource(hRsc);

To improve the performance of drawing the bitmap, you can call the "Get" and "Lock" functions well in advance to calling the "Draw" function. In addition, if you plan to reuse the same bitmap, you can call the "Unlock" and "Release" functions later in your code. For example, you could load and lock a number of bitmaps in an AppStart function, and then unlock and release them in an AppStop function.

# Compatibility Notes

Prior to Palm OS 3.5, the steps for adding a bitmap were similar, but you would simply add a black-and-white bitmap rather than a bitmap family. For Palm OS 3.5 and later, using a bitmap family allows Palm OS to select the right bit depth that is supported for the screen hardware. If your version of Constructor has no support for Bitmap Family resources, then you need to upgrade to the version of Constructor that comes with Palm OS 4.0 SDK. Note that when you create a bitmap family in Constructor, it will look like each bitmap has its own object ID. However, these object IDs are for use by Constructor; your code cannot access an individual member of a bitmap family.