WBITMAP-CAPTURE-IMAGE (op-code 7)

This operation captures a screen shot of a window, and stores it as an image file. All image types supported by the Microsoft CImage class are also supported by WBITMAP-CAPTURE-IMAGE.

Notes:
  • For a list of supported image types, see the Microsoft CImage class documentation.
  • If you are using this operation in a thin client environment, see Accessing Local Resource Files in the AcuConnect User's Guide for special considerations.

This operation takes four additional parameters:

name This required alphanumeric literal is the name of the file in which the image is saved.

The type of image saved depends on the file extension specified. For example, a file extension of .jpg saves the image as a JPEG file; a file extension of .png saves the image as a PNG file, etc.

The name may include embedded spaces.

This parameter is not affected by the FILE_PREFIX configuration variable.

If a file of the specified name already exists, it is overwritten unless it is read-only.

If this parameter is omitted or set to spaces, the image is saved to the Windows clipboard.

window-handle This optional PIC S9(9) COMP-4 data item is the Windows system handle of the image to capture.

If this parameter is omitted or set to 0, the currently active window is captured. (Active means the window that responds to a keystroke.)

If no window-handle is available or there is no currently active window, an image of the desktop is captured.

The Windows system handle is not the same as the Acucorp window handle. You may determine the value of window-handle using the following code:

   DISPLAY WINDOW HANDLE IN acu-handle.
or
   DISPLAY ENTRY-FIELD HANDLE IN acu-handle.
   INQUIRE acu-handle SYSTEM HANDLE IN window-handle.

where acu-handle is the handle of a window or control, and window-handle is a PIC 9(9) COMP-5 or PC X(4) COMP-N data item.

client This optional numeric data item is used to specify whether to capture the entire window, or just the interior of the window.

If you specify this parameter, you must also specify window-handle.

This parameter may have one of two values:

  • 0 - (default) The entire window is captured, including the title bar, window frame, menu, etc.
  • 1 - Only the interior of the window specified by window-handle is captured. This can be useful if you are displaying a scanned image, and want to capture only that image, not the window frame.
colordepth This optional numeric data item sets the number of color bits per pixel used when capturing the image.

If this value is not specified, the screen default is used.

The default color density of a screen is a property of the video adapter driver. On most modern PCs this is set to 24-bits per pixel.

This parameter is not used when images are saved to the clipboard.

This parameter may be set to one of the following values:
  • 1 - Monochrome
  • 4 - 4-bits per pixel
  • 8 - 8-bits per pixel (256 colors)
  • 16 - 16-bits per pixel
  • 24 - 24-bits per pixel (True color)
  • 32 - 32-bits per pixel (True color)

When making copies of all or part of the screen, do not use higher color density than necessary. Color is memory intensive and a higher color density does not improve image quality as much as it results in a larger file size. Consider what you will use the image for and set colordepth accordingly. Many tools do not support bitmaps with more than 256 colors. A color density setting of 8 is adequate for most situations.