TCustomForm.GetFormImage

Gets the display content for the form as an image.

Declaration

Source position: forms.pp line 712

Function result

Bitmap created in the method with the image for the form.

Description

GetFormImage is an overloaded method used to capture the display content for the current form instance as an image type. The overloaded variants allow the image to be passed as a TCustomBitmap argument, or to create a TBitmap instance used as the return value.

The procedure variant includes the ABitmap argument with the bitmap instance where the image for the form is stored. It sets the size of the bitmap to the ClientWidth and ClientHeight for the form instance. The Handle for the form is used to get the display rectangle for its window, and it is drawn to the Canvas in the bitmap instance. This variant allows one of the other supported images formats (TCustomBitmap descendants like TJpegImage, TPortableNetworkGraphic, et. al.) to be passed in The ABitmap argument. ABitmap is allocated and freed in the calling routine.

For example:

procedure TForm1.Button1Click(Sender: TObject);
var
  jpg: TJpegImage;
begin
  jpg := TJpegImage.Create;
  try
    GetFormImage(jpg);
    Image1.Picture.Assign(jpg);
  finally
    jpg.Free;
  end;
end;

The function variant creates a new TBitmap instance which is used as the return value. It calls the overloaded variant to get the content in the TBitmap instance. The return value must be managed by the calling routine; the instance must be explicitly freed to avoid a memory leak. The return value can be Nil if an Exception was raised and handled in the method. This variant is compatible with the signature used in the Delphi VCL; the overloaded procedure leads to clearer code and avoids a potential memory leak.

For example:

procedure TForm1.Button1Click(Sender: TObject);
var
  bmp: TBitmap;
begin
  bmp := GetFormImage;
  try
    Image1.Picture.Assign(bmp);
  finally
    bmp.Free;
  end;
end;

Version info

Modified in LCL version 3.6 to include the overloaded variant which stores the image to an existing bitmap instance.

See also