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, IImageElementInheritance: objectDisposableObjectRadObjectRadElementVisualElementBasePrimitiveImagePrimitive...
Implements:
Inherited Members
Constructors
public ImagePrimitive()Fields
public static RadProperty ImageIndexPropertypublic static RadProperty ImageKeyPropertypublic static RadProperty ImageLayoutPropertypublic static RadProperty ImagePropertypublic static RadProperty ImageScalingPropertypublic static RadProperty ScaleSizePropertypublic static RadProperty SvgImagePropertypublic static RadProperty TransparentColorPropertypublic static RadProperty UseSmallImageListPropertyProperties
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.1014.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 be used when displaying the image. Works when ImageScalingMode is set to FitToSize.
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 managed resources by clearing the property store and disposing value animators to prevent memory leaks.
protected override void DisposeManagedResources()Overrides:
Gets the IFilter instance that may be used to filter the properties, treated as Stylable for this element.
Initializes member fields to their default values. This method is called prior the CreateChildItems one and allows for initialization of members on which child elements depend.
protected override void InitializeFields()Overrides:
Measures the space required by the RadElement
Used by the layout system.
protected override SizeF MeasureOverride(SizeF availableSize)The size that is available to the RadElement. The available size can be infinity (to take the full size of the element)
Returns:The minimum size required by the element to be completely visible. Cannot be infinity.
Overrides:
In this method call to the Measure method of each child must be made.
Called when the element has been successfully loaded. That includes loading of all its children as well.
protected override void OnLoaded()Overrides:
Called when a property value has changed, allowing for custom response to property changes.
protected override void OnPropertyChanged(RadPropertyChangedEventArgs e)The property changed event arguments.
Overrides:
Called when the tunnel phase of a routed event occurs.
protected override void OnTunnelEvent(RadElement sender, RoutedEventArgs args)The element that originally raised the event.
argsRoutedEventArgsThe routed event arguments.
Overrides:
Notifies that the element has been successfully unloaded from an element tree. Allows inheritors to provide custom logic at this stage.
protected override void OnUnloaded(ComponentThemableElementTree oldTree)Reference to the element tree from which the element has been unloaded.
Overrides:
Determines whether the property defined by the provided property descriptor should be serialized.
public override bool? ShouldSerializeProperty(PropertyDescriptor property)bool?
Overrides: