Picture#

Qualified name: delphivcl.Picture

class Picture#

Bases: Persistent

TPicture contains a bitmap, icon, metafile graphic, or user-defined graphic. TPicture is a TGraphic container, used to hold a graphic, the type of which is specified in the Graphic property. It is used in place of a TGraphic if the graphic can be of any TGraphic class. LoadFromFile and SaveToFile are polymorphic. For example, if the TPicture is holding an Icon, it is valid to LoadFromFile a bitmap file, where the class TIcon can only read .ICO files. If the TPicture contains a bitmap graphic, the Bitmap property specifies the graphic. If the TPicture contains an icon graphic, the Icon property specifies the graphic. If the TPicture contains a metafile graphic, the Metafile property specifies the graphic. The properties of TPicture indicate the type of graphic that the picture object contains, and its size. The methods of TPicture are used to load, save, and manipulate graphics. To load or save a picture to the Clipboard, use the Assign method of a TClipboard object. To draw a picture on a canvas, call the Draw or StretchDraw methods of a TCanvas object, passing the Graphic property of a TPicture as a parameter.

Methods

`Assign`	Copies one object to another by copying the contents of that object to the other.
`Create`	Creates a TPicture object.
`Destroy`	Destroys an instance of a picture object.
`LoadFromClipboardFormat`	Reads the picture from the handle provided in the given Clipboard format.
`LoadFromFile`	Reads the file specified in Filename and loads the data into the TPicture object.
`LoadFromStream`	Reads the picture from a Stream.
`RegisterClipboardFormat`	Registers a new TGraphic class for use in the LoadFromClipboardFormat method.
`RegisterFileFormat`	Registers a new TGraphic class for use in LoadFromFile.
`RegisterFileFormatRes`	Registers a new TGraphic class for use in the LoadFromFile method.
`SaveToClipboardFormat`	Allocates a global handle and writes the picture in its native Clipboard format (CF_BITMAP for bitmaps, CF_METAFILE for metafiles, and so on).
`SaveToFile`	Writes the picture to disk.
`SaveToStream`	Saves the picture to a stream.
`SupportsClipboardFormat`	Indicates if the given Clipboard format is supported by the LoadFromClipboardFormat method.
`UnregisterGraphicClass`	Removes all references to the specified TGraphic class and all its descendants from the internal lists of file formats and clipboard formats.

Attributes

`Bitmap`	Specifies the contents of the picture object as a bitmap graphic (.BMP file format).
`ClassName`	Returns the TObject.ClassName
`Graphic`	Specifies the graphic that the picture contains.
`Height`	Specifies the vertical size (in pixels) of the graphic.
`Icon`	Specifies the contents of the TPicture object as an icon graphic (.ICO file format).
`Metafile`	Specifies the contents of the picture object as an Enhanced Windows metafile graphic (.EMF file format).
`OnChange`	<Delphi property OnChange of type TPicture at 211415E4000>
`OnFindGraphicClass`	<Delphi property OnFindGraphicClass of type TPicture at 211415E41A0>
`OnProgress`	<Delphi property OnProgress of type TPicture at 211415E40D0>
`PictureAdapter`	Represents an OLE interface for the picture.
`WICImage`	Embarcadero Technologies does not currently have any additional information.
`Width`	Specifies the horizontal size (in pixels) of the picture.

Assign(Source: Persistent)#: Copies one object to another by copying the contents of that object to the other. When Source is a object type that is valid for the Graphic property, Assign makes that graphic the value of the Graphic property. The actions performed by Assign depend on the actual types of the TPicture Graphic property and Source. For example, if the Graphic property and Source are bitmaps (TBitmap), the bitmap contained in Source is copied into the Graphic property. Similar conversions are valid, for example, for TIcon or TMetafile. If the Source parameter is not a valid object for the Graphic property, Assign calls the inherited method so that the picture can be copied from any object with which it is compatible.

Bitmap#

Specifies the contents of the picture object as a bitmap graphic (.BMP file format). Use Bitmap to reference the picture object when it contains a bitmap. If Bitmap is referenced when the picture contains a Metafile or Icon graphic, the graphic won’t be converted (Types of Graphic Objects). Instead, the original contents of the picture are discarded and Bitmap returns a new, blank bitmap.

Note: When assigning the Bitmap property, TPicture assigns the properties of a another TBitmap object. It does not take ownership of the specified value.

Create()#: Creates a TPicture object. Call Create to create an instance of TPicture at runtime. Create allocates the memory for the picture object and initializes its internal formats. After creating the TPicture object, use the LoadFromClipboardFormat or LoadFromFile method to assign a graphical image to the picture, so that it is available to the application.

