W$BITMAP Routine

W$BITMAP is a collection of related routines that handle bitmapped (BMP and JPG) images. Only Windows machines can actually display bitmaps. On all other machines, this routine returns the WBERR-UNSUPPORTED status code (see below).

Usage

CALL "W$BITMAP"
   USING OP-CODE, parameters,
   GIVING BITMAP-HANDLE

Parameters

OP-CODE Numeric parameter

OP-CODE indicates the desired operation. The file "acugui.def" contains level 78 symbolic names for these operations.

OP-CODE parameters:

Vary depending on the OP-CODE chosen

BITMAP-HANDLE PIC S9(9)

BITMAP-HANDLE holds the return value of W$BITMAP. Values less than or equal to zero indicate errors. This is only used by the WBITMAP-DISPLAY op-code.

Comments

There are three operations available in W$BITMAP:

1. display a bitmapped image

2. remove a bitmapped image and free its memory

3. load a bitmapped image into memory

To use W$BITMAP, you pass an op-code as the first parameter, followed by one or more other parameters. The op-code determines which operation is performed and which parameters are required.

Currently, there are three op-codes: WBITMAP-DISPLAY (to display an image), WBITMAP-DESTROY (to remove an image and release its memory), and WBITMAP-LOAD (to load an image into memory--for use with bitmapped buttons).

When it is trying to locate a bitmap file, W$BITMAP will search first for a resource with the specified name, and then for a disk file. Resources are named in a fashion similar to disk files, but without any directory information. See the COPY RESOURCE statement in section 2.4.1 in Book 3, "Reference Manual" for more information about including resources.

W$BITMAP will examine files to determine the type of image format. If the file suffix is ".jpg", ".jpe" or ".jpeg", W$BITMAP assumes the file is a JPG image. Otherwise, it assumes the files are in BMP format. In order to read JPG files, you must have the file "VIC32.DLL" installed in the runtime directory. Only 32-bit runtimes support JPG format images.

W$BITMAP loads 24-bit color or 8-bit grayscale images in the JPEG File Interchange Format (JFIF). It reads baseline and extended DCT sequential and progressive files that are Huffman encoded (file types SOF0, SOF1, SOF2). The JPG lossless mode format is not supported.

The following example shows the first two op-codes in use. After the example, the parameters are described. For an example of the WBITMAP-LOAD operation, see section 3.8.2 in Book 2, "User Interface Programming."

Notice the two calls to W$BITMAP in the sample code. First we use W$BITMAP to display the Acucorp logo, and then we use the DISPLAY verb to place two lines of text on the screen. The second call to W$BITMAP removes the logo from the screen and releases the memory it occupies.

Displays the Acucorp logo for 2 seconds. display window, line 7, column 26, lines 9, size 30, color black + bckgrnd-white, erase, shadow, no scroll, pop-up area is window-1. * Now we give the name of the bitmap file and * the row and column of the upper left corner: call "w$bitmap" using wbitmap-display, "sample/acucob85.bmp", 2, 5. * We save the handle so we'll have it when we want * to remove the image: move return-code to bitmap-handle. * Check to make sure the logo file was found and * that no error occurred: if bitmap-handle <= zero close window window-1 else display "Copyright (c) 1985 - 2000", line 7, size 30, centered display "Acucorp, Inc.", line 8, size 30, centered accept single-char, auto, before time 200 end-if close window window-1 * We remove the bitmapped image and release the * memory it uses: call "w$bitmap" using wbitmap-destroy, bitmap-handle.

Note: The behavior of this library routine is affected by the setting of the FILENAME-SPACES configuration variable. See the documentation in Appendix H, Configuration File Entries, for information about the terminating character for path names.

WBITMAP-DISPLAY

The WBITMAP-DISPLAY operation retrieves a bitmapped image from disk and displays it on the screen. This op-code takes four additional parameters. They are, in order:

NAME This is an alphanumeric literal or data item that is the file name of the bitmap to display. This must be a file that contains a device-independent bitmap (usually called ".bmp" files). Create this file with a bitmap editor. For example, the bitmap contained in the sample program "tour.cbl" was created using the Paint program that comes with Windows. The file name is not interpreted--it should be the exact file name of the image.

