TdxSmartImage Class

A universal container designed to store images in different formats.

Declaration

TdxSmartImage = class(
    TdxGPImage
)

Remarks

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.

Most DevExpress controls use TdxSmartGlyph^[1] instances to manage and display UI element icons.

Supported Image Formats

All supported formats are implemented as the following codec classes derived from the TdxSmartImageCodec class:

TdxGPImageCodecBMP

A Device-Independent Bitmap (BMP/DIB) image format codec.

TdxGPImageCodecGIF

A Graphics Interchange Format (GIF) codec.

TdxGPImageCodecJPEG

A Joint Photographic Experts Group (JPEG) image format codec.

TdxGPImageCodecPNG

A Portable Network Graphics (PNG) image format codec.

TdxGPImageCodecTIFF

A Tagged Image File Format (TIFF) codec.

TdxSVGImageCodec

A Scalable Vector Graphics (SVG) image format codec.

TdxGPImageCodecWMF

A 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.

Main API Members

The list below outlines key API members of the TdxSmartImage class that allow you to work with images.

Image Container Creation

This section contains TdxSmartImage class constructors and other methods that allow you to create image containers.

Clone

Creates a new image container populated with a copy of the stored image.

CreateSize

Creates an image container filled with a specific color.

CreateFromBitmap | CreateFromHBitmap | CreateFromBits | CreateFromStream

Create an image container and populate it from the specified source.

GetAsBitmap

Creates a TBitmap container and populates it with the stored image.

Data Import and Export

Assign | AssignFromGraphic | AssignFromSmartImage

Repopulate the image container with an image from another image container.

CopyToClipboard | CutToClipboard | PasteFromClipboard

Move image data between the image container and the clipboard.

GetBitmapBits

Returns the stored image as an array of pixel data.

LoadFromBits | LoadFromFieldValue | LoadFromResource | LoadFromFile | LoadFromStream

Repopulate the image container from the specified source.

SaveToStream | SaveToStreamByCodec

Save the stored image to a stream.

SaveToFile

Saves the stored image to a file.

Content and Resource Management

Clear

Clears the image container.

ChangeColor

Fills all pixels of the stored image with a color.

ConvertToBitmap

Rasterizes the stored vector image.

CreateCanvas | StretchDraw

Draw 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 | HandleNeeded

Allow you to suspend and restore the image container to optimize GDI resource usage.

ExifAutoRotation

Allows you to explicitly enable or disable automatic image rotation based on EXIF metadata.

Flip

Flips the stored image horizontally or vertically.

ImageCodec

Specifies the format of the stored image. You can use this property to convert the stored image to any supported format, except for SVG.

MakeComposition

These overloaded functions blend two images from two image containers using the alpha channel.

Resize | Scale

Scale the source image.

Animation and Multi-Frame Image Settings

ActiveFrame

Specifies the currently displayed frame in a multi-frame image.

AnimationFrameCount

Returns the number of frames in a multi-frame image.

Animation | AnimationLoop | AnimationLoopCount | AnimationLoopIndex | StartAnimation | StopAnimation

Allow you to track and manage animation playback for the stored animated image.

General-Purpose API Members

ClientRect | Size

Return stored image dimensions.

Compare

Compares two image containers.

GetHashCode

Calculates a CRC32 hash code from stored image data.

IsAlphaUsed

Allows you to identify if the stored image has transparent pixels.

Code Example

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:

Delphi

uses
..., dxSVGImage;  // This unit contains the TdxSVGImageCodec class declaration
//...
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;

C++

#include "dxSVGImage.hpp"  // This header contains the TdxSVGImageCodec class declaration
//...
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
  }
}

Direct TdxSmartImage Class References

The following public API members reference a TdxSmartImage object:

TdxTileControlCustomStyle.Texture

Specifies a tile control element’s background image.

TdxTileControlActionBarItem.Glyph

Specifies the action bar item’s image.

Other Image Container Classes

DevExpress products also include the following TdxSmartImage class descendants:

TdxSmartGlyph

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.

TdxOfficeImage

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.

Inheritance

TObject

TPersistent

TInterfacedPersistent

TGraphic

TdxCustomSmartImage

TdxGPImage

TdxSmartImage

Footnotes

1. A TdxSmartGlyph class descendant.

2. 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.