createPicture

createPicture(entireWindow:      Boolean;
              includeChildren:   Boolean;
              numberOfColorBits: Integer): Binary;

The createPicture method of the Window and Control class creates a bitmap for the receiver form or control, respectively.

Use the entireWindow parameter to specify that the created picture includes the non-client area of the form or control, the includeChildren parameter to specify that the created picture includes child controls (that is, controls that are placed on the form or control are included in the picture), and the numberOfColorBits parameter to specify the number of color bits for the picture. (The valid numbers of color bits that you can specify are 1, 4, 8, or 24.)

The createPicture method creates an image by drawing the window (and its children, if required) and replaying any drawing commands saved while the autoRedraw property is set to true. The process does not scrape the image off the screen.

The code fragments in the following examples show the use of the createPicture method.

setBackDrop(logo.createPicture(false, true, 24), 1, -1);

// create a picture and display the common File Save dialog to list all
// available Jpeg files for picture conversion
createPicture(true, true, 24).convertToFile("", Window.PictureType_Jpeg);

When you call this method for the Window class on an MDI frame that has MDI children, the frame and all of its children are included in the image. In addition, you can use this method to capture the entire image of a Form and its controls.

The created image is a reflection of how the window, which can include child windows, would be displayed. To recreate an image of a different size, set the image into a picture control with the stretch property set to Stretch_ToControl (1) and call createPicture(false, false, 24).

The createPicture method for Picture and JadeMask Web images attempts to preserve any image transparency where possible. This applies only if all of the following are true.

• The value of the entireWindow parameter of the createPicture method is false.

• The value of the includeChildren parameter of the createPicture method is false.

• This image type is BMP, PNG, JPEG, TIFF, or GIF.

• The control does not implement a paint event.

• For a JadeMask control, the value of the text property is null.

• Either the image size is the same size as the client areas of the control or the image is stretched to fit the control.

• If the image is stretched, the value of the transparentColor property of the control must be set to the default Black color (transparentColor is ignored if the image is the correct size and all of the above are true).

If all of the above are true and the image size is:

• The same size as the client area of the control, a copy of the original image is returned by the createPicture method.

• Stretched, the image is scaled to fit the control and it is returned as a PNG image, thus preserving any transparency effects.

If any of the above is false, the createPicture method constructs the required image by drawing all of the control components into a new image. This results in any transparency effects being lost.

See also the Control class createPictureIndirect method, which improves JADE thin client mode performance as it does not have to pass large binary large objects (blobs) back and forth between the presentation client and the application server.