ImagePrimitive
Represents a primitive element that renders images with comprehensive scaling, layout, transformation, and caching capabilities.
ImagePrimitive is a versatile rendering component in the Telerik WinControls framework that provides sophisticated image display functionality supporting both raster images (bitmap, PNG, JPEG, etc.) and vector images (SVG). It offers advanced features for image presentation including multiple scaling modes, layout options, rotation and flip transformations, transparency handling, and performance optimization.
Key capabilities include:
- Support for both Image and RadSvgImage content
- Multiple layout modes: Center, Stretch, Tile, Zoom, and None for flexible image positioning
- Advanced scaling options with DPI awareness and custom size specifications
- Image transformation support including rotation and flipping operations
- Integration with ImageList components for icon management and organization
- Transparency color handling and alpha channel support
- Performance optimization through intelligent caching and animated image support
The primitive is extensively used throughout Telerik controls in buttons, menu items, toolbars, tree nodes, and other UI elements requiring image display. It automatically handles image disposal and memory management to prevent resource leaks, while providing smooth animation support for animated image formats.
ImagePrimitive integrates seamlessly with the theming system, supporting property inheritance and style-based image assignment, making it ideal for creating consistent visual experiences across complex control hierarchies.
Definition
Namespace:Telerik.WinControls.Primitives
Assembly:Telerik.WinControls.dll
Syntax:
public class ImagePrimitive : BasePrimitive, IDisposable, INotifyPropertyChanged, ICustomTypeDescriptor, ISupportSystemSkin, IStylableNode, IPrimitive, IImageElement
Inheritance: objectDisposableObjectRadObjectRadElementVisualElementBasePrimitiveImagePrimitive...
Implements:
Inherited Members
Constructors
public ImagePrimitive()
Fields
Identifies the index used to resolve an image from the selected image list.
public static RadProperty ImageIndexProperty
Identifies the key used to resolve an image from the selected image list.
public static RadProperty ImageKeyProperty
Identifies the layout mode used to position or scale the image within the primitive.
public static RadProperty ImageLayoutProperty
Identifies the raster image property; changes can affect the image's display, measure, and layout.
public static RadProperty ImageProperty
Identifies whether the image uses its intrinsic size or the size specified by ScaleSize.
public static RadProperty ImageScalingProperty
Identifies the target image dimensions used when image scaling is set to SizeToFit.
public static RadProperty ScaleSizeProperty
Identifies the SVG image property; changes can affect the image's display, measure, and layout.
public static RadProperty SvgImageProperty
Identifies the color keyed to transparency when a cached raster image is created.
public static RadProperty TransparentColorProperty
Identifies whether image-list lookups use the small image list instead of the regular image list.
public static RadProperty UseSmallImageListProperty
Properties
Gets actual index.
[Browsable(false)]
public virtual int ActualIndex { get; }
Gets or sets the image that is displayed.
[TypeConverter(typeof(ImageTypeConverter))]
public Image Image { get; set; }
Implements:
Determines whether the Image or SvgImage property will be painted. Note that if SvgImage == null, this property will always return "ImageDrawType.Image".
[Browsable(false)]
public ImageDrawType ImageDrawType { get; set; }
Gets or sets the image list index value of the displayed image.
[RelatedImageList("ElementTree.Control.ImageList")]
public int ImageIndex { get; set; }
Implements:
Gets or sets the key accessor for the image in the ImageList.
[RelatedImageList("ElementTree.Control.ImageList")]
[TypeConverter("Telerik.WinControls.UI.Design.RadImageKeyConverter, Telerik.WinControls.UI.Design, Version=2026.3.1026.48, Culture=neutral, PublicKeyToken=5bb2a467cbec794e")]
public string ImageKey { get; set; }
Implements:
Gets or sets the way ImagePrimitive will layout its image on the screen.
public ImageLayout ImageLayout { get; set; }
Gets or sets image scaling. Possible values are members of ImageScaling enumeration: None and SizeToFit.
public ImageScaling ImageScaling { get; set; }
Gets a value indicating whether the primitive has content.
[Browsable(false)]
public override bool IsEmpty { get; }
Overrides:
Gets the Image that will be painted on the screen, with settings such as Opacity and Flip applied.
[Browsable(false)]
public Image RenderImage { get; }
Gets or sets the type of rotate/flip to be applied.
public RotateFlipType RotateFlipType { get; set; }
Gets or sets the desired size to use when SizeToFit scaling is active.
public Size ScaleSize { get; set; }
Gets or sets the flag controlling whether the image primitive fills up the available area horizontally
public override bool StretchHorizontally { get; set; }
Overrides:
Gets or sets the flag controlling whether the image primitive fills up the available area vertically
public override bool StretchVertically { get; set; }
Overrides:
Gets or sets the image that is displayed.
public RadSvgImage SvgImage { get; set; }
Gets or sets the transparent color for the image
[TypeConverter(typeof(RadColorEditorConverter))]
public Color TransparentColor { get; set; }
Specifies whether the image should be taken from the SmallImageList or from the ImageList when the ImageIndex/ImageKey property is set.
public bool UseSmallImageList { get; set; }
Methods
Releases cached image copies created by this primitive without disposing the supplied source images.
protected override void DisposeManagedResources()
Overrides:
Gets the property filter used when applying theme styles to this image primitive.
public override Filter GetStylablePropertiesFilter()
A filter containing the properties that can be styled for an image primitive.
Overrides:
Initializes image-rendering defaults and marks the image state for refresh.
protected override void InitializeFields()
Overrides:
Refreshes the image resolved from the containing element tree's image list when the primitive is loaded.
protected override void OnLoaded()
Overrides:
Synchronizes the resolved image and its cached rendering state when image-related properties change.
protected override void OnPropertyChanged(RadPropertyChangedEventArgs e)
The changed property and its old and new values.
Overrides:
Changing the image index or key resolves the corresponding image-list entry and clears the alternate selector. Changing the raster image clears both selectors and stops its animation; changing the SVG image rebuilds its cache. Opacity and transparent-color changes invalidate the image rendering state.
Updates image-list resolution and layout when the image list or parent changes in the routed event path.
protected override void OnTunnelEvent(RadElement sender, RoutedEventArgs args)
The element that raised the routed event.
argsRoutedEventArgsThe routed event data.
Overrides:
Refreshes image-list resolution after the primitive is removed from its element tree.
protected override void OnUnloaded(ComponentThemableElementTree oldTree)
The element tree from which the primitive was unloaded.
Overrides:
Determines when the SVG image representation is included in designer serialization.
public override bool? ShouldSerializeProperty(PropertyDescriptor property)
bool?
Overrides:
SvgImageXmlis serialized only when SvgImage is non-null and its value is locally assigned or supplied by a binding. Other properties use the base implementation.