Usage of the VCL Components

This guide demonstrates common usage patterns for the SVGIconImageList VCL components in your applications.

Getting Started

Choose Your Approach

For Delphi 10.3+ (Modern Approach): Use TSVGIconImageCollection + TSVGIconVirtualImageList for memory-efficient, centralized icon management.

For Delphi XE6-10.2 (Classic Approach): Use TSVGIconImageList for a simpler, self-contained solution.

For Individual Images: Use TSVGIconImage to display standalone SVG graphics (logos, illustrations, etc.).

Method 1: Using ImageCollection + VirtualImageList (Delphi 10.3+)

Step 1: Create the ImageCollection

1. Drop a TSVGIconImageCollection component onto a DataModule (recommended) or Form
2. Double-click to open the Component Editor
3. Click "Add" to load SVG files from disk
4. Alternatively, use "Add from WEB" to download icons from iconify.design
5. Organize icons with categories (optional): "Navigation\home", "Actions\save", etc.

Step 2: Create Virtual ImageLists

On each form that uses icons:

1. Drop TSVGIconVirtualImageList component(s)
2. Set ImageCollection property to your TSVGIconImageCollection
3. Set Size property (e.g., 16 for toolbar, 32 for buttons, 48 for large icons)
4. Configure appearance (FixedColor, GrayScale, Opacity)

Step 3: Link to Controls

Connect the VirtualImageList to VCL controls:

ToolBar1.Images := SVGIconVirtualImageListSmall;  // 16x16
ListView1.SmallImages := SVGIconVirtualImageListSmall;
ListView1.LargeImages := SVGIconVirtualImageListLarge;  // 48x48
ActionList1.Images := SVGIconVirtualImageListSmall;

Benefits of This Approach

• ✅ Memory Efficient: Icons stored once, rendered at multiple sizes
• ✅ Centralized Management: Update collection, all forms refresh
• ✅ Easy Theming: Change colors in one place
• ✅ Modern: Follows Delphi's recommended pattern

Method 2: Using TSVGIconImageList (All Delphi Versions)

Step 1: Add Component

1. Drop TSVGIconImageList onto Form or DataModule
2. Double-click to open the Component Editor
3. Load SVG files using "Add" button
4. Set Size property (e.g., 16, 24, 32)

Step 2: Use with Controls

ToolBar1.Images := SVGIconImageList1;
TreeView1.Images := SVGIconImageList1;
ActionList1.Images := SVGIconImageList1;

Benefits of This Approach

• ✅ Simple: One component, no dependencies
• ✅ Compatible: Works with Delphi XE6+
• ✅ Self-Contained: Storage and rendering in one place
• ❌ Less Efficient: Duplicate storage for multiple sizes

Method 3: Using TSVGIconImage for Single Images

Display Logos or Graphics

procedure TMainForm.FormCreate(Sender: TObject);
begin
  // Load company logo
  SVGIconImageLogo.LoadFromFile('logo.svg');
  SVGIconImageLogo.Proportional := True;
  SVGIconImageLogo.Center := True;

  // Or use ImageList
  SVGIconImageStatus.ImageList := SVGIconImageList1;
  SVGIconImageStatus.ImageIndex := GetStatusIcon;
end;

Common Usage Patterns

Pattern 1: Application-Wide Icon Management

DataModule Setup (dmIcons.pas):

type
  TdmIcons = class(TDataModule)
    SVGIconImageCollection: TSVGIconImageCollection;
    VirtualImageList16: TSVGIconVirtualImageList;
    VirtualImageList24: TSVGIconVirtualImageList;
    VirtualImageList32: TSVGIconVirtualImageList;
    procedure DataModuleCreate(Sender: TObject);
  end;

procedure TdmIcons.DataModuleCreate(Sender: TObject);
begin
  // Load all application icons once
  SVGIconImageCollection.LoadFromFiles(GetIconFiles);

  // Configure small icons (toolbar, menu)
  VirtualImageList16.ImageCollection := SVGIconImageCollection;
  VirtualImageList16.Size := 16;

  // Configure medium icons (TreeView)
  VirtualImageList24.ImageCollection := SVGIconImageCollection;
  VirtualImageList24.Size := 24;

  // Configure large icons (ListView, buttons)
  VirtualImageList32.ImageCollection := SVGIconImageCollection;
  VirtualImageList32.Size := 32;
end;

Usage in Forms:

procedure TMainForm.FormCreate(Sender: TObject);
begin
  ToolBar1.Images := dmIcons.VirtualImageList16;
  TreeView1.Images := dmIcons.VirtualImageList24;
  ListView1.LargeImages := dmIcons.VirtualImageList32;
  ActionList1.Images := dmIcons.VirtualImageList16;
end;

Pattern 2: Dynamic Icon Loading

procedure TMainForm.LoadIconsOnDemand;
var
  IconPath: string;
  Files: TStringList;
begin
  IconPath := TPath.Combine(ExtractFilePath(Application.ExeName), 'icons');

  Files := TStringList.Create;
  try
    // Collect SVG files
    TDirectory.GetFiles(IconPath, '*.svg', Files);

    // Load into collection
    SVGIconImageCollection.LoadFromFiles(Files);

    StatusBar1.SimpleText := Format('Loaded %d icons', [Files.Count]);
  finally
    Files.Free;
  end;
end;

Pattern 3: Runtime Icon Customization

procedure TMainForm.CustomizeIcons;
begin
  // Change specific icon
  var Item := SVGIconImageCollection.SVGIconItems.GetIconByName('warning');
  if Assigned(Item) then
  begin
    Item.FixedColor := clRed;
    Item.GrayScale := False;
  end;

  // Change all icons in a category
  for var I := 0 to SVGIconImageCollection.SVGIconItems.Count - 1 do
  begin
    Item := SVGIconImageCollection.SVGIconItems[I];
    if Item.Category = 'Navigation' then
      Item.FixedColor := clBlue;
  end;
end;

Pattern 4: Theme Support

type
  TTheme = (tmLight, tmDark);

procedure TMainForm.ApplyTheme(ATheme: TTheme);
begin
  case ATheme of
    tmLight:
      begin
        Color := clWhite;
        SVGIconImageCollection.FixedColor := clBlack;
        SVGIconImageCollection.AntiAliasColor := clWhite;
      end;
    tmDark:
      begin
        Color := $202020;
        SVGIconImageCollection.FixedColor := clWhite;
        SVGIconImageCollection.AntiAliasColor := $202020;
      end;
  end;

  // All virtual image lists automatically update
  Invalidate;
end;

Pattern 5: DPI-Aware Applications

type
  TMainForm = class(TForm)
    procedure FormAfterMonitorDpiChanged(Sender: TObject; OldDPI, NewDPI: Integer);
  end;

procedure TMainForm.FormAfterMonitorDpiChanged(Sender: TObject; OldDPI, NewDPI: Integer);
begin
  // Components with Scaled = True handle this automatically
  // Manual adjustments if needed:

  StatusBar1.SimpleText := Format('DPI changed: %d → %d', [OldDPI, NewDPI]);

  // Optional: Adjust icon sizes based on DPI
  if NewDPI >= 192 then  // 200% scaling
    VirtualImageList32.Size := 48
  else if NewDPI >= 144 then  // 150% scaling
    VirtualImageList32.Size := 36
  else
    VirtualImageList32.Size := 32;
end;

Pattern 6: ActionList Integration

procedure TMainForm.SetupActions;
begin
  // Link ActionList to ImageList
  ActionList1.Images := dmIcons.VirtualImageList16;

  // Actions automatically use icons
  actFileNew.ImageIndex := dmIcons.SVGIconImageCollection.IndexOf('new');
  actFileOpen.ImageIndex := dmIcons.SVGIconImageCollection.IndexOf('open');
  actFileSave.ImageIndex := dmIcons.SVGIconImageCollection.IndexOf('save');

  // Buttons, menus, etc. inherit from Actions
  ToolButton1.Action := actFileNew;  // Automatically shows icon
  MenuItem1.Action := actFileNew;    // Automatically shows icon
end;

Pattern 7: ListView with Icons

procedure TMainForm.PopulateListView;
var
  Item: TListItem;
begin
  ListView1.SmallImages := dmIcons.VirtualImageList16;
  ListView1.LargeImages := dmIcons.VirtualImageList32;
  ListView1.ViewStyle := vsReport;

  // Add items with icons
  Item := ListView1.Items.Add;
  Item.Caption := 'Document 1';
  Item.ImageIndex := dmIcons.SVGIconImageCollection.IndexOf('document');
  Item.SubItems.Add('Modified today');

  Item := ListView1.Items.Add;
  Item.Caption := 'Folder';
  Item.ImageIndex := dmIcons.SVGIconImageCollection.IndexOf('folder');
  Item.SubItems.Add('Contains 5 items');
end;

Pattern 8: TreeView with Icons

procedure TMainForm.BuildTreeView;
var
  Node: TTreeNode;
  FolderIdx, FileIdx: Integer;
