Metafile#

Qualified name: delphivcl.Metafile

class Metafile#

Bases: Graphic

TMetafile is an encapsulation of the Win32 Enhanced metafile. TMetafile contains a metafile graphic (EMF file format). Properties of TMetafile indicate the size and characteristics of the metafile. To draw a metafile on a canvas, call the Draw or StretchDraw methods of a TCanvas object, passing a TMetafile as a parameter. The Enhanced property determines how the metafile will be stored on disk. If Enhanced is true, the metafile is stored as an .EMF (Win32 Enhanced Metafile) file. If Enhanced is false, the metafile is stored as a .WMF (Windows 3.1 Metafile, with Aldus header).

Methods

`Assign`	Copies an object to the metafile.
`CanLoadFromStream`	Vcl.Graphics.TMetafile.CanLoadFromStream inherits from Vcl.Graphics.TGraphic.CanLoadFromStream.
`Clear`	Deletes the metafile image.
`Create`	Instantiates a metafile object.
`Destroy`	Destroys an instance of a metafile object.
`HandleAllocated`	Indicates whether the TMetafile object has acquired a handle to the underlying GDI object.
`LoadFromClipboardFormat`	Loads a metafile from the Clipboard.
`LoadFromStream`	Loads the metafile from a stream.
`ReleaseHandle`	Releases the Windows GDI object represented by the metafile.
`SaveToClipboardFormat`	Saves a metafile to a Clipboard format.
`SaveToFile`	Writes the metafile to disk.
`SaveToStream`	Writes the metafile to a stream.
`SetSize`	Specifies the size of the metafile.

Attributes

`ClassName`	Returns the TObject.ClassName
`CreatedBy`	Specifies the name of the author or application used to create the metafile.
`Description`	Provides an optional text description that is embedded in the metafile.
`Empty`	Indicates whether the graphics object contains a graphic.
`Enhanced`	Determines how the metafile will be stored on disk.
`Handle`	Provides access to the Windows GDI metafile handle, for accessing the GDI metafile object.
`Height`	Specifies the vertical size of the graphic in pixels.
`Inch`	Returns the units per inch that are used for the metafile's coordinate mapping.
`MMHeight`	Contains the height of the metafile image in 0.01 millimeter units, the native scale used by enhanced metafiles.
`MMWidth`	Contains the width of the metafile image in 0.01 millimeter units, the native scale used by enhanced metafiles.
`Modified`	Indicates whether the graphics object has been changed or edited.
`OnChange`	<Delphi property OnChange of type TGraphic at 21141225010>
`OnProgress`	<Delphi property OnProgress of type TGraphic at 211412250E0>
`Palette`	Indicates the color palette of the graphical image.
`PaletteModified`	Indicates whether the palette has changed.
`ScaledDrawer`	Returns the reference to the scaled drawer.
`SupportsPartialTransparency`	Indicate whether graphic supports partial transparency or an alpha channel.
`Transparent`	Indicates whether the image covers its rectangular area.
`Width`	Determines the maximum width of the graphics object in pixels.

Assign(Source: Persistent)#: Copies an object to the metafile. Assign copies the Enhanced and Palette properties of an object to the metafile. If the metafile is nil (Delphi) or NULL (C++), Assign creates one. Otherwise, Assign calls the inherited method. For assignment, metafiles are polymorphic with other TGraphic objects, and with TPicture.

CanLoadFromStream(Stream: Stream) → Boolean#: Vcl.Graphics.TMetafile.CanLoadFromStream inherits from Vcl.Graphics.TGraphic.CanLoadFromStream. All content below this line refers to Vcl.Graphics.TGraphic.CanLoadFromStream. CanLoadFromStream returns True when a specified stream contains a streamed image of a specific TGraphic subclass. The method uses current stream position, it does not change current stream position.

Clear()#: Deletes the metafile image. Use Clear to release the old metafile image, create a new image, and increment a reference count on it.

Create()#: Instantiates a metafile object. Call Create to instantiate a metafile at runtime. Create allocates memory for a metafile object, and calls the inherited Create. Then sets the Enhanced and Transparent properties to true. To create a metafile image from scratch, draw the image in a metafile canvas. When the metafile canvas is destroyed, it transfers the image into the metafile object provided to the metafile canvas constructor. After the image is drawn on the canvas and the canvas is destroyed, the image is ‘playable’ in the metafile object.

CreatedBy#: Specifies the name of the author or application used to create the metafile. Use CreatedBy to set the string to an optional name of the author or application used to create the metafile. To set the CreatedBy string of a new metafile, call the TMetafileCanvas CreateWithComment constructor (Delphi) or the TMetafileCanvas constructor that takes a comment (C++).

Description#: Provides an optional text description that is embedded in the metafile. Set the Description string of a new metafile by calling the TMetafileCanvas CreateWithComment constructor (Delphi) or the TMetafileCanvas constructor that takes a comment (C++)..