ROW This is a numeric parameter. This value is the row where you want to place the upper-left corner of the image. Row values are treated just as they are in a DISPLAY statement. This means that row "1" is the top row of the current ACUCOBOL-GT window. You may also refer to fractional row positions. For example, row "1.5" is halfway between the top of row "1" and the top of row "2".

COLUMN This is a numeric parameter. This identifies the column where the upper-left corner of the image is to be placed. COLUMN is processed in the same manner as ROW.

FLAGS This is a numeric parameter that contains display options. Currently, the only option is WBITMAP-NO-FILL. When this is set, it inhibits the background-fill operation described below. This parameter can be omitted, in which case the fill option behaves as described.

The bitmapped image contained in the named file is loaded into memory, converted to a device-dependent bitmap and displayed at the position indicated by ROW and COLUMN. The entire image in the file is displayed, except that it is truncated to fit in the current ACUCOBOL-GT window.

Important: You should generally try to produce small bitmaps, because full-screen bitmaps occupy significant amounts of memory and can take noticeable time to process. If you use Windows Paint to create the image, you should first use the "Image Attributes" option to set the size of the image (the default is a full page; you'll want to make it smaller).

Frequently, the edges of the image will not exactly match a row and column boundary. ACUCOBOL-GT fills the tiny area between the edge of the bitmap and the next character cell with the current window's background color. If you use the WBITMAP-NO-FILL parameter, then the runtime leaves this area alone. Usually, this means that it will show arbitrary data as the program progresses. This can be useful, however, if you are placing several bitmaps very close together and do not want the fill area of one bitmap to overwrite another bitmapped image.

When W$BITMAP returns, it sets BITMAP-HANDLE to a positive (non-zero) value that is the bitmap's handle. This should be saved in a variable declared as PIC 9(9). Use the handle when you make future reference to the displayed image (for example, you need the handle in order to remove the bitmap and free the memory that it occupies).

Error Handling for WBITMAP-DISPLAY

If BITMAP-HANDLE is less than or equal to zero, then an error has occurred. The errors have symbolic names defined in "acugui.def". They are:

WBERR-UNSUPPORTED The system that you are running on does not support bitmapped images. Currently, ACUCOBOL-GT supports the display of bitmaps on Windows and Windows NT systems.

WBERR-FILE-ERROR A file error occurred when trying to open name. The most common cause is that name does not exist. Other possibilities include a permissions error or running out of file handles.

WBERR-MISSING-DLL The runtime has atttempted to load a ".jpg" file and the the file "VIC32.DLL" cannot be found.

WBERR-NO-MEMORY The system ran out of memory trying to allocate space for the image.

WBERR-NOT-BITMAP The named file does not contain a device-independent bitmap.

You may display data and pop-up windows over bitmapped images. However, the current implementation may cause the image to flash through the data displayed on top when the runtime is repainting the screen. The final image should be correct, but the flash can be annoying in some cases. To avoid this, either do not display anything over the image, or display over the entire image (the runtime will not try to display the image if it is entirely hidden).

The effect of displaying overlapping bitmapped images is undefined.

WBITMAP-DESTROY

The WBITMAP-DESTROY operation removes a bitmapped image from the screen and frees the memory used by that bitmap. It takes only one parameter: the handle of the bitmap returned by WBITMAP-DISPLAY. This should be either USAGE COMP-4 or unsigned DISPLAY.

Note that you can effectively remove an image from the screen by displaying over it. However, this does not free the memory used by the image. The runtime also spends some time whenever it updates the screen determining whether or not the image is visible. For these reasons, you should destroy images when you are done with them.

When an image is removed from the screen, it's replaced by spaces using the current window's background color. Only those parts of the screen that are currently showing the image are updated.

The runtime automatically destroys all remaining images when it shuts down.

WBITMAP-LOAD

The WBITMAP-LOAD operation loads bitmapped images from disk into memory so that they can be displayed with bitmapped buttons. This op-code takes two additional parameters. They are, in order:

filename A literal or data item containing the name of the file to load.

bitmap-handle A PIC S9(9) COMP-4 data item that stores a handle to the bitmapped image loaded into memory.

If the operation is successful, bitmap-handle holds a positive value. If bitmap-handle is "0" or negative, an error occurred.

If you have bitmapped images in more than one file, you need to load each file before using the images they contain. Be sure to store separate handles for each file loaded.

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, because the results are unpredictable.