Class VisualElement

Extends RadElement with visual properties and rendering capabilities common to all visual elements.

Inheritance
System.Object
DisposableObject
RadObject
RadElement
VisualElement
BasePrimitive
RadComponentElement
UIElement
UIElement
CarouselContentItem
UIElement
TextBlockElement
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
Assembly: Telerik.WinControls.dll

Syntax

public class VisualElement : RadElement, IDisposable, INotifyPropertyChanged, ICustomTypeDescriptor, ISupportSystemSkin, IStylableNode
Remarks

VisualElement serves as the base class for all visually rendered elements in the Telerik WinControls framework. It provides fundamental visual properties such as colors, fonts, opacity, smoothing modes, and other rendering attributes that affect how elements appear on screen.

This class implements the core visual property system, including property inheritance, layout effects, and painting infrastructure. It defines how elements interact with themes, handle DPI scaling, and manage visual states during runtime.

VisualElement is the foundation for all primitive elements, layout panels, and composite controls in the Telerik framework, providing consistent visual behavior and styling capabilities.

Constructors

VisualElement()

Declaration
public VisualElement()

Fields

BackColorProperty

Identifies the BackColor dependency property. This property represents the background color used for filling the element.

Declaration
public static RadProperty BackColorProperty
Field Value
RadProperty

Remarks

This is an attached property that can be inherited through the element tree. Changes to this property will trigger display updates.

CustomFontProperty

Identifies the CustomFont dependency property. This property specifies the name of a custom font to use.

Declaration
public static RadProperty CustomFontProperty
Field Value
RadProperty

Remarks

The default value is "None", which means no custom font is used. When set to a valid font name, it overrides the standard Font property.

CustomFontSizeProperty

Identifies the CustomFontSize dependency property. This property specifies the size of the custom font.

Declaration
public static RadProperty CustomFontSizeProperty
Field Value
RadProperty

Remarks

The default value is 12.0f. This property is used in conjunction with CustomFont.

CustomFontStyleProperty

Identifies the CustomFontStyle dependency property. This property specifies the style of the custom font.

Declaration
public static RadProperty CustomFontStyleProperty
Field Value
RadProperty

Remarks

The default value is FontStyle.Regular. This property is used in conjunction with CustomFont.

DefaultSizeProperty

Identifies the DefaultSize dependency property. This property represents the default size of a VisualElement. When set, this property affects display, parent arrangement, and measurement calculations.

Declaration
public static RadProperty DefaultSizeProperty
Field Value
RadProperty

Remarks

This is an attached property that can be applied to any VisualElement. The default value is Size.Empty. When changed, it will trigger layout recalculation because it has the AffectsDisplay, AffectsParentArrange, and AffectsMeasure property options.

FontProperty

Identifies the Font dependency property. This property represents the font used for rendering text.

Declaration
public static RadProperty FontProperty
Field Value
RadProperty

Remarks

This property has significant impact on layout and display. Changes to this property will trigger measurement, layout recalculation, and display updates. It can be inherited from parent elements.

ForeColorProperty

Identifies the ForeColor dependency property. This property represents the foreground color used for rendering text and borders.

Declaration
public static RadProperty ForeColorProperty
Field Value
RadProperty

Remarks

This property can inherit its value from parent elements and affects the display of the element when changed.

OpacityProperty

Identifies the Opacity dependency property. This property determines the transparency level of the element.

Declaration
public static RadProperty OpacityProperty
Field Value
RadProperty

Remarks

The value ranges from 0.0 (completely transparent) to 1.0 (completely opaque). Changes to this property affect how the element and its children are displayed.

SmoothingModeProperty

Identifies the SmoothingMode dependency property. This property determines how graphics are smoothed when rendered.

Declaration
public static RadProperty SmoothingModeProperty
Field Value
RadProperty

Remarks

Changes to this property affect the visual quality of rendered graphics. The default value is SmoothingMode.Default.

Properties

BackColor

Gets or sets the background color of the element.

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

A System.Drawing.Color that represents the background color of the element. The default value is determined by the current theme.
Remarks

This property is inheritable through the element tree, allowing child elements to inherit the background color from their parents unless explicitly overridden.

CustomFont

Gets or sets the name of the custom font to be used for rendering text in this element.

Declaration
[VsbBrowsable(true)]
[RadPropertyDefaultValue("CustomFont", typeof(VisualElement))]
public virtual string CustomFont { get; set; }
Property Value
System.String

Remarks

This property works in conjunction with CustomFontSize and CustomFontStyle to define a custom font. Setting this property to a font name other than "None" will override the Font property. Available values include standard fonts like "Roboto" and icon fonts like "Telerik Web UI" and "Font Awesome".

CustomFontSize

Gets or sets the size of the custom font in points.

Declaration
[VsbBrowsable(true)]
[RadPropertyDefaultValue("CustomFontSize", typeof(VisualElement))]
public virtual float CustomFontSize { get; set; }
Property Value
System.Single

Remarks

This property is used when CustomFont is set to a value other than "None". The default size is 12 points.

CustomFontStyle

Gets or sets the style for the custom font.