begin
  TreeView1.Images := dmIcons.VirtualImageList24;

  FolderIdx := dmIcons.SVGIconImageCollection.IndexOf('folder');
  FileIdx := dmIcons.SVGIconImageCollection.IndexOf('file');

  // Add root node
  Node := TreeView1.Items.Add(nil, 'Root');
  Node.ImageIndex := FolderIdx;
  Node.SelectedIndex := FolderIdx;

  // Add child nodes
  var Child := TreeView1.Items.AddChild(Node, 'Document.txt');
  Child.ImageIndex := FileIdx;
  Child.SelectedIndex := FileIdx;
end;

Pattern 9: Disabled/Enabled States

procedure TMainForm.UpdateButtonStates(AEnabled: Boolean);
begin
  Button1.Enabled := AEnabled;

  // Icons automatically adjust:
  // - If DisabledGrayScale = True: shown in grayscale
  // - If DisabledOpacity < 255: shown with reduced opacity

  // Manual control:
  if AEnabled then
    SVGIconImage1.Opacity := 255
  else
    SVGIconImage1.Opacity := 125;
end;

Pattern 10: Loading from Resources

// Add to .rc file:
// HOME_ICON SVG "icons\home.svg"
// SAVE_ICON SVG "icons\save.svg"

procedure TMainForm.LoadIconsFromResources;
begin
  SVGIconImageCollection.LoadFromResource(HInstance, 'HOME_ICON', 'home');
  SVGIconImageCollection.LoadFromResource(HInstance, 'SAVE_ICON', 'save');

  // Icons are now embedded in executable, no external files needed
end;

Best Practices

1. Organize Icons with Categories

// Use backslash to create categories
SVGIconImageCollection.Add(Icon, 'home', 'Navigation');
SVGIconImageCollection.Add(Icon, 'save', 'Actions');
SVGIconImageCollection.Add(Icon, 'error', 'Status');

// Results in: Navigation\home, Actions\save, Status\error

2. Use Consistent Naming

// Good naming conventions:
'file-new', 'file-open', 'file-save'
'edit-cut', 'edit-copy', 'edit-paste'
'nav-home', 'nav-back', 'nav-forward'

3. Set AntiAliasColor Appropriately

// Match background for best rendering
Panel1.Color := clBlack;
VirtualImageList1.AntiAliasColor := clBlack;  // Not clBtnFace!

4. Use DataModules for Shared Icons

• Create a DataModule for application-wide icons
• Avoids duplication across forms
• Simplifies icon management
• Reduces memory usage

5. Handle Missing Icons Gracefully

function TMainForm.GetIconIndex(const AName: string): Integer;
begin
  Result := dmIcons.SVGIconImageCollection.IndexOf(AName);
  if Result < 0 then
  begin
    // Use default icon
    Result := dmIcons.SVGIconImageCollection.IndexOf('default');

    // Log warning
    if Result < 0 then
      raise Exception.CreateFmt('Icon not found: %s', [AName]);
  end;
end;

6. Preload Icons at Startup

procedure TMainForm.FormCreate(Sender: TObject);
begin
  // Show splash screen
  SplashScreen.Show;
  try
    // Load all icons
    dmIcons.LoadAllIcons;

    // Initialize UI
    SetupToolBar;
    SetupMenus;
  finally
    SplashScreen.Hide;
  end;
end;

Troubleshooting

Icons Appear Blurry

Problem: Icons look pixelated or blurry Solution:

// Ensure correct size
VirtualImageList1.Size := 32;  // Match control size

// Check DPI scaling
SVGIconImageList1.Scaled := True;

// Verify AntiAliasColor
VirtualImageList1.AntiAliasColor := Form1.Color;

Icons Not Updating

Problem: Changes to collection don't appear Solution:

// Force refresh
SVGIconImageList1.RecreateBitmaps;
// or
VirtualImageList1.Change;

Memory Usage High

Problem: Application uses too much memory Solution:

• Use ImageCollection + VirtualImageList instead of multiple ImageLists
• Clear unused icons: Collection.Delete(Index)
• Avoid loading unnecessarily large icon sets

Icons Wrong Color

Problem: Icons display incorrect colors Solution:

// Check FixedColor settings
Item.FixedColor := SVG_INHERIT_COLOR;  // Use original colors

// Or set desired color
Item.FixedColor := clWindowText;  // Match text color

See Also

• Component Overview: Overview (VCL)
• Complete API Reference: VCL Components Reference
• Component Editor: The Component Editor
• Virtual ImageList Guide: Virtual Image Collection
• Demo Projects: VCL Demos
• Advanced Topics: FAQ Advanced