TSVGIconImageList

Unit: SVGIconImageList

Inherits from: TSVGIconImageListBase → TDragImageList → TCustomImageList

Description

TSVGIconImageList is an extended ImageList component for Delphi/VCL that manages a collection of SVG icons. It replaces the standard TImageList with full SVG support, providing automatic scaling, DPI awareness, and advanced rendering features like opacity control, fixed colors, and grayscale effects.

The component stores SVG icons as XML text and renders them to bitmaps on demand, ensuring perfect quality at any resolution.

Published Properties

Size Control

Width

property Width: Integer;

Width of icons in pixels. Default: 16

Usage:

SVGIconImageList1.Width := 48;

Height

property Height: Integer;

Height of icons in pixels. Default: 16

Usage:

SVGIconImageList1.Height := 48;

Size

property Size: Integer;

Convenience property to set both Width and Height to the same value (square icons). Default: 16

Usage:

SVGIconImageList1.Size := 32;  // Sets both Width and Height to 32

Icon Collection

SVGIconItems

property SVGIconItems: TSVGIconItems;

Collection of SVG icon items. Each item contains an SVG image and associated properties.

Usage:

// Access items
var Item := SVGIconImageList1.SVGIconItems[0];

// Iterate
for var I := 0 to SVGIconImageList1.SVGIconItems.Count - 1 do
  ShowMessage(SVGIconImageList1.SVGIconItems[I].IconName);

See TSVGIconItems for details.

Appearance

Opacity

property Opacity: Byte;

Opacity level for all icons (0-255, where 255 is fully opaque). Default: 255

Usage:

SVGIconImageList1.Opacity := 200;  // 78% opaque
SVGIconImageList1.Opacity := 128;  // 50% opaque

Note: Individual icons can override this with their own Opacity setting.

FixedColor

property FixedColor: TColor;

Fixed color to apply to all SVG icons. Use SVG_INHERIT_COLOR (clDefault) to preserve original colors. Default: SVG_INHERIT_COLOR

Usage:

// Make all icons blue
SVGIconImageList1.FixedColor := clBlue;

// Make all icons match system window color
SVGIconImageList1.FixedColor := clWindowText;

// Restore original colors
SVGIconImageList1.FixedColor := SVG_INHERIT_COLOR;

Note: Individual icons can override this setting.

GrayScale

property GrayScale: Boolean;

Render all icons in grayscale. Default: False

Usage:

// Convert all icons to grayscale (disabled appearance)
SVGIconImageList1.GrayScale := True;

Note: Individual icons can override this setting.

AntiAliasColor

property AntiAliasColor: TColor;

Background color used for anti-aliasing when rendering icons to bitmaps. Default: clBtnFace

Usage:

// Use white background for anti-aliasing
SVGIconImageList1.AntiAliasColor := clWhite;

// Match form background
SVGIconImageList1.AntiAliasColor := Form1.Color;

Disabled State Rendering

DisabledGrayScale

property DisabledGrayScale: Boolean;

Automatically render disabled icons in grayscale. Default: True

Usage:

SVGIconImageList1.DisabledGrayScale := True;  // Disabled icons are gray
SVGIconImageList1.DisabledGrayScale := False; // Disabled icons keep colors

DisabledOpacity

property DisabledOpacity: Byte;

Opacity level for disabled icons (0-255). Default: 125

Usage:

SVGIconImageList1.DisabledOpacity := 100;  // More transparent
SVGIconImageList1.DisabledOpacity := 200;  // Less transparent

DPI Scaling

Scaled

property Scaled: Boolean;

Enable/disable automatic scaling with form DPI (when High-DPI support is enabled). Default: True

Usage:

SVGIconImageList1.Scaled := True;  // Auto-scale with DPI changes

When True, the component automatically adjusts icon sizes when:

• The form is displayed on a different DPI monitor
• Windows DPI settings change
• The application is moved between monitors with different DPIs

Events

OnChange

property OnChange: TNotifyEvent;

Event fired when the image list changes (icons added, removed, or properties changed).

Usage:

procedure TForm1.SVGIconImageList1Change(Sender: TObject);
begin
  StatusBar1.SimpleText := Format('Icons: %d', [SVGIconImageList1.Count]);
end;

Public Methods

Create

constructor Create(AOwner: TComponent);

Creates a new instance of TSVGIconImageList.

Destroy

destructor Destroy; override;

Destroys the instance and frees all resources.

Icon Management

Add

function Add(const ASVG: ISVG; const AIconName: string;
  const AGrayScale: Boolean = False;
  const AFixedColor: TColor = SVG_INHERIT_COLOR;
  const AAntiAliasColor: TColor = clBtnFace): Integer;

Adds a new SVG icon to the list and returns its index.

Parameters:

• ASVG: SVG interface to add
• AIconName: Name for the icon
• AGrayScale: Render this icon in grayscale
• AFixedColor: Fixed color for this icon
• AAntiAliasColor: Anti-alias background color

Returns: Index of the newly added icon

Usage:

var
  SVG: ISVG;
  Index: Integer;
begin
  SVG := GlobalSVGFactory.NewSvg;
  SVG.LoadFromFile('home.svg');
  Index := SVGIconImageList1.Add(SVG, 'home');
end;

Add (with category)

