Class ImagePrimitive

Represents a primitive element that renders images with comprehensive scaling, layout, transformation, and caching capabilities.

Inheritance
System.Object
DisposableObject
RadObject
RadElement
VisualElement
BasePrimitive
ImagePrimitive
Inherited Members
System.Object.Equals(System.Object)
System.Object.Equals(System.Object, System.Object)
System.Object.ReferenceEquals(System.Object, System.Object)
System.Object.GetHashCode()
System.Object.GetType()
System.Object.MemberwiseClone()
Namespace: Telerik.WinControls.Primitives
Assembly: Telerik.WinControls.dll

Syntax

public class ImagePrimitive : BasePrimitive, IDisposable, INotifyPropertyChanged, ICustomTypeDescriptor, ISupportSystemSkin, IStylableNode, IPrimitive, IImageElement
Remarks

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 System.Drawing.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.

Constructors

ImagePrimitive()

Declaration
public ImagePrimitive()

Fields

ImageIndexProperty

Declaration
public static RadProperty ImageIndexProperty
Field Value
RadProperty

ImageKeyProperty

Declaration
public static RadProperty ImageKeyProperty
Field Value
RadProperty

ImageLayoutProperty

Declaration
public static RadProperty ImageLayoutProperty
Field Value
RadProperty

ImageProperty

Declaration
public static RadProperty ImageProperty
Field Value
RadProperty

ImageScalingProperty

Declaration
public static RadProperty ImageScalingProperty
Field Value
RadProperty

ScaleSizeProperty

Declaration
public static RadProperty ScaleSizeProperty
Field Value
RadProperty

SvgImageProperty

Declaration
public static RadProperty SvgImageProperty
Field Value
RadProperty

TransparentColorProperty

Declaration
public static RadProperty TransparentColorProperty
Field Value
RadProperty

UseSmallImageListProperty

Declaration
public static RadProperty UseSmallImageListProperty
Field Value
RadProperty

Properties

ActualIndex

Gets actual index.

Declaration
public virtual int ActualIndex { get; }
Property Value
System.Int32

Image

Gets or sets the image that is displayed.

Declaration
[RadPropertyDefaultValue("Image", typeof(ImagePrimitive))]
public Image Image { get; set; }
Property Value
System.Drawing.Image

Implements

ImageDrawType

Determines whether the Image or SvgImage property will be painted. Note that if SvgImage == null, this property will always return "ImageDrawType.Image".

Declaration
public ImageDrawType ImageDrawType { get; set; }
Property Value
ImageDrawType

ImageIndex

Gets or sets the image list index value of the displayed image.

Declaration
[RadPropertyDefaultValue("ImageIndex", typeof(ImagePrimitive))]
public int ImageIndex { get; set; }
Property Value
System.Int32

Implements

ImageKey

Gets or sets the key accessor for the image in the ImageList.

Declaration
[RadPropertyDefaultValue("ImageKey", typeof(ImagePrimitive))]
public string ImageKey { get; set; }
Property Value
System.String

Implements

ImageLayout

Gets or sets the way ImagePrimitive will layout its image on the screen.

Declaration
public ImageLayout ImageLayout { get; set; }
Property Value
System.Windows.Forms.ImageLayout

ImageScaling

Gets or sets image scaling. Possible values are members of ImageScaling enumeration: None and SizeToFit.

Declaration
[RadPropertyDefaultValue("ImageScaling", typeof(ImagePrimitive))]
public ImageScaling ImageScaling { get; set; }
Property Value
ImageScaling

IsEmpty

Gets a value indicating whether the primitive has content.

Declaration
public override bool IsEmpty { get; }
Property Value
System.Boolean

Overrides

RenderImage

Gets the Image that will be painted on the screen, with settings such as Opacity and Flip applied.

Declaration
public Image RenderImage { get; }
Property Value
System.Drawing.Image

RotateFlipType

Gets or sets the type of rotate/flip to be applied.

Declaration
public RotateFlipType RotateFlipType { get; set; }
Property Value
System.Drawing.RotateFlipType

ScaleSize

Gets or sets the desired size to be used when displaying the image. Works when ImageScalingMode is set to FitToSize.

Declaration
public Size ScaleSize { get; set; }
Property Value
System.Drawing.Size

StretchHorizontally

Gets or sets the flag controlling whether the image primitive fills up the available area horizontally

Declaration
public override bool StretchHorizontally { get; set; }
Property Value
System.Boolean

Overrides

StretchVertically

Gets or sets the flag controlling whether the image primitive fills up the available area vertically

Declaration
public override bool StretchVertically { get; set; }
Property Value
System.Boolean

Overrides

SvgImage

Gets or sets the image that is displayed.

Declaration
[RadPropertyDefaultValue("SvgImage", typeof(ImagePrimitive))]
public RadSvgImage SvgImage { get; set; }
Property Value
RadSvgImage

SvgImageXml

Gets or sets the Svg Image as string.

Declaration
public string SvgImageXml { get; set; }
Property Value
System.String

TransparentColor

Gets or sets the transparent color for the image

Declaration
[RadPropertyDefaultValue("TransparentColor", typeof(ImagePrimitive))]
public Color TransparentColor { get; set; }
Property Value
System.Drawing.Color

UseSmallImageList

Specifies whether the image should be taken from the SmallImageList or from the ImageList when the ImageIndex/ImageKey property is set.

Declaration
[RadPropertyDefaultValue("UseSmallImageList", typeof(ImagePrimitive))]
public bool UseSmallImageList { get; set; }
Property Value
System.Boolean

Methods

DisposeManagedResources()

Declaration
protected override void DisposeManagedResources()
Overrides

GetStylablePropertiesFilter()

Declaration
public override Filter GetStylablePropertiesFilter()
Returns
Filter

Overrides

InitializeFields()

Declaration
protected override void InitializeFields()
Overrides

MeasureOverride(SizeF)

Declaration
protected override SizeF MeasureOverride(SizeF availableSize)
Parameters
System.Drawing.SizeF availableSize

Returns
System.Drawing.SizeF

Overrides

OnLoaded()

Declaration
protected override void OnLoaded()
Overrides

OnPropertyChanged(RadPropertyChangedEventArgs)

Declaration
protected override void OnPropertyChanged(RadPropertyChangedEventArgs e)
Parameters
RadPropertyChangedEventArgs e

Overrides

OnTunnelEvent(RadElement, RoutedEventArgs)

Declaration
protected override void OnTunnelEvent(RadElement sender, RoutedEventArgs args)
Parameters
RadElement sender

RoutedEventArgs args

Overrides

OnUnloaded(ComponentThemableElementTree)

Declaration
protected override void OnUnloaded(ComponentThemableElementTree oldTree)
Parameters
ComponentThemableElementTree oldTree

Overrides

PaintPrimitive(IGraphics, Single, SizeF)

Draws the primitive on the screen.

Declaration
public override void PaintPrimitive(IGraphics graphics, float angle, SizeF scale)
Parameters
IGraphics graphics

System.Single angle

System.Drawing.SizeF scale

Overrides

ShouldSerializeProperty(PropertyDescriptor)

Declaration
public override bool? ShouldSerializeProperty(PropertyDescriptor property)
Parameters
System.ComponentModel.PropertyDescriptor property

Returns
System.Nullable<System.Boolean>

Overrides

Extension Methods