Loading Bitmaps

In your program, you must load bitmap images (BMP, JPG, PNG, or TIFF) from disk into memory before they can be displayed as buttons. To load a bitmap, you must use the WBITMAP-LOAD operation of the W$BITMAP library routine. The call looks like this:

CALL "W$BITMAP" USING WBITMAP-LOAD, filename 
   GIVING bitmap-handle

where filename is a literal or data item that holds the name of the bitmap file to load, and bitmap-handle is a PIC 9(9) COMP-4 data item. This call opens the filename file, loads the bitmap into memory and closes the file. If the operation is successful, bitmap-handle will contain a positive value. If bitmap-handle is zero or negative, an error occurred. For a complete description of W$BITMAP including all error values returned by it, see W$BITMAP.

If you have multiple bitmap files, you need to load each before you can use the images they contain. Make certain to store the returned handles in different data items.

W$BITMAP searches for resources before it searches for disk files. For example, the tour.cbl sample program contains the following lines:

COPY RESOURCE "gtanima.bmp".

CALL "W$BITMAP" USING WBITMAP-LOAD, 
"gtanima.bmp" GIVING GT-BITMAP

The bitmap loaded is the resource specified in the COPY RESOURCE statement because the referenced file name is the same as the resource name. Replacing the COPY RESOURCE statement with

COPY RESOURCE "mybmps/gtanima.bmp"

produces the same results (assuming mybmps/gtanima.bmp existed at compile time) because resource names are not stored with directory information. Note that

CALL "W$BITMAP" USING WBITMAP-LOAD, 
"mybmps/gtanima.bmp"  . . .

also load the resource gtanima.bmp because W$BITMAP looks for a resource first, stripping directory information as part of the lookup. If no resource is found, W$BITMAP loads the file in the specified directory.

You can include JPEG, PNG or TIFF files as a resource in your COBOL programs with the COPY RESOURCE statement or by using cblutil, in exactly the same manner as BMP files. cblutil -info will identify these resources contained within an object library.

Note: A resource name with a hyphen (MY-FILE) is considered equivalent to the same resource name given with an underscore (MY_FILE).

When you are done with an image and have destroyed all the buttons that reference that image, you can remove it from memory with the WBITMAP-DESTROY operation. Do not destroy an image that is referenced by an existing button; the results are unpredictable.