Declaration
[VsbBrowsable(true)]
[RadPropertyDefaultValue("CustomFontStyle", typeof(VisualElement))]
public virtual FontStyle CustomFontStyle { get; set; }
Property Value
System.Drawing.FontStyle

Remarks

This property is used when CustomFont is set to a value other than "None". The default style is Regular, but can be set to other FontStyle values like Bold, Italic, etc.

DefaultSize

Gets or sets the default size for the visual element.

Declaration
[RadPropertyDefaultValue("DefaultSize", typeof(VisualElement))]
public virtual Size DefaultSize { get; set; }
Property Value
System.Drawing.Size

Remarks

The default size is used as the preferred size when measuring and arranging elements. This property is inheritable through the element tree and affects layout calculations.

Font

Gets or sets the font used for rendering text in this element.

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

A Font object that defines the text format including font face, size, and style attributes. The default value is determined by the current theme or system default font.
Remarks

This property is inheritable through the element tree and has significant impact on layout calculations. Setting the font to null will reset it to the inherited or default value.

ForeColor

Gets or sets the foreground color of the element.

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

A System.Drawing.Color that represents the foreground color used for text and borders. The default value is determined by the current theme.
Remarks

This property is inheritable through the element tree, allowing child elements to inherit the foreground color from their parents unless explicitly overridden. The foreground color affects text rendering and border appearance.

Opacity

Gets or sets the opacity of an element. Value 0.0f indicates that the element is completely transparent, 1.0f means the element is not transparent (the default value).

Declaration
[RadPropertyDefaultValue("Opacity", typeof(VisualElement))]
public virtual double Opacity { get; set; }
Property Value
System.Double

SmoothingMode

Gets or sets the smoothing mode of an element. Smoothing mode enumeration defines possible values.

Declaration
[RadPropertyDefaultValue("SmoothingMode", typeof(VisualElement))]
public virtual SmoothingMode SmoothingMode { get; set; }
Property Value
System.Drawing.Drawing2D.SmoothingMode

Methods

GetScaledFont(Single)

Creates a scaled version of the element's font based on the provided scale factor.

Declaration
public virtual Font GetScaledFont(float scale)
Parameters
System.Single scale

The scale factor to apply to the font.
Returns
System.Drawing.Font

A new Font object with size adjusted according to the scale factor.
Remarks

This method applies DPI scaling if enabled. It's useful when rendering text at different zoom levels or on displays with different pixel densities.

GetScaledFont(Single, Font)

Creates a scaled version of the specified font based on the provided scale factor.

Declaration
protected virtual Font GetScaledFont(float scale, Font fontToScale)
Parameters
System.Single scale

The scale factor to apply to the font.
System.Drawing.Font fontToScale

The font to scale.
Returns
System.Drawing.Font

A new Font object with size adjusted according to the scale factor.

OnFontChanged(EventArgs)

Raises the FontChanged event.

Declaration
protected virtual void OnFontChanged(EventArgs e)
Parameters
System.EventArgs e

An System.EventArgs that contains the event data.

OnPropertyChanged(RadPropertyChangedEventArgs)

Called when a property value has changed, allowing for custom response to property changes.

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

The property changed event arguments.
Overrides

OnPropertyChanging(RadPropertyChangingEventArgs)

Called before a property value is changed, allowing for validation or cancellation.

Declaration
protected override void OnPropertyChanging(RadPropertyChangingEventArgs args)
Parameters
RadPropertyChangingEventArgs args

The property changing event arguments.
Overrides

PaintChildren(IGraphics, Rectangle, Single, SizeF, Boolean)

Paints the child elements of this visual element with opacity support.

Declaration
protected override void PaintChildren(IGraphics graphics, Rectangle clipRectangle, float angle, SizeF scale, bool useRelativeTransformation)
Parameters
IGraphics graphics

The graphics object used for painting.
System.Drawing.Rectangle clipRectangle

The clipping rectangle that limits the painting area.
System.Single angle

The rotation angle to apply during painting.
System.Drawing.SizeF scale

The scale factor to apply during painting.
System.Boolean useRelativeTransformation

True to use relative transformation; otherwise, false.
Overrides

PaintElement(IGraphics, Single, SizeF)

Paints the element's background and calls the base implementation to paint child elements.

Declaration
protected override void PaintElement(IGraphics graphics, float angle, SizeF scale)
Parameters
IGraphics graphics

The graphics object used for painting.
System.Single angle

The rotation angle to apply during painting.
System.Drawing.SizeF scale

The scale factor to apply during painting.
Overrides

PostPaintElement(IGraphics)

Performs post-painting cleanup operations including restoring smoothing mode and opacity.

Declaration
protected override void PostPaintElement(IGraphics graphics)
Parameters
IGraphics graphics

The graphics object used for painting.
Overrides

PrePaintElement(IGraphics)

Performs pre-painting operations including setting smoothing mode and opacity.

Declaration
protected override void PrePaintElement(IGraphics graphics)
Parameters
IGraphics graphics

The graphics object used for painting.
Overrides

Events

FontChanged

Occurs when the Font property value changes.

Declaration
public event EventHandler FontChanged
Event Type
System.EventHandler

Extension Methods