This operation retrieves a bitmapped image from disk and displays it on the screen. This opcode takes four additional parameters:
| 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.
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). If BITMAP-HANDLE is less than or equal to zero, then an error has occurred.
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.