VCL Components Reference - Overview

This section provides comprehensive API documentation for all VCL components in the SVGIconImageList library.

Components

The library provides four main VCL components for working with SVG icons:

Core Components

1. TSVGIconImageList - Extended ImageList component for SVG icons

   • Replaces standard TImageList with SVG support
   • Manages a collection of SVG icons (TSVGIconItems)
   • Provides automatic scaling and DPI awareness
   • Supports opacity, fixed colors, and grayscale effects

2. TSVGIconImage - Graphic control for displaying SVG images

   • Displays a single SVG image at any size
   • Can be linked to a TSVGIconImageList
   • Supports loading from files, streams, or text
   • Full control over rendering attributes

3. TSVGIconImageCollection - Collection component for storing SVG icons

   • Modern image collection (Delphi 10.3+)
   • Stores SVG icons without rendering
   • Can be shared by multiple virtual image lists
   • Part of Delphi's Virtual ImageList architecture

4. TSVGIconVirtualImageList - Virtual ImageList for SVG icons

   • References a TSVGIconImageCollection
   • Renders icons at specified sizes on demand
   • Multiple virtual lists can share one collection
   • Full VCL ImageList compatibility

Supporting Classes

• TSVGIconItem - Individual icon in a collection
• TSVGIconItems - Collection manager for TSVGIconItem objects
• TSVGGraphic - TGraphic descendant for TPicture support

Key Concepts

Icon Storage and Rendering

The library uses two main approaches for icon management:

Classic Approach (All Delphi versions):

• Use TSVGIconImageList which contains both storage (TSVGIconItems) and rendering
• Icons are stored as SVG XML text and rendered to bitmaps as needed
• Simple and self-contained, suitable for most applications

Modern Virtual Approach (Delphi 10.3+):

• Use TSVGIconImageCollection to store icons
• Use one or more TSVGIconVirtualImageList components to render icons at different sizes
• Efficient memory usage when same icons are needed at multiple sizes
• Follows Delphi's modern ImageCollection/VirtualImageList pattern

Rendering Attributes

All components support these rendering features:

• Size/Width/Height: Render icons at any resolution
• Opacity: Control transparency (0-255)
• FixedColor: Override SVG colors with a fixed color
• GrayScale: Render icons in grayscale
• AntiAliasColor: Background color for anti-aliasing
• ApplyFixedColorToRootOnly: Apply color only to root SVG element

DPI Awareness

Components automatically handle DPI scaling when:

• The Scaled property is True (default)
• The form has DPI awareness enabled
• Windows DPI changes occur

Icons are automatically re-rendered at the appropriate size for the current DPI.

Color System

The library uses special color constants:

• SVG_INHERIT_COLOR (clDefault): Use original SVG colors
• SVG_NONE_COLOR (clNone): No color override
• Any TColor value: Override SVG colors with the specified color

Icon Naming

Icons can be organized using categories:

// Simple name
IconName := 'home';

// With category (backslash separator)
IconName := 'Navigation\home';

// Extract parts
Category := Item.Category;  // Returns 'Navigation'
Name := Item.Name;          // Returns 'home'

Version Compatibility

Some features require specific Delphi versions:

Feature	Minimum Version	Notes
TSVGIconImageList	XE6	Core functionality
TSVGIconImageCollection	10.3 (Rio)	Part of VCL.BaseImageCollection
TSVGIconVirtualImageList	10.3 (Rio)	Part of Virtual ImageList framework
ImageName property	10.4 (Sydney)	Named image indexing
GetIndexByName / GetNameByIndex	10.4 (Sydney)	ImageList interface

Constants

const
  // Library version
  SVGIconImageListVersion = '4.5.3';

  // Default values
  DEFAULT_SIZE = 16;

  // Special colors
  SVG_INHERIT_COLOR = TColors.SysDefault;
  SVG_NONE_COLOR = TColors.SysNone;

Quick Start

Using TSVGIconImageList

// Create and configure
SVGIconImageList1.Size := 32;
SVGIconImageList1.FixedColor := clBlue;

// Add icons
SVGIconImageList1.Add(MySVG, 'icon1');
SVGIconImageList1.LoadFromFiles(FileList);

// Use with controls
Button1.ImageIndex := 0;
ListView1.SmallImages := SVGIconImageList1;

Using Virtual ImageLists (Delphi 10.3+)

// Setup collection (once)
SVGIconImageCollection1.LoadFromFiles(FileList);

// Create multiple virtual lists at different sizes
SmallImageList.Size := 16;
SmallImageList.ImageCollection := SVGIconImageCollection1;

LargeImageList.Size := 48;
LargeImageList.ImageCollection := SVGIconImageCollection1;

// Same icons, different sizes, shared storage
ListView1.SmallImages := SmallImageList;
ListView1.LargeImages := LargeImageList;

Using TSVGIconImage

// Display from file
SVGIconImage1.LoadFromFile('icon.svg');

// Display from ImageList
SVGIconImage1.ImageList := SVGIconImageList1;
SVGIconImage1.ImageIndex := 0;

// Display from text
SVGIconImage1.SVGText := '<svg>...</svg>';

// Control rendering
SVGIconImage1.FixedColor := clRed;
SVGIconImage1.GrayScale := True;
SVGIconImage1.Opacity := 200;

See Also

• VCL Components Overview
• Usage Guide (VCL)
• Component Editor (VCL)
• Choice of SVG Factories