TSVGIconImageList (FMX)

Unit: FMX.SVGIconImageList

Inherits from: TCustomImageList

Description

TSVGIconImageList is a FireMonkey (FMX) component that extends TCustomImageList to provide SVG icon support across all FMX platforms (Windows, macOS, iOS, Android). It automatically generates multi-resolution bitmaps from SVG sources, ensuring sharp icons at any scale factor.

The component uses a Source/Destination architecture where SVG icons are stored once in the Source collection and rendered on-demand at different sizes and scales in the Destination collection.

Properties

Size Configuration

Size: Integer

property Size: Integer read GetSize write SetSize default 32;

Uniform size for square icons (sets both Width and Height). Default: 32 pixels.

Example:

SVGIconImageList1.Size := 48; // Creates 48x48 icons

Width: Integer

property Width: Integer read GetWidth write SetWidth default 32;

Icon width in pixels. Default: 32.

Height: Integer

property Height: Integer read GetHeight write SetHeight default 32;

Icon height in pixels. Default: 32.

Zoom: Integer

property Zoom: Integer read FZoom write SetZoom default 100;

Zoom percentage for rendering (10-100). Default: 100.

Example:

SVGIconImageList1.Zoom := 90; // 90% of original size

Rendering Attributes

FixedColor: TAlphaColor

property FixedColor: TAlphaColor read FFixedColor write SetFixedColor default TAlphaColors.Null;

Override all colors in SVG with this fixed color. Use TAlphaColors.Null to preserve original colors.

Example:

// Apply fixed color
SVGIconImageList1.FixedColor := TAlphaColorRec.Blue;

// Restore original colors
SVGIconImageList1.FixedColor := TAlphaColors.Null;

ApplyFixedColorToRootOnly: Boolean

property ApplyFixedColorToRootOnly: Boolean read FApplyFixedColorToRootOnly write SetApplyFixedColorToRootOnly default False;

When True, applies FixedColor only to the root SVG element instead of all elements. Default: False.

GrayScale: Boolean

property GrayScale: Boolean read FGrayScale write SetGrayScale default False;

Renders all icons in grayscale. Perfect for disabled states. Default: False.

Example:

SVGIconImageList1.GrayScale := True; // All icons in grayscale

Opacity: Single

property Opacity: Single read FOpacity write SetOpacity;

Default opacity for all icons (0.0 = transparent, 1.0 = opaque). Default: 1.0.

Example:

SVGIconImageList1.Opacity := 0.5; // 50% transparent

Multi-Resolution

AutoSizeBitmaps: Boolean

property AutoSizeBitmaps: Boolean read FAutoSizeBitmaps write SetAutoSizeBitmaps default True;

When True (default), bitmaps are generated dynamically based on requesting control's size. When False, uses predefined scale factors (1x, 1.5x, 2x, 3x).

Example:

// Dynamic sizing (recommended)
SVGIconImageList1.AutoSizeBitmaps := True;

// Fixed scale factors
SVGIconImageList1.AutoSizeBitmaps := False;

Collections

Source: TSourceCollection

property Source;

Read-only collection of TSVGIconSourceItem objects containing the original SVG icons.

Destination: TDestinationCollection

property Destination;

Read-only collection of rendered bitmaps at various sizes and scales.

Events

OnChange: TNotifyEvent

property OnChange: TNotifyEvent;

Fired when the ImageList structure changes (icons added/removed).

OnChanged: TNotifyEvent

property OnChanged: TNotifyEvent;

Fired when icon properties change (colors, size, etc.).

Methods

Single Icon Operations

AddIcon

function AddIcon(const ASVGText: string; const AIconName: string = ''): TSVGIconSourceItem;

Adds a new SVG icon to the collection.

Parameters:

• ASVGText: SVG XML content as string
• AIconName: Optional name for the icon (auto-generated if empty)

Returns: The created TSVGIconSourceItem

Example:

var
  Icon: TSVGIconSourceItem;
begin
  Icon := SVGIconImageList1.AddIcon('<svg>...</svg>', 'home');
end;

InsertIcon

function InsertIcon(const AIndex: Integer; const ASVGText: string; const AIconName: string = ''): TSVGIconSourceItem;

Inserts an SVG icon at specific index.

Parameters:

• AIndex: Position to insert (0-based)
• ASVGText: SVG XML content
• AIconName: Optional icon name

Returns: The created TSVGIconSourceItem

CloneIcon

function CloneIcon(const AIndex: Integer; const AInsertIndex: Integer = -1): TSVGIconSourceItem;

Duplicates an existing icon.

Parameters:

• AIndex: Index of icon to clone
• AInsertIndex: Position for clone (-1 = append at end)

Returns: The cloned TSVGIconSourceItem

DeleteIcon

procedure DeleteIcon(const AIndex: Integer);

Removes an icon at specified index.

Example:

SVGIconImageList1.DeleteIcon(5); // Delete icon at index 5

GetIcon

function GetIcon(const AIndex: Integer): TSVGIconSourceItem;

Retrieves icon by index.

Returns: TSVGIconSourceItem or nil if index invalid

Example:

var
  Icon: TSVGIconSourceItem;
begin
  Icon := SVGIconImageList1.GetIcon(0);
  if Assigned(Icon) then
    Icon.FixedColor := TAlphaColorRec.Red;
end;

GetIconByName

function GetIconByName(const AName: string): TSVGIconSourceItem;

Retrieves icon by name.

Returns: TSVGIconSourceItem or nil if not found

Example:

var
  Icon: TSVGIconSourceItem;
