SVG Image Support

• Nov 19, 2024
• 8 minutes to read

The DPI-adaptive UI requires that controls automatically scale their icons in response to DPI changes. Icons should use all available pixels to avoid blurriness. We recommend that you use only SVG images as UI element glyphs because an SVG image ensures crisp render at any target resolution.

DevExpress VCL Controls use the TcxImageList component and Smart Image/Smart Glyph containers to work with SVG images. These containers use the SVG Viewport dimensions as the base size to scale images.

SVG Images in the Icon Library

The Icon Library ships with categorized SVG icons you can find in the DevAV and SVG Images collections:

Supported SVG Elements and Attributes

The TdxSVGImageCodec class implements the Scalable Vector Graphics (SVG) image format in DevExpress products. This format implementation supports the following SVG elements and attributes:

Common SVG Attributes

C

class

The name of a CSS class defined in the CSS section of an SVG file.

I

id

An SVG element’s ID.

F

fill

An SVG element’s background color.

fill-rule

An additional rule that determines how the fill attribute affects a shape SVG element.

fill-opacity

An opacity of a color, pattern, or gradient used to fill a shape.

O

opacity

A floating-point value in the range between 0.0 (completely transparent) and 1.0 (opaque).

S

stroke

An SVG element’s outline.

stroke-dasharray

A pattern of dashes and gaps used to display paths and SVG element outlines.

stroke-dashoffset

An offset for the pattern that the stroke-dasharray attribute defines.

stroke-linecap

A shape (butt, round, or square) of outlines applied to end points of open lines and paths.

stroke-linejoin

A shape (arcs, bevel, miter, miter-clip, or round) of stroked path corners.

stroke-miterlimit

A limit on the ratio of the miter length and the stroke-width attribute value used to draw a miter join. If this limit is exceeded, the join is drawn as a bevel join rather than a miter join.

stroke-opacity

An opacity of a color, pattern, or gradient applied to a shape’s outline.

stroke-width

An SVG element’s outline color.

style

An SVG element’s style information. This attribute works identically to the style attribute in HTML. SVG images use CSS as a style sheet language.

T

transform

Defines a custom (user) coordinate system for the SVG engine. You can use the following commands specific to the transform attribute: matrix, rotate, scale, skewX, skewY, and translate.

SVG Elements and Element-Specific Attributes

C

circle

A circle based on a center point (cx and cy floating-point coordinates) and a radius (r). This element can include the shape-rendering attribute with the auto, optimizeSpeed, crispEdges, or geometricPrecision value.

clipPath

A clipping path. The clip-path attribute references a clipping path. The path can contain the following SVG elements: path, text, use, or a basic shape.

E

ellipse

An axis-aligned ellipse based on a center point (cx and cy) and two radiuses (rx and ry). This element can include the shape-rendering attribute with the auto, optimizeSpeed, crispEdges, or geometricPrecision value.

G

g

A container element designed to group SVG elements (with support for nested groups).

I

image

A custom bitmap inserted into an SVG image. This element supports the following bitmap-specific attributes: x, y, width, height, and href (xlink:href). The href attribute supports only inline bitmaps. The SVG engine ignores external bitmaps.

L

line

A line segment with the specified start (x1 and y1) and end (x2 and y2) points. This element can include the shape-rendering attribute with the auto, optimizeSpeed, crispEdges, or geometricPrecision value.

linearGradient

A linear gradient that fills a shape. DevExpress Smart Image containers support only four linear gradient directions in SVG images: horizontal, vertical, forward diagonal, and backward diagonal.

The SVG engine selects the most suitable supported vector direction when it displays an image with an unsupported gradient direction. This element supports the gradientTransform attribute.

P

path

A path that consists of custom straight and curved lines (including cubic and quadratic Bezier lines). This element can include the shape-rendering attribute with the auto, optimizeSpeed, crispEdges, or geometricPrecision value.

The path element accepts a path data command line as the d attribute. The DevExpress SVG engine supports the clip-rule attribute as well as all path data commands described in the SVG standard specification (v1.1).

pattern

A graphics object that can be redrawn at repeated x- and y-coordinate intervals (tiled) to cover an area. This object supports the following pattern-specific attributes: x, y, width, height, viewBox, patternUnits, and patternTransform.

polygon

A custom closed shape created from interconnected straight line segments. This element can include the shape-rendering attribute with the auto, optimizeSpeed, crispEdges, or geometricPrecision value.

The polygon element accepts a list of coordinates as the points attribute.

polyline

A set of connected straight line segments. This element can include the shape-rendering attribute with the auto, optimizeSpeed, crispEdges, or geometricPrecision value.

The polyline element accepts a list of coordinates as the points attribute.

R

radialGradient

A radial gradient used to fill a shape. This element supports the following attributes specific to radial gradients: cx, cy, r, fx, fy, fr, gradientTransform, and gradientUnits.

rect

An axis-aligned rectangle. This element can include the shape-rendering attribute with the auto, optimizeSpeed, crispEdges, or geometricPrecision value.

x, y, height, and width attribute values define the rectangle’s origin and dimensions; you can use optional rx and ry attributes to round the angles.

S

stop

A key point on a gradient direction vector. These points support the following attributes: offset, stop-color, and stop-opacity.

T

text

A text block within an SVG image. An SVG image can display text only within such text blocks. You can apply a supported linear gradient, pattern, or clipping path to text elements in an SVG image.

In addition to common attributes, the SVG engine supports the following attributes specific to the text element: x, y, dx, dy, font-family, font-size, font-weight, font-style, text-anchor, and text-decoration.

tspan

A text range within a text element or another tspan element. This SVG element allows you to apply different formatting to multiple ranges within the same text block.

In addition to common attributes, the current SVG engine version supports the following attributes specific to the tspan element: x, y, dx, and dy.

Note

Both text and tspan elements can include multiple X and Y coordinates that explicitly define individual glyph positions. If a glyph has no corresponding X or Y coordinate, the glyph position is calculated automatically based on the last glyph whose corresponding coordinate is defined explicitly.

U

use

Clones a referenced SVG element and places it at the specified position. The current SVG engine implementation supports only the following attributes that are specific to the use element: x, y, and href.

SVG Images, Skins, and Palettes

DevExpress controls can change their SVG icon colors based on the current skin and palette to maintain UI element contrast. All SVG icons shipped with the DevExpress Icon Library define the following named colors as CSS styles for fill and stroke attributes:

• Green
• Black
• Red
• Yellow
• Blue
• White

SVG Glyph and Palette Interaction Settings

The following global settings specify if SVG glyphs for UI elements interact with the active vector skin palette:

TdxVisualRefinements.UseDisabledSkinPaletteForSVG

Specifies if UI elements apply the active vector skin palette to disabled state glyphs at the application level.

TdxVisualRefinements.UseEnabledSkinPaletteForSVG

Specifies if UI elements apply the active vector skin palette to enabled state glyphs at the application level.

In addition, you can use the following properties to specify if individual SVG glyphs for UI elements interact with vector skin palettes:

TcxCustomImageList.UseDisabledSkinPaletteForSVG

Specifies if the active vector skin palette affects stored SVG glyphs for the disabled UI element state.

TcxCustomImageList.UseEnabledSkinPaletteForSVG

Specifies if the active vector skin palette affects stored SVG glyphs for the enabled UI element state.

TdxGPImage.UseDisabledSkinPaletteForSVG

Specifies if the active vector skin palette affects the stored SVG glyph for the disabled UI element state.

TdxGPImage.UseEnabledSkinPaletteForSVG

Specifies if the active vector skin palette affects the stored SVG glyph for the enabled UI element state.

Palette interaction settings of individual glyphs and image lists have higher priority than corresponding global settings.

CSS Example in DevExpress SVG Icons

XML

<?xml version="1.0" encoding="utf-8"?>
<svg version="1.1" id="Layer_1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" x="0px" y="0py"
viewbox="0 0 32 32" style="enable-background:new 0 0 32 32;" xml:space="preserve">
<style type="text/css">  <!-- CSS Style Classes -->
 .Green{fill:#039C23;}  <!-- The class name followed by the 'fill' attribute and the corresponding hexadecimal color code -->
 .Black{fill:#727272;}
 .Red{fill:#D11C1C;}
 .Yellow{fill:#FFB115;}
 .Blue{fill:#1177D7;}
 .White{fill:#FFFFFF;}
 .st0{opacity:0.5;}
 .st1{opacity:0.75;}
</style>  <!-- End of the CSS styles declaration -->
<g id="ChartBubble">  <!-- The SVG geometry section. -->
<!-- Each line defines a circle filled with the color declared in the CSS class -->
 <circle class="Yellow" cx="11" cy="21" r="7" />
 <circle class="Blue" cx="23" cy="11" r="5"/>
 <circle class="Green" cx="24" cy="22" r="2" />
 <circle class="Red" cx="12" cy="6" r="4" />
</g>  <!-- The end of the SVG geometry section. -->
</svg>

Third-Party SVG Icon Adaptation

To allow the DevExpress Skin Engine to update element colors in third-party SVG icons, these icons must define and use the same colors. For detailed information on how to use third-party icons together with DevExpress skins in your application, refer to the following topic: Third-Party SVG Icon Adaptation for DevExpress Skins and Palettes.

Limitations

The Office Image container in the Rich Edit control does not support SVG images to ensure compatibility with popular document formats.