WBITMAP-LOAD-PICTURE (op-code 10)

This operation accepts a filename and returns a handle to an IPictureDisp object. This is similar to the Visual Basic LoadPicture function. You must use the acuclass.def file to obtain the definition of the IPictureDisp object.

An IPictureDisp object uses the IPictureDisp interface to expose its properties through Automation. It provides a subset of the functionality available through IPicture methods. For more information, go to: msdn.microsoft.com/library and search for IPictureDisp and/or IPicture.

The following image formats are supported:

Bitmaps & device independent bitmaps (DIB)	.bmp
Graphics Interchange Format	.gif
Icons	.ico
Joint Photographic Experts Group (JPEG)	.jpg
Portable Network Graphic (PNG)	.png
Tagged Image File Format (TIFF)	.tif, .tff, or .tiff
Windows MetaFile	.wmf

This operation takes one parameter:

name

This required alphanumeric literal is the name of the file you want to load. The filename must include an absolute path. The length of name (including path) should not exceed 90 characters.

Note: If the operation is successful, bitmap-handle holds a positive value. If bitmap-handle is 0 or negative, an error occurred. Note that the runtime does not manage memory consumed by this function. When you are done with an image, you should remove it from memory with a DESTROY IPictureDisp_handle statement.

The IPictureDisp handle will not accept negative values. If an error (a negative value) is returned, you must use a REDEFINES, or move the value to a signed numeric variable, in order to read the error code. See Example 3 below.

Error Handling

If the value of BITMAP-HANDLE is 0 or negative, an error has occurred. These errors are defined in acugui.def.

WBERR-UNSUPPORTED (value 0): The system does not support bitmapped images. Currently, ACUCOBOL-GT supports bitmap display on Windows systems only.
WBERR-FILE-ERROR (value -1): 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-NO-MEMORY (value -2): The system ran out of memory trying to allocate space for the image.
WBERR-NOT-BITMAP (value -3): The named file does not contain a device-independent bitmap.
WBERR-FORMAT-UNSUPPORTED (value -4): The format of the current image is not supported.
WBERR-INVALID-HWND (value -6): The run time can not capture the current image. The window handle provided was invalid.
WBERR-INVALID-DATA (value -7): The run time can not access the bitmap object. This can happen if the window has been closed, or if the image is corrupt.
WBERR-INVALID-CLIPBOARD (value -8): The run time has been denied access to the clipboard. This may be because another application has locked the clipboard.
WBERR-INVALID-PALETTE (value -9): The run time is not able to create the palette for this image. The most common cause is that the image is corrupt or has an unsupported palette size.

Example 1

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 Example 3.

Notice the two calls to W$BITMAP in the sample code. First, W$BITMAP displays a logo, then uses 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 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 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. 
 
* Save the handle so it is available when needed 
* 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 
 
* Remove the bitmapped image and release the  
* memory it uses:  
 
call "w$bitmap" using wbitmap-destroy, bitmap-handle.

Example 2

Following are several examples of different W$BITMAP calls to capture screen shots and desktop images:

* This call captures the standard active window as a file  
* named "myfile.bmp" 
call "W$BITMAP" using WBITMAP-CAPTURE-IMAGE "myfile.bmp". 
 
* This call captures the standard active window onto  
* the Windows clipboard 
call "W$BITMAP" using WBITMAP-CAPTURE-IMAGE " ". 
 
* This call captures the client area of the active  
* window as a file named "myfile.bmp" using 8-bit color 
call "W$BITMAP"  
   using WBITMAP-CAPTURE-IMAGE "myfile.bmp" 0 1 8. 
 
* This call captures the indicated window handle using 16-bit 
* color and saves it as a file named "myfile.bmp" 
inquire mycontrol system handle in hWND 
call "W$BITMAP"  
   using WBITMAP-CAPTURE-IMAGE "myfile.bmp" hWND 0 16. 
 
* This call captures the entire desktop as a file named 
* "myfile.bmp" using 32-bit color 
call "W$BITMAP" using WBITMAP-CAPTURE-DESKTOP "myfile.bmp" 32. 
 
* This call captures the current bitmap content of the Windows 
* clipboard as a file named "myfile.bmp"  
call "W$BITMAP" using WBITMAP-CAPTURE-CLIPBOARD "myfile.bmp".

Example 3

The following sample program calls W$BITMAP to load an IPicture object.

       ... 
 
SPECIAL-NAMES. 
   COPY "acuclass.def". 
     . 
 
WORKING-STORAGE SECTION. 
   COPY "acugui.def". 
     77  myIPictureDisp     HANDLE OF IPictureDisp. 
     77  myErrorTest REDEFINES myIPictureDisp PIC S9(9) COMP-5. 
 
   ... 
PROCEDURE DIVISION. 
   MAIN-001. 
 
  CALL "W$BITMAP" USING WBITMAP-LOAD-PICTURE 
      "C:\MyDir\MyBitmaps.bmp" 
       GIVING myIPictureDisp. 
 
EVALUATE myErrorTest 
     WHEN WBERR-FILE-ERROR 
        DISPLAY MESSAGE BOX 
          "File not found" 
          TITLE "Error" 
          INITIALIZE myIPictureDisp 
     WHEN WBERR-FORMAT-UNSUPPORTED 
        DISPLAY MESSAGE BOX 
          "Format not supported" 
           TITLE "Error" 
           INITIALIZE myIPictureDisp 
     WHEN OTHER 
          DISPLAY MESSAGE BOX 
          "File successfully loaded" 
          TITLE "Success" 
END-EVALUATE. 
DESTROY myIPictureDisp. 
GOBACK.