Destroy()#: Destroys an instance of a picture object. Do not call Destroy directly in an application. Instead, call Free. Free verifies that the TPicture reference is not nil before it calls Destroy. Destroy frees the graphic image it contains before calling the inherited Destroy.

Graphic#

Specifies the graphic that the picture contains. Use Graphic to specify what graphic the TPicture object contains. The graphic can be a bitmap, icon, metafile, or user-defined graphic class (Types of Graphic Objects).

Note: When assigning the Graphic property, TPicture assigns the properties of a another TGraphic object. It does not take ownership of the specified object.

Height#: Specifies the vertical size (in pixels) of the graphic. Use Height to find the height of the graphic image contained in the picture object. Height is the native, unstretched, height of the picture.

Icon#

Specifies the contents of the TPicture object as an icon graphic (.ICO file format). If Icon is referenced when the TPicture contains a Bitmap or Metafile graphic, the graphic won’t be converted. Instead, the original contents of the TPicture are discarded and Icon returns a new, blank icon.

Note: When assigning the Icon property, TPicture assigns the properties of a another Icon object. It does not take ownership of the specified value.

LoadFromClipboardFormat(AFormat: Word, AData: NativeUInt, APalette: HPALETE)#

Reads the picture from the handle provided in the given Clipboard format. Use LoadFromClipboardFormat to read in a graphic from the Clipboard. If the format is not supported, an EInvalidGraphic exception is raised. The following code snippet shows how to load a picture from the clipboard into a TImage control.

Note: To load a picture into the clipboard, you can use the code snippet for the SaveToClipboardFormat method.

Delphi:

uses: Vcl.Clipbrd;

procedure TForm1.Button1Click(Sender: TObject); var

Picture: TPicture;

begin

Picture := TPicture.Create; try

Picture.LoadFromClipboardFormat(cf_BitMap, ClipBoard.GetAsHandle(cf_Bitmap), 0); Image1.Picture := Picture;

finally: Picture.Free; Clipboard.Clear;

end;

C++:

#include <Vcl.Clipbrd.hpp>

