vcl-dxgdiplusclasses-19309442.md
A universal container designed to store images in different formats.
TdxSmartImage = class(
TdxGPImage
)
The TdxSmartImage class is a TGraphic descendant that implements a universal image container in DevExpress products. An image container supports multiple formats and implements an extensive API for image import, export, conversion, and draw operations.
Note
Most DevExpress controls use TdxSmartGlyph[1] instances to manage and display UI element icons.
In this topic…
Add the dxGDIPlusClasses unit to the uses clause of your project (in Delphi) or include the dxGDIPlusClasses header to the required source code file (in C++Builder).
All supported formats are implemented as the following codec classes derived from the TdxSmartImageCodec class:
TdxGPImageCodecBMPA Device-Independent Bitmap (BMP/DIB) image format codec.TdxGPImageCodecGIFA Graphics Interchange Format (GIF) codec.TdxGPImageCodecJPEGA Joint Photographic Experts Group (JPEG) image format codec.TdxGPImageCodecPNGA Portable Network Graphics (PNG) image format codec.TdxGPImageCodecTIFFA Tagged Image File Format (TIFF) codec.TdxSVGImageCodecA Scalable Vector Graphics (SVG) image format codec.TdxGPImageCodecWMFA Windows Metafile (WMF) image format codec.
All image format implementations (except for SVG) available in DevExpress VCL products rely on the native image format encoder functionality of the Windows Imaging Component (WIC).
Tip
You can use the ImageCodec property to identify the current image format or convert the stored image to a different bitmap format.
The list below outlines key API members of the TdxSmartImage class that allow you to work with images.
This section contains TdxSmartImage class constructors and other methods that allow you to create image containers.
CloneCreates a new image container populated with a copy of the stored image.CreateSizeCreates an image container filled with a specific color.CreateFromBitmap | CreateFromHBitmap | CreateFromBits | CreateFromStreamCreate an image container and populate it from the specified source.GetAsBitmapCreates a TBitmap container and populates it with the stored image.
Assign | AssignFromGraphic | AssignFromSmartImageRepopulate the image container with an image from another image container.CopyToClipboard | CutToClipboard | PasteFromClipboardMove image data between the image container and the clipboard.GetBitmapBitsReturns the stored image as an array of pixel data.LoadFromBits | LoadFromFieldValue | LoadFromResource | LoadFromFile | LoadFromStreamRepopulate the image container from the specified source.SaveToStream | SaveToStreamByCodecSave the stored image to a stream.SaveToFileSaves the stored image to a file.
ClearClears the image container.ChangeColorFills all pixels of the stored image with a color.ConvertToBitmapRasterizes the stored vector image.CreateCanvas | StretchDrawDraw the stored image.DefaultImageExifAutoRotation
Specifies the default automatic image rotation setting based on EXIF metadata.
This class property defines the default EXIF image rotation for all image editors[2] and containers in the application.
Dormant | HandleNeededAllow you to suspend and restore the image container to optimize GDI resource usage.ExifAutoRotationAllows you to explicitly enable or disable automatic image rotation based on EXIF metadata.FlipFlips the stored image horizontally or vertically.ImageCodecSpecifies the format of the stored image. You can use this property to convert the stored image to any supported format, except for SVG.MakeCompositionThese overloaded functions blend two images from two image containers using the alpha channel.Resize | ScaleScale the source image.
ActiveFrameSpecifies the currently displayed frame in a multi-frame image.AnimationFrameCountReturns the number of frames in a multi-frame image.Animation | AnimationLoop | AnimationLoopCount | AnimationLoopIndex | StartAnimation | StopAnimationAllow you to track and manage animation playback for the stored animated image.
ClientRect | SizeReturn stored image dimensions.CompareCompares two image containers.GetHashCodeCalculates a CRC32 hash code from stored image data.IsAlphaUsedAllows you to identify if the stored image has transparent pixels.
The following code example allows users to select an image in any format and insert the image at the end of a document opened in a TdxRichEditControl:
uses
dxGDIPlusClasses, // Declares the TdxSmartImage class
dxSVGImage; // Declares the TdxSVGImageCodec class
//...
procedure TMyForm.cxButton1Click(Sender: TObject);
var
ADocument: IdxRichEditDocument;
AImageContainer: TdxSmartImage;
AFileName: string;
begin
ADocument := dxRichEditControl1.Document;
dxOpenPictureDialog1.Execute(Handle); // Invokes the "Open" dialog for image file selection
AFileName := dxOpenPictureDialog1.FileName;
if (AFileName = '') then Exit; // Exits the procedure if a user selects no image
AImageContainer := TdxSmartImage.Create; // Creates a Smart Image container
try
AImageContainer.LoadFromFile(AFileName);
if (AImageContainer.ImageCodec = TdxSVGImageCodec) then // If the container stores an SVG image
AImageContainer.ConvertToBitmap; // Rasterizes the vector image
ADocument.Images.Append(AImageContainer); // Creates a new inline image from the stored bitmap
finally
AImageContainer.Free; // Destroys the Smart Image container to prevent memory leaks
end;
end;
#include "dxGDIPlusClasses.hpp" // Declares the TdxSmartImage class
#include "dxSVGImage.hpp" // Declares the TdxSVGImageCodec class
//...
void __fastcall TMyForm::cxButton1Click(Sender: TObject)
{
_di_IdxRichEditDocument ADocument;
TdxSmartImage *AImageContainer;
UnicodeString AFileName;
// ...
ADocument = dxRichEditControl1->Document;
dxOpenPictureDialog1->Execute(Handle); // Invokes the "Open" dialog for image file selection
AFileName = dxOpenPictureDialog1->FileName;
if (AFileName == "") { return; } // Exits the routine if a user selects no image
AImageContainer = new TdxSmartImage(); // Creates a Smart Image container
try
{
AImageContainer->LoadFromFile(AFileName);
if (AImageContainer->ImageCodec == __classid(TdxSVGImageCodec)) // If the container stores an SVG image
AImageContainer->ConvertToBitmap(); // Rasterizes the vector image
ADocument->Images->Append(AImageContainer); // Creates a new inline image from the stored bitmap
}
__finally
{
delete AImageContainer; // Destroys the Smart Image container to prevent memory leaks
}
}
The following public API members reference a TdxSmartImage object:
TdxTileControlCustomStyle.TextureSpecifies a tile control element’s background image.TdxTileControlActionBarItem.GlyphSpecifies the action bar item’s image.
DevExpress products also include the following TdxSmartImage class descendants:
A DPI-aware image container that can load an image from a DFM file.
Most DevExpress controls use this image container to store, manage, and display UI element icons.
A bitmap image container that can store and manage inline and floating images in rich text documents.
Document management APIs in Rich Edit and Document Server components use this image container to work with images.
TObject TPersistent TInterfacedPersistent TGraphic TdxCustomSmartImage TdxGPImage TdxSmartImage
Footnotes
A TdxSmartImage class descendant.
The TcxImage editor supports EXIF image rotation when used as a standalone editor or as an in-place editor in Data Grid, Tree List, Vertical Grid, and Pivot Grid controls.
See Also