function Add(const ASVG: ISVG; const AIconName, AIconCategory: string;
  const AGrayScale: Boolean = False;
  const AFixedColor: TColor = SVG_INHERIT_COLOR;
  const AAntiAliasColor: TColor = clBtnFace): Integer;

Adds a new SVG icon with a category to the list.

Parameters:

• AIconCategory: Category for organizing icons (e.g., 'Navigation', 'Actions')

Usage:

Index := SVGIconImageList1.Add(SVG, 'home', 'Navigation');
// Icon will be named 'Navigation\home'

Delete

procedure Delete(const Index: Integer);

Deletes the icon at the specified index.

Usage:

SVGIconImageList1.Delete(0);  // Delete first icon

Remove

procedure Remove(const Name: string);

Removes the icon with the specified name.

Usage:

SVGIconImageList1.Remove('home');
SVGIconImageList1.Remove('Navigation\home');  // With category

ClearIcons

procedure ClearIcons;

Removes all icons from the list.

Usage:

SVGIconImageList1.ClearIcons;

File Operations

SaveToFile

procedure SaveToFile(const AFileName: string);

Saves all icons as a bitmap strip to the specified file.

Usage:

SVGIconImageList1.SaveToFile('icons.bmp');

Note: This saves the rendered bitmap strip, not the original SVG data. To save individual SVG icons, use the TSVGIconItem.SVGText property.

Rendering

PaintTo

procedure PaintTo(const ACanvas: TCanvas; const AIndex: Integer;
  const X, Y, AWidth, AHeight: Single; AEnabled: Boolean = True);

Paints the icon at the specified index to a canvas at given coordinates and size.

Parameters:

• ACanvas: Target canvas
• AIndex: Icon index
• X, Y: Position to paint
• AWidth, AHeight: Size to paint
• AEnabled: Whether to render as enabled or disabled

Usage:

// Paint icon to custom canvas
SVGIconImageList1.PaintTo(Canvas, 0, 10, 10, 64, 64, True);

RecreateBitmaps

procedure RecreateBitmaps;

Regenerates all bitmap representations from SVG sources. Call this after changing global rendering properties.

Usage:

SVGIconImageList1.FixedColor := clBlue;
SVGIconImageList1.RecreateBitmaps;  // Apply color to all icons

Note: Usually not needed as the component automatically updates when properties change.

Examples

Basic Usage

procedure TForm1.FormCreate(Sender: TObject);
begin
  // Configure image list
  SVGIconImageList1.Size := 32;
  SVGIconImageList1.FixedColor := clWindowText;

  // Load icons from files
  var Files := TStringList.Create;
  try
    Files.Add('icons\home.svg');
    Files.Add('icons\settings.svg');
    Files.Add('icons\exit.svg');
    SVGIconImageList1.LoadFromFiles(Files);
  finally
    Files.Free;
  end;

  // Use with toolbar
  ToolBar1.Images := SVGIconImageList1;
end;

Programmatic Icon Addition

procedure TForm1.AddCustomIcon;
var
  SVG: ISVG;
  SVGText: string;
begin
  SVGText := '<svg width="24" height="24" viewBox="0 0 24 24">' +
             '<path d="M10 20v-6h4v6h5v-8h3L12 3 2 12h3v8z"/>' +
             '</svg>';

  SVG := GlobalSVGFactory.NewSvg;
  SVG.Source := SVGText;

  SVGIconImageList1.Add(SVG, 'custom-home', 'Custom');
end;

Dynamic Resizing

procedure TForm1.TrackBar1Change(Sender: TObject);
begin
  // Dynamically resize all icons
  SVGIconImageList1.Size := TrackBar1.Position;
  // Icons are automatically re-rendered at new size
end;

Theming Support

procedure TForm1.ApplyDarkTheme;
begin
  if DarkThemeEnabled then
  begin
    SVGIconImageList1.FixedColor := clWhite;
    SVGIconImageList1.AntiAliasColor := clBlack;
  end
  else
  begin
    SVGIconImageList1.FixedColor := clBlack;
    SVGIconImageList1.AntiAliasColor := clWhite;
  end;

  SVGIconImageList1.RecreateBitmaps;
end;

High-DPI Aware Application

procedure TForm1.FormCreate(Sender: TObject);
begin
  // Enable automatic DPI scaling
  SVGIconImageList1.Scaled := True;

  // Icons will automatically scale when form DPI changes
  SVGIconImageList1.LoadFromFiles(IconFiles);
end;

// Handle manual DPI changes
procedure TForm1.FormAfterMonitorDpiChanged(Sender: TObject; OldDPI, NewDPI: Integer);
begin
  // Component handles this automatically when Scaled = True
  // No manual intervention needed
  StatusBar1.SimpleText := Format('DPI changed: %d → %d', [OldDPI, NewDPI]);
end;

Per-Icon Customization

procedure TForm1.CustomizeIcons;
var
  Item: TSVGIconItem;
begin
  // Make first icon red
  SVGIconImageList1.SVGIconItems[0].FixedColor := clRed;

  // Make second icon grayscale
  SVGIconImageList1.SVGIconItems[1].GrayScale := True;

  // Find and customize specific icon
  Item := SVGIconImageList1.SVGIconItems.GetIconByName('settings');
  if Assigned(Item) then
    Item.FixedColor := clBlue;
end;

See Also

• TSVGIconItems - Collection class
• TSVGIconItem - Individual icon class
• TSVGIconImage - Display component
• VCL Reference Overview
• Usage Guide (VCL)