void __fastcall TForm1::Button1Click(TObject *Sender){

TPicture* Picture; TClipboard* cb = Clipboard();

Picture = new TPicture(); try{

Picture->LoadFromClipboardFormat(CF_BITMAP, cb->GetAsHandle(CF_BITMAP), 0); Image1->Picture = Picture;

} __finally{

delete Picture; cb->Clear();

}

LoadFromFile(Filename: string)#: Reads the file specified in Filename and loads the data into the TPicture object. Use LoadFromFile to read a picture from disk. The TGraphic class created is determined by the file extension of the file. If the file extension is not recognized an EInvalidGraphic exception is raised.

LoadFromStream(Stream: Stream)#: Reads the picture from a Stream. Use LoadFromStream to read a picture from a TStream object. The TGraphic class created is determined by the type of data contained in the stream. The data in the stream should be previously written by a call to the SaveToStream method of another TPicture or of a TGraphic descendant.

Metafile#

Specifies the contents of the picture object as an Enhanced Windows metafile graphic (.EMF file format). If Metafile is referenced when the TPicture contains a Bitmap or Icon graphic, the graphic won’t be converted. Instead, the original contents of the TPicture are discarded and Metafile returns a new, blank metafile (Types of Graphic Objects ).

Note: When assigning the Metafile property, TPicture assigns the properties of a another TMetafile object. It does not take ownership of the specified value.

OnChange#: <Delphi property OnChange of type TPicture at 211415E4000>

OnFindGraphicClass#: <Delphi property OnFindGraphicClass of type TPicture at 211415E41A0>

OnProgress#: <Delphi property OnProgress of type TPicture at 211415E40D0>

PictureAdapter#: Represents an OLE interface for the picture. PictureAdapter is for internal use only.

RegisterClipboardFormat(AFormat: Word, AGraphicClass: GraphicClass)#: Registers a new TGraphic class for use in the LoadFromClipboardFormat method. Use RegisterClipboardFormat register a new graphic format with TPicture so that it can be used with the LoadFromClipboardFormat method.

RegisterFileFormat(AExtension: string, ADescription: string, AGraphicClass: GraphicClass)#: Registers a new TGraphic class for use in LoadFromFile. Use RegisterFileFormat to register a graphic file format with TPicture so that it can be used with a Open or Save dialog box. The AExtension parameter specifies the three-character system file extension to associate with the graphic class (for example, “bmp” is associated with TBitmap). The ADescription parameter specifies the description of the graphic to appear in the drop down list of the dialog box (for example, “Bitmaps” is the description of TBitmap). The AGraphicClass parameter registers the new graphic class to associate with the file format.

RegisterFileFormatRes(AExtension: string, ADescriptionResID: Integer, AGraphicClass: GraphicClass)#: Registers a new TGraphic class for use in the LoadFromFile method. Use RegisterFileFormatRes by specifying a string resource. The AExtension parameter specifies the three-character system file extension to associate with the graphic class (for example, “bmp” is associated with TBitmap). The ADescriptionResID parameter specifies the resource ID for a description of the graphic, which then appears in the drop down list of the dialog box (for example, “Bitmaps” is the description of TBitmap). The AGraphicClass parameter registers the new graphic class to associate with the file format.

SaveToClipboardFormat(AFormat: Word, AData: NativeUInt, APalette: HPALETE)#

Allocates a global handle and writes the picture in its native Clipboard format (CF_BITMAP for bitmaps, CF_METAFILE for metafiles, and so on). Use SaveToClipboardFormat to copy the picture to a Clipboard format. The resulting values can then be copied to the Windows clipboard using the clipboard’s SetAsHandle method. The palette of the picture is returned in the APalette parameter, the format in the AFormat parameter, and a handle to the data in the AData parameter. Before the picture can be saved, an application must have registered the format using the RegisterClipboardFormat method. The following code snippet shows how to save a bitmap to the clipboard.

Note: To load a bitmap from the clipboard, you can use the code snippet for the LoadFromClipboardFormat method.

Delphi:

uses: Vcl.Clipbrd;

procedure TForm1.Button1Click(Sender: TObject); var

MyFormat : Word; Picture : TPicture; AData : THandle; APalette : HPALETTE;

begin

Picture := TPicture.Create; try

Picture.LoadFromFile(‘C:UsersPublicPicturesSample Picturesdesert.bmp’); Picture.SaveToClipBoardFormat(MyFormat, AData, APalette); ClipBoard.SetAsHandle(MyFormat,AData);

finally: Picture.Free;

end;

C++:

#include <Vcl.Clipbrd.hpp>

void __fastcall TForm1::Button1Click(TObject *Sender){

TClipboard* cb = Clipboard(); unsigned short MyFormat; TPicture* Picture; unsigned int AData; HPALETTE APalette;

Picture = new TPicture(); try{

Picture->LoadFromFile(“C:\Users\Public\Pictures\Sample Pictures\desert.bmp”); Picture->SaveToClipboardFormat(MyFormat, AData, APalette); cb->SetAsHandle(MyFormat, AData);

} __finally{

delete Picture;

}

SaveToFile(Filename: string)#: Writes the picture to disk. Use SaveToFile to save a TPicture object to the file specified in Filename. The saved picture can be loaded to another TPicture or to an appropriate TGraphic descendant by calling its LoadFromFile method.

SaveToStream(Stream: Stream)#: Saves the picture to a stream. Use SaveToStream to save a picture to the TStream object specified by the Stream parameter. The saved picture can be loaded to another TPicture or to an appropriate TGraphic descendant by calling its LoadFromStream method.

SupportsClipboardFormat(AFormat: Word) → Boolean#: Indicates if the given Clipboard format is supported by the LoadFromClipboardFormat method. If the LoadFromClipboardFormat method supports the Clipboard format specified as the value of AFormat, SupportsClipboardFormat returns true. If the format is not supported, the method returns false.

UnregisterGraphicClass(AClass: GraphicClass)#: Removes all references to the specified TGraphic class and all its descendants from the internal lists of file formats and clipboard formats. Call UnregisterGraphicClass to make a graphic class unavailable to all picture objects. UnregisterGraphicClass reverses the registration accomplished by the RegisterFileFormat, or RegisterFileFormatRes, or RegisterClipboardFormat method. When a graphic class is registered, the global GraphicFilter, GraphicExtension, and GraphicFileMask functions can return dialog filter strings, default file extensions or file filters for the graphic class. Call UnregisterGraphicClass when these values should not be available. For example, component writers who implement custom graphic classes unregister those classes according to the language used. In Delphi, the classes are unregistered in the finalization block of the unit that implements them and, in C++, the classes are unregistered using the #pragma exit directive (C++). File formats and clipboard formats for the custom class are registered in the initialization block (Delphi) or using #pragma startup (C++).

WICImage#: Embarcadero Technologies does not currently have any additional information.

Width#: Specifies the horizontal size (in pixels) of the picture. Use Width to find the width of a graphic image. Width contains the native, unstretched, width of the picture.