GDI Plus Image Foundation Class

Article
07/09/2007

The gpImage class encapsulates a GDI+ image, and serves as the base class for specific image types (for example, the gpBitmap class).

Category	Reporting
Default Catalog	Visual FoxPro Catalog\Foundation Classes\Output\GDIplus
Class	gpImage
Base Class	Custom
Class Library	_GDIPLUS.vcx
Parent Class	gpObject (GDI Plus Object Foundation Class)

Remarks

The following table lists public properties and methods added by this class to its parent class, gpObject. This class also implements the Init and Clone methods.

Properties and methods Description

Clone Method

Clones an image object.

Syntax: THIS.Clone(toGpImage)

Return Values: Logical, representing success or failure.

Parameters:

toGpImage, required, the gpImage-based object to clone.

CreateFromFile Method

Creates an image object from a file.

Syntax: THIS.CreateFromFile(tcFileName [, tlUseEmbeddedColorMgmt])

Return Values: Logical, representing success or failure.

Parameters:

tcFileName, required, the image file from which to create the image object.

tlUseEmbeddedColorMgmt, optional, whether to use embedded color management.

Flags Property

Specifies attribute flags for this image as an integer computed as a combination of bit values, using the GDIPLUS_ImageFlags_* defined constants.

Default: Empty.

GetBounds Method

Gets a bounding rectangle in the specified units.

Syntax: THIS.GetBounds(tnUnits)

Return Values: an object of type gpRectangle, or null (.NULL.) on error.

Parameters:

tnUnits, required, specified according to the GDIPLUS_Unit_* set of constants.

GetDecoderCLSID Method

Gets the CLSID for the Decoder for a specific image format (for example, "image/jpeg").

Syntax: qCLSID = THIS.GetDecoderCSLID(tvSearchValue)

Return Values: Varbinary, CLSID of Decoder. Returns null (.NULL.) on error.

Parameters:

tvSearchValue, required. A string containing MIME type of image (eg "image/jpeg"), or a varbinary GUID of image format, as specified in GDIPLUS_IMAGEFORMAT_* constants.

Remarks: If no decoder is found for the specified image type, or if the image format MIME type or GUID supplied in tvSearchValue is invalid, then this function returns .NULL. and the GetStatus() method returns 0 ("no error").

GetEncoderCLSID Method

Gets the CLSID for the encoder for a specific image format (for example, "image/jpeg").

Syntax: qCLSID = THIS.GetEncoderCSLID(tvSearchValue)

Return Values: Varbinary, CLSID of encoder suitable for passing to SaveToFile() method. Returns null (.NULL.) on error.

Parameters:

tvSearchValue, required. A string containing MIME type of image (eg "image/jpeg"), or a varbinary GUID of image format, as specified in GDIPLUS_IMAGEFORMAT_* constants.

Remarks: If no encoder is found for the specified image type, or if the image format MIME type or GUID supplied in tvSearchValue is invalid, then this function returns .NULL. and the GetStatus() method returns 0 ("no error").

GetPropertyCount Method

Gets the number of properties stored in the metadata of this image object.

Syntax: nCount = THIS.GetPropertyCount()

Return Values: Integer, number of meta data properties (which could be zero). Returns null (.NULL.) on error.

Parameters: none.

GetPropertyIdList Method

Gets a list of all the properties stored in the image metadata, as a Visual FoxPro array.

Syntax: nCount = THIS.GetPropertyIdList(@raPropIDList)

Return Values: Integer, number of meta data properties (which could be zero). Returns null (.NULL.) on error. The property ID values are returned in the raPropIDList parameter array.

Parameters:

raPropIDList, required, array passed by reference. On return, this array is dimensioned to a 1-dimensional array, and each element of the array contains an integer property ID value.

GetPropertyItem Method

Retrieves the specified property from the image metadata.

Syntax: vPropertyValue = THIS.GetPropertyItem(tnPropID)

Returns:Property value, or null (.NULL.) if the property is not found or an error occurs. The data type depends on the property tag type, as follows:

Property types:	Returned in Visual FoxPro as:
byte, short, long, signed long	Numeric
String	ANSI string
rational, signed rational	String containing two numbers separated by a slash character. For example, one-third would be `"1/3"`.