Destroy()#: Destroys an instance of a metafile object. Do not call Destroy directly in an application. Instead, an application should call Free. Free verifies that the TMetafile reference is not nil before it calls Destroy. Destroy releases the image, which frees the image and the handle when the reference count on the metafile image is zero. Then Destroy calls the inherited Destroy.

Enhanced#: Determines how the metafile will be stored on disk. Use Enhanced to determine how the metafile is stored on disk. If Enhanced is True, the metafile is stored as an .EMF (Win32 Enhanced Metafile). If Enhanced is False, the metafile is stored as a .WMF (Windows 3.1 Metafile, with Aldus header). The in-memory format is always EMF. WMF has very limited capabilities; storing as WMF will lose information that would be retained by EMF. This property is set to match the metafile type when loaded from a stream or file. If loaded as WMF, then save as WMF. By default, the Enhanced property is True.

Handle#: Provides access to the Windows GDI metafile handle, for accessing the GDI metafile object. Use Handle when calling a Windows API function that requires the handle of a metafile object. Pass the handle from the Handle property of the metafile object to the function.

HandleAllocated()#: Indicates whether the TMetafile object has acquired a handle to the underlying GDI object. Use HandleAllocated to determine whether the Handle property is set to an HMETAFILE value. HandleAllocated indicates whether the underlying GDI object has already been created. Use HandleAllocated rather than reading the Handle property. When an application reads the Handle property, it automatically creates a metafile and returns its handle if the underlying GDI object does not already exist.

Inch#: Returns the units per inch that are used for the metafile’s coordinate mapping. Use Inch to find the units per inch assumed by a WMF metafile, and to alter scale when writing as WMF, but otherwise this property is obsolete. Enhanced metafiles maintain complete scale information internally. For example, if the metafile was created in a Twips coordinate system (using MM_TWIPS mapping), the value of Inch is 1440.

LoadFromClipboardFormat(AFormat: Word, AData: NativeUInt, APalette: HPALETE)#: Loads a metafile from the Clipboard. LoadFromClipboardFormat replaces the current image with the data in the clipboard. LoadFromClipboardFormat ignores the AData and APalette parameters.

LoadFromStream(Stream: Stream)#: Loads the metafile from a stream. Use LoadFromStream by specifying the stream from which the metafile is loaded as the value of Stream. LoadFromStream reads a metafile from a stream and replaces the current image with it.

MMHeight#: Contains the height of the metafile image in 0.01 millimeter units, the native scale used by enhanced metafiles. MMHeight is used for a more accurate reading of the vertical size of the graphic. The Height property, by contrast, is always in screen device pixel units; to avoid loss of precision in converting between device pixels and millimeters, set or read the dimensions in millimeters with MMHeight.

MMWidth#: Contains the width of the metafile image in 0.01 millimeter units, the native scale used by enhanced metafiles. MMWidth is used for a more accurate reading of the horizontal size of the graphic. The Width property, by contrast, is always in screen device pixel units; to avoid loss of precision in converting between device pixels and millimeters, set or read the dimensions in millimeters with MMWidth. The MMWidth property is always in screen device pixel units.

ReleaseHandle()#: Releases the Windows GDI object represented by the metafile. Call ReleaseHandle to release the resources used to represent the metafile. ReleaseHandle sets the Handle property to nil. NULL. Call ReleaseHandle before setting the Handle property, so that the resources associated with the metafile are not lost.

SaveToClipboardFormat(AFormat: Word, AData: NativeUInt, APalette: HPALETE)#: Saves a metafile to a Clipboard format. Use SaveToClipboardFormat to copy the metafile to a Clipboard format. The resulting values can then be copied to the Windows clipboard using the clipboard’s SetAsHandle method. The metafile’s palette is returned in the APalette parameter, the format in the AFormat parameter, and a handle to the data in the AData parameter. Before the metafile can be saved, an application must have registered the format with the metafile object using the RegisterClipboardFormat method. To save a metafile to a file, call SaveToFile.

SaveToFile(Filename: string)#: Writes the metafile to disk. Use SaveToFile to save the metafile to a file provided by the Filename parameter. To load a metafile from a file, call the LoadFromFile method.

Note: If the Filename parameter has an extension of “.wmf”, the metafile is saved as a WMF file. It is not necessary to set the Enhanced property.

SaveToStream(Stream: Stream)#: Writes the metafile to a stream. Use SaveToStream to save the metafile to the stream specified by the Stream parameter. If the Enhanced property is True, the metafile is saved as an EMF; if False, it it saved as a WMF.

SetSize(AWidth: Integer, AHeight: Integer)#: Specifies the size of the metafile. Use the SetSize method to set both the height and width of the metafile. This results in better performance than setting the height and width separately.