begin
  Icon := SVGIconImageList1.GetIconByName('home');
  if Assigned(Icon) then
    ShowMessage(Icon.SVGText);
end;

Extraction Methods

ExtractSVG

function ExtractSVG(const AIndex: Integer): TFmxImageSVG;

Creates a new TFmxImageSVG instance from icon at index.

Returns: New TFmxImageSVG object (caller must free)

Example:

var
  SVG: TFmxImageSVG;
begin
  SVG := SVGIconImageList1.ExtractSVG(0);
  try
    SVG.PaintToBitmap(MyBitmap);
  finally
    SVG.Free;
  end;
end;

ExtractSVGByName

function ExtractSVGByName(const AName: string): TFmxImageSVG;

Creates a new TFmxImageSVG instance from named icon.

Returns: New TFmxImageSVG object or nil if not found

Multiple Icon Operations

LoadFromFiles

function LoadFromFiles(const AFileNames: TStrings; const AAppend: Boolean = True): Integer;

Loads multiple SVG files into the collection.

Parameters:

• AFileNames: List of SVG file paths
• AAppend: True to append, False to replace existing icons

Returns: Number of icons loaded

Example:

var
  Files: TStringList;
  Count: Integer;
begin
  Files := TStringList.Create;
  try
    TDirectory.GetFiles(IconPath, '*.svg', Files);
    Count := SVGIconImageList1.LoadFromFiles(Files);
    ShowMessage(Format('Loaded %d icons', [Count]));
  finally
    Files.Free;
  end;
end;

ClearIcons

procedure ClearIcons; virtual;

Removes all icons from the collection.

Example:

SVGIconImageList1.ClearIcons;

RefreshAllIcons

procedure RefreshAllIcons;

Regenerates all bitmaps. Call after changing global properties like FixedColor, GrayScale, or Size.

Example:

SVGIconImageList1.FixedColor := TAlphaColorRec.Blue;
SVGIconImageList1.GrayScale := True;
SVGIconImageList1.RefreshAllIcons; // Apply changes

UpdateIconAttributes

procedure UpdateIconAttributes(const ASize: Integer; const AOpacity: Single); overload;

Batch update size and opacity for all icons.

Parameters:

• ASize: New size for all icons
• AOpacity: New opacity (0.0-1.0)

Example:

SVGIconImageList1.UpdateIconAttributes(64, 0.8);

Usage Examples

Basic Setup

procedure TForm1.FormCreate(Sender: TObject);
begin
  // Configure ImageList
  SVGIconImageList1.Size := 32;
  SVGIconImageList1.FixedColor := TAlphaColorRec.Black;
  SVGIconImageList1.AutoSizeBitmaps := True;

  // Load icons
  SVGIconImageList1.AddIcon('<svg>...</svg>', 'home');
  SVGIconImageList1.LoadFromFiles(GetIconFiles);
end;

Use with ListView

procedure TForm1.SetupListView;
var
  Item: TListViewItem;
begin
  ListView1.ItemAppearance.ItemAppearance := 'ImageListItemRightButton';
  ListView1.Images := SVGIconImageList1;

  Item := ListView1.Items.Add;
  Item.Text := 'Home';
  Item.ImageIndex := 0;
end;

Use with Buttons

procedure TForm1.SetupButtons;
begin
  Button1.Images := SVGIconImageList1;
  Button1.ImageIndex := 0; // Uses icon at index 0
end;

Dynamic Icon Customization

procedure TForm1.CustomizeIcon(const AName: string; AColor: TAlphaColor);
var
  Icon: TSVGIconSourceItem;
begin
  Icon := SVGIconImageList1.GetIconByName(AName);
  if Assigned(Icon) then
  begin
    Icon.FixedColor := AColor;
    Icon.Opacity := 0.9;
    SVGIconImageList1.RefreshAllIcons;
  end;
end;

Theme Support

procedure TForm1.ApplyTheme(ADark: Boolean);
begin
  if ADark then
  begin
    SVGIconImageList1.FixedColor := TAlphaColorRec.White;
    Fill.Color := TAlphaColorRec.Black;
  end
  else
  begin
    SVGIconImageList1.FixedColor := TAlphaColorRec.Black;
    Fill.Color := TAlphaColorRec.White;
  end;
  SVGIconImageList1.RefreshAllIcons;
end;

Cross-Platform Icon Loading

procedure TForm1.LoadPlatformIcons;
var
  IconPath: string;
begin
  {$IFDEF MSWINDOWS}
  IconPath := 'C:\Icons\';
  {$ENDIF}
  {$IFDEF MACOS}
  IconPath := TPath.Combine(TPath.GetHomePath, 'Icons');
  {$ENDIF}
  {$IFDEF ANDROID}
  IconPath := TPath.Combine(TPath.GetDocumentsPath, 'icons');
  {$ENDIF}
  {$IFDEF IOS}
  IconPath := TPath.Combine(TPath.GetDocumentsPath, 'icons');
  {$ENDIF}

  SVGIconImageList1.LoadFromFiles(GetFilesInPath(IconPath));
end;

Platform Support

• ✅ Windows 32-bit and 64-bit
• ✅ macOS 32-bit and 64-bit (Intel and Apple Silicon)
• ✅ iOS Simulator and Device (32/64-bit)
• ✅ Android ARM 32-bit and 64-bit

See Also

• TSVGIconImage - Single image component
• TSVGIconSourceItem - Individual icon in collection
• TSVGIconMultiResBitmap - Multi-resolution bitmap manager
• TFmxImageSVG - Base SVG rendering class
• Overview (FMX) - FMX components overview
• Demo (FMX) - Demo applications