Property types not shown here are not supported.

Parameters:

tnPropID, required, integer, a property item ID as returned by GetPropertyIDList.

Remarks: If the requested property is not defined, this method returns null (.NULL.) and the GetStatus() method returns 19 (GDIPLUS_STATUS_PropertyNotFound).

GetThumbnailImage Method

Gets a thumbnail image from the image object, returned as a new gpImage object.

Syntax: oImage= THIS.GetThumbnailImage(tnWidth, tnHeight)

Return Values:gpImage object containing a thumbnail. Returns null (.NULL.) if an error occurs.

Parameters:

tnWidth, integer, required, desired width of thumbnail in pixels.

tnHeight, integer, required, desired width of thumbnail in pixels.

Remarks: Some image files have a thumbnail image embedded in the file. In such cases, this method retrieves the embedded thumbnail image and the tnWidth and tnHeight parameter values are ignored. If there is no embedded thumbnail image, this method creates a thumbnail image by scaling the main image to the size specified in the tnWidth and tnHeight parameters. If both of those parameters are 0, a system-defined size is used.

HorizontalResolution Property

Numeric, horizontal resolution in pixels-per-inch. Read-only.

Default: none.

ImageHeight Property

Height of this Image object. Read-only.

Default: none.

ImageWidth Property

Width of this Image object. Read-only.

Default: none.

Init Method

Constructs an Image object during initialization if passed appropriate arguments.

Syntax: CREATEOBJECT("gpImage" [,tnHandle|tcFileName[, tlParam]])

Return Values: Logical, representing success or failure. If the method fails, the object does not instantiate.

Parameters:

tnHandle | tcFilename, required if immediate creation of the object is requested, a graphics handle or filename from which the image will be created.

tlParam, optional, indicates whether the class owns the graphics handle (if the first parameter is tnHandle) or whether color management should be used (if the first parameter is tcFileName).

PhysicalDimension Property

Provides the width and height of this image object, as an object of type gpSize. Read-only.

Default: none.

Remarks: If the image is a bitmap, the width and height are returned in pixels. If the image is a metafile, the width and height are returned in 0.01 millimeter units.

PixelFormat Property

Pixel format, according to the values specified in GP_PIXELFORMAT_* constants. Read-only.

Default: none.

Remarks: May not apply to some image objects, such as vector-format images.

RawFormat Property

Get the format of this image as a GUID of varbinary type. Read-only.

Default: none.

RotateFlip Method

Rotates and/or flips (mirrors) the image object.

Syntax: THIS.RotateFlip(tnRotateFlipType)

Return Values: Logical, representing success or failure.

Parameters:

tnRotateFlipType, required, integer. Specifies angle of rotation and/or type of flip, according to the values specified in the GDIPLUS_ROTATEFLIPTYPE_* defined constants.

SaveToFile Method

Saves the image object to a disk file, using specified encoder or image format and optional parameters.

Syntax: THIS.SaveToFile(tcFilename, tvCLSIDEncoder[, rvEncoderParams])

Return Values: Logical, representing success or failure.

Parameters:

tcFilename, required, string, the file name to which the image should be saved.

tvCLSIDEncoder, required, string or varbinary. The CLSID of the encoder to use, or a MIME type (eg "image/jpeg"). If a MIME type is specified, then the method dynamically looks up the CLSID of the appropriate Encoder.

rvEncoderParams, optional, parameters for the encoder. Either a comma-separated string in the form "param1=value1,param2=value2", or a two-column array (passed by reference) of encoder parameters and values.

Remarks: The encoder parameters are defined internally by globally unique IDs (GUIDS). This function understands a limited set of parameters by name:

Image type	Available parameters
JPEG	quality, transformation
TIFF	compression, colordepth, saveflag

To pass other parameters, use the array form of rvEncoderParams with the GUID of the parameter in the first column.

The following example saves an image to a JPEG file, using a quality of 80%.

lSuccess = oImage.SaveToFile( "example.jpg", ;
           "image/jpeg", "quality=80" )

VerticalResolution Property

Numeric, vertical resolution in pixels-per-inch. Read-only.

Default: none.

GDI Plus Image Foundation Class

Remarks

See Also

Reference

Concepts

Additional resources