CaptureBitmap Method
The CaptureBitmap method captures a displayed region of a field, frame, or screen as a bitmap object, and optionally replaces the captured region with the image from a different bitmap.
If the specified region lies partly outside the window, the captured image will be truncated to what lies within the window.
If the BitmapObject is attached to a FormField or a stored TaggedValue Item, using this in your program during development may change your frame's source definition. See BitmapObject Attributes and Methods Affecting the Frame Source (see
BitmapObject Class).
This method has the following syntax:
BitmapObject = BitmapObject.CaptureBitmap(windowhandle = integer
[, xstart = integer][, ystart = integer][, width = integer]
[, height = integer][, replacement = BitmapObject][, clear = integer]
[, opacity = float])
This method has the following parameters:
windowhandle
(Required) Specifies the windowhandle (widgetid) of the field or frame, or if 0, specifies the whole screen.
Only fields that are active fields have a widgetid: to capture the appearance of a shape field on the display, capture the area of its parent composite field that contains the shape.
xstart
(Optional) Specifies the x-value of the first pixel in the region to be captured from the specified window, in pixels.
Default: 1
ystart
(Optional) Specifies the y-value of the first pixel in the region to be captured from the specified window, in pixels.
Default: 1
width
(Optional) Specifies the width of the region to be captured, in pixels. If width is not specified, this defaults to the remaining width (target width – xstart + 1).
height
(Optional) Specifies the height of the region to be captured, in pixels. If height is not specified, this defaults to the remaining width (target height – xstart + 1).
replacement
(Optional) Specifies the bitmap object whose image is to be applied to the captured region. If the size does not match the region, the image is resized to match.
clear
(Optional) Specifies whether the replacement contains transparent pixels (pixels that must be ignored when the replacement is applied to the display).
Default: FALSE
opacity
(Optional) Specifies the degree of opacity to use when applying the replacement.
Opacity is applied as a blend of the image with the background to which it is being applied, in the proportion specified by the opacity setting.
For example, if the opacity is set to 0.60, an image pixel that is colored as RGB(200,200,200), when applied to a background pixel colored RGB(100,100,100), results in a background pixel that is colored RGB(160,160,160).
Limits: 0.00–1.00.
Default: No opacity set. This is equivalent to opacity=1.00: the image pixels completely replace the background pixels.
This method returns a reference to the bitmap object, if successful (the BitmapObject itself is changed). If an error occurred, the bitmap object's errorstatus is set to a non-zero value, the return value is null, and the bitmap object is unchanged.
Example—CaptureBitmap method:
The following code captures the current screen display:
imageA.CaptureBitmap();
The following code captures the current frame's appearance:
imageA.CaptureBitmap(windowhandle=curframe.WidgetId);
The following code captures the appearance of a shape field on the display:
pixeldensity = float4(cursession.PixelScreenHeight)/float4(cursession.ScreenHeight));
shape = field(myshape);
shapewidth = shape.Width*pixeldensity;
imageA.CaptureBitmap(windowhandle=shape.ParentField.WidgetId,
xstart=shape.XLeft*pixeldensity,
ystart=shape.YTop*pixeldensity,
width=shape.OuterWidth*pixeldensity,
height=shape.OuterHeight*pixeldensity);
The following code applies a bitmap's image to a region of the specified field's display (the captured bitmap is ignored):
map = field(mymap);
discard = BitmapObject.Create();
discard.CaptureBitmap(windowhandle=map.WidgetId,
xstart=100, ystart=10, replacement=imageA);
The following code applies a bitmap's image to a region of the specified field's display, ignoring any transparent pixels, and displaying the image itself only faintly:
map = field(mymap);
discard = BitmapObject.Create();
discard.CaptureBitmap(windowhandle=map.WidgetId,
xstart=100, ystart=10, replacement=imageA, clear=TRUE, opacity=0.03);