LightVisualElement
Represents a lightweight visual element that supports text, border, image, background color, and foreground color with various layout adjustments. This element provides efficient rendering capabilities for common UI scenarios while implementing text and image primitive interfaces.
Definition
Namespace:Telerik.WinControls.UI
Assembly:Telerik.WinControls.UI.dll
Syntax:
public class LightVisualElement : UIItemBase, INotifyPropertyChanged, ICustomTypeDescriptor, ISupportSystemSkin, IBindableComponent, IComponent, IDisposable, ISupportDrag, ISupportDrop, IShortcutProvider, IStylableElement, IStylableNode, IPrimitiveElement, IShapedElement, IFillElement, IBorderElement, IBoxStyle, IBoxElement, IDrawFillElement, IImageElement, ITextPrimitive, ITextProviderInheritance: objectDisposableObjectRadObjectRadElementVisualElementRadComponentElementRadItemUIItemBaseLightVisualElement...
Derived Classes:
Implements:
Inherited Members
Constructors
public LightVisualElement()Fields
public static RadProperty BackColor2Propertypublic static RadProperty BackColor3Propertypublic static RadProperty BackColor4Propertypublic static RadProperty BackgroundImageLayoutPropertypublic static RadProperty BackgroundImagePropertypublic static RadProperty BorderBottomColorPropertypublic static RadProperty BorderBottomShadowColorPropertypublic static RadProperty BorderBottomWidthPropertypublic static RadProperty BorderBoxStylePropertypublic static RadProperty BorderColor2Propertypublic static RadProperty BorderColor3Propertypublic static RadProperty BorderColor4Propertypublic static RadProperty BorderColorPropertypublic static RadProperty BorderDashPatternPropertypublic static RadProperty BorderDashStylePropertypublic static RadProperty BorderDrawModePropertypublic static RadProperty BorderGradientAnglePropertypublic static RadProperty BorderGradientStylePropertypublic static RadProperty BorderInnerColor2Propertypublic static RadProperty BorderInnerColor3Propertypublic static RadProperty BorderInnerColor4Propertypublic static RadProperty BorderInnerColorPropertypublic static RadProperty BorderLeftColorPropertypublic static RadProperty BorderLeftShadowColorPropertypublic static RadProperty BorderLeftWidthPropertypublic static RadProperty BorderRightColorPropertypublic static RadProperty BorderRightShadowColorPropertypublic static RadProperty BorderRightWidthPropertypublic static RadProperty BorderTopColorPropertypublic static RadProperty BorderTopShadowColorPropertypublic static RadProperty BorderTopWidthPropertypublic static RadProperty BorderWidthPropertypublic static RadProperty ClipTextPropertypublic static RadProperty DisabledTextRenderingHintPropertypublic static RadProperty DrawBackgroundImagePropertypublic static RadProperty DrawBorderPropertypublic static RadProperty DrawFillPropertypublic static RadProperty DrawImagePropertypublic static RadProperty DrawTextPropertypublic static RadProperty EnableImageTransparencyPropertypublic static RadProperty GradientAnglePropertypublic static RadProperty GradientPercentage2Propertypublic static RadProperty GradientPercentagePropertypublic static RadProperty GradientStylePropertypublic static RadProperty HorizontalLineColorPropertypublic static RadProperty HorizontalLineWidthPropertypublic static RadProperty ImageAlignmentPropertypublic static RadProperty ImageIndexPropertypublic static RadProperty ImageKeyPropertypublic static RadProperty ImageLayoutPropertypublic static RadProperty ImageOpacityPropertypublic static RadProperty ImagePropertypublic static RadProperty ImageTransparentColorPropertypublic static RadProperty NumberOfColorsPropertypublic static RadProperty ShowHorizontalLinePropertypublic static RadProperty SvgImagePropertypublic static RadProperty TextAlignmentPropertypublic static RadProperty TextImageRelationPropertypublic static RadProperty TextRenderingHintPropertypublic static RadProperty TextWrapPropertyProperties
Gets or sets a value indicating whether automatic text ellipsis will be applied when text cannot fit within the available space.
public bool AutoEllipsis { get; set; }Implements:
Gets or sets the second background color used in gradient fill effects for multi-color gradient styles.
[TypeConverter(typeof(RadColorEditorConverter))]
public override Color BackColor2 { get; set; }Overrides:
Gets or sets the third background color used in gradient fill effects for multi-color gradient styles.
[TypeConverter(typeof(RadColorEditorConverter))]
public override Color BackColor3 { get; set; }Overrides:
Gets or sets the fourth background color used in gradient fill effects for multi-color gradient styles.
[TypeConverter(typeof(RadColorEditorConverter))]
public override Color BackColor4 { get; set; }Overrides:
Gets or sets the background image displayed behind the element's content. This image is rendered according to the BackgroundImageLayout property.
[TypeConverter(typeof(ImageTypeConverter))]
public virtual Image BackgroundImage { get; set; }Gets or sets the layout mode for the background image, determining how it is positioned and scaled within the element bounds.
public virtual ImageLayout BackgroundImageLayout { get; set; }Gets or sets the color of the bottom border when using FourBorders style.
[TypeConverter(typeof(RadColorEditorConverter))]
public override Color BorderBottomColor { get; set; }Overrides:
Gets or sets the shadow color for the bottom border, providing a visual depth effect when rendered.
[TypeConverter(typeof(RadColorEditorConverter))]
public override Color BorderBottomShadowColor { get; set; }Overrides:
Gets or sets the width of the bottom border when using FourBorders style. This value is automatically scaled based on the current DPI settings of the display.
public override float BorderBottomWidth { get; set; }Overrides:
Gets or sets the border drawing style that determines how border appearance is configured. SingleBorder applies uniform appearance to all sides, while FourBorders allows individual configuration of each side's color, width, and shadow properties.
public override BorderBoxStyle BorderBoxStyle { get; set; }Overrides:
Gets or sets the primary border color used for solid borders or as the first color in gradient border effects.
[TypeConverter(typeof(RadColorEditorConverter))]
public override Color BorderColor { get; set; }Overrides:
Gets or sets the second color used in gradient border effects for radial, glass, office glass, gel, and vista gradient styles.
[TypeConverter(typeof(RadColorEditorConverter))]
public override Color BorderColor2 { get; set; }Overrides:
Gets or sets the third color used in gradient border effects for radial, glass, office glass, and vista gradient styles.
[TypeConverter(typeof(RadColorEditorConverter))]
public override Color BorderColor3 { get; set; }Overrides:
Gets or sets the fourth color used in gradient border effects for radial, glass, office glass, and vista gradient styles.
[TypeConverter(typeof(RadColorEditorConverter))]
public override Color BorderColor4 { get; set; }Overrides:
Gets or sets the custom dash pattern array for border rendering when using custom dashed line styles.
public override float[] BorderDashPattern { get; set; }Overrides:
Gets or sets the style of dashed lines used for border rendering when dashed border effects are applied.
public override DashStyle BorderDashStyle { get; set; }Overrides:
Gets or sets the drawing order for border lines when using FourBorders style. This property determines which border lines are drawn on top when borders overlap at corners.
public override BorderDrawModes BorderDrawMode { get; set; }Overrides:
Gets or sets the angle in degrees for linear gradient borders. This property determines the direction of the gradient effect when BorderGradientStyle is set to linear gradient.
public override float BorderGradientAngle { get; set; }Overrides:
Gets or sets the gradient style for border rendering. Available styles include solid, linear, radial, glass, office glass, gel, and vista. Each style provides different visual effects for the border appearance.
public override GradientStyles BorderGradientStyle { get; set; }Overrides:
Gets or sets the primary inner border color used in outer-inner border configurations for gradient border effects.
[TypeConverter(typeof(RadColorEditorConverter))]
public override Color BorderInnerColor { get; set; }Overrides:
Gets or sets the second inner border color used in outer-inner border configurations for gradient border effects.
[TypeConverter(typeof(RadColorEditorConverter))]
public override Color BorderInnerColor2 { get; set; }Overrides:
Gets or sets the third inner border color used in outer-inner border configurations for gradient border effects.
[TypeConverter(typeof(RadColorEditorConverter))]
public override Color BorderInnerColor3 { get; set; }Overrides:
Gets or sets the fourth inner border color used in outer-inner border configurations for gradient border effects.
[TypeConverter(typeof(RadColorEditorConverter))]
public override Color BorderInnerColor4 { get; set; }Overrides:
Gets or sets the color of the left border when using FourBorders style.
[TypeConverter(typeof(RadColorEditorConverter))]
public override Color BorderLeftColor { get; set; }Overrides:
Gets or sets the shadow color for the left border, providing a visual depth effect when rendered.
[TypeConverter(typeof(RadColorEditorConverter))]
public override Color BorderLeftShadowColor { get; set; }Overrides:
Gets or sets the width of the left border when using FourBorders style. This value is automatically scaled based on the current DPI settings of the display.
public override float BorderLeftWidth { get; set; }Overrides:
Gets or sets the color of the right border when using FourBorders style.
[TypeConverter(typeof(RadColorEditorConverter))]
public override Color BorderRightColor { get; set; }Overrides:
Gets or sets the shadow color for the right border, providing a visual depth effect when rendered.
[TypeConverter(typeof(RadColorEditorConverter))]
public override Color BorderRightShadowColor { get; set; }Overrides:
Gets or sets the width of the right border when using FourBorders style. This value is automatically scaled based on the current DPI settings of the display.
public override float BorderRightWidth { get; set; }Overrides:
Gets or sets the color of the top border when using FourBorders style.
[TypeConverter(typeof(RadColorEditorConverter))]
public override Color BorderTopColor { get; set; }Overrides:
Gets or sets the shadow color for the top border, providing a visual depth effect when rendered.
[TypeConverter(typeof(RadColorEditorConverter))]
public override Color BorderTopShadowColor { get; set; }Overrides:
Gets or sets the width of the top border when using FourBorders style. This value is automatically scaled based on the current DPI settings of the display.
public override float BorderTopWidth { get; set; }Overrides:
Gets or sets the uniform width of all border sides when using SingleBorder style. This value is automatically scaled based on the current DPI settings of the display.
public override float BorderWidth { get; set; }Overrides:
Gets or sets a value indicating whether the element can receive input focus.
public override bool CanFocus { get; set; }Overrides:
Gets or sets a value indicating whether text should be clipped to the calculated text painting rectangle boundaries.
public bool ClipText { get; set; }Gets or sets the opacity level applied to images when they are in a disabled state.
public virtual double DisabledImageOpacity { get; set; }If the value is set to a number outside the range 0.0 to 1.0, the property will use the value of the ImageOpacity property instead. The opacity value must be between 0.0 (fully transparent) and 1.0 (fully opaque).
Gets or sets the text rendering hint used specifically when this element is in a disabled state. This allows for different text rendering quality when the element is disabled versus enabled.
public virtual TextRenderingHint DisabledTextRenderingHint { get; set; }Gets or sets a value indicating whether HTML formatting in text content should be disabled, forcing plain text rendering.
public bool DisableHTMLRendering { get; set; }Gets or sets a value indicating whether the element should render its background image during the paint operation. This property controls the visibility of the image specified by the BackgroundImage property.
public bool DrawBackgroundImage { get; set; }Gets or sets a value indicating whether the element should render its border during the paint operation. This property controls the visibility of all border styles including single borders, four borders, and outer-inner borders.
public override bool DrawBorder { get; set; }Overrides:
Gets or sets a value indicating whether the element should render its background fill during the paint operation. This property controls the visibility of gradient fills, solid colors, and other background painting effects.
public override bool DrawFill { get; set; }Overrides:
Gets or sets a value indicating whether the element should render its main image during the paint operation. This property controls the visibility of the image specified by the Image property.
public bool DrawImage { get; set; }Gets or sets a value indicating whether the element should render its text content during the paint operation. When set to false, the text will not be visible even if the text property is set.
public virtual bool DrawText { get; set; }Gets or sets a value indicating whether image transparency effects are enabled for this element.
public bool EnableImageTransparency { get; set; }Gets or sets the angle in degrees for linear gradient background effects. This determines the direction of the gradient.
public override float GradientAngle { get; set; }Overrides:
Gets or sets the first gradient percentage that controls the distribution of colors in gradient background effects.
public override float GradientPercentage { get; set; }Overrides:
Gets or sets the second gradient percentage that controls the distribution of colors in gradient background effects.
public override float GradientPercentage2 { get; set; }Overrides:
Gets or sets the gradient style for background fill rendering. Available styles include solid, linear, radial, glass, office glass, gel, and vista.
public override GradientStyles GradientStyle { get; set; }Overrides:
Gets or sets the color of the horizontal line when ShowHorizontalLine is enabled.
[TypeConverter(typeof(RadColorEditorConverter))]
public virtual Color HorizontalLineColor { get; set; }Gets or sets the width in pixels of the horizontal line when ShowHorizontalLine is enabled. This value is automatically scaled based on current DPI settings.
public virtual int HorizontalLineWidth { get; set; }Gets or sets the main image displayed on the element. The image position is controlled by ImageAlignment and TextImageRelation properties.
[TypeConverter(typeof(ImageTypeConverter))]
public virtual Image Image { get; set; }Implements:
Gets or sets the alignment of the image within the element bounds, controlling both horizontal and vertical positioning.
public virtual ContentAlignment ImageAlignment { get; set; }Gets or sets the type of image to draw, determining whether to render bitmap images or SVG images based on availability and configuration. 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 virtual ImageDrawType ImageDrawType { get; set; }Gets or sets the index of the image from the associated to display on this element.
[RelatedImageList("ElementTree.Control.ImageList")]
[TypeConverter("Telerik.WinControls.UI.Design.NoneExcludedImageIndexConverter, Telerik.WinControls.UI.Design, Version=2026.2.721.48, Culture=neutral, PublicKeyToken=5bb2a467cbec794e")]
public virtual int ImageIndex { get; set; }Implements:
Gets or sets the key of the image from the associated to display on this element.
[TypeConverter("Telerik.WinControls.UI.Design.RadImageKeyConverter, Telerik.WinControls.UI.Design, Version=2026.2.721.48, Culture=neutral, PublicKeyToken=5bb2a467cbec794e")]
public virtual string ImageKey { get; set; }Implements:
Gets or sets the layout mode for the main image, determining how it is positioned and scaled within the element bounds.
public virtual ImageLayout ImageLayout { get; set; }Gets or sets the opacity level for image rendering, where 1.0 represents fully opaque and 0.0 represents fully transparent.
public virtual double ImageOpacity { get; set; }Gets or sets the color that will be treated as transparent when rendering images on this element.
[TypeConverter(typeof(RadColorEditorConverter))]
public Color ImageTransparentColor { get; set; }Gets the layout manager that controls the positioning and sizing of text and image content within this element.
public virtual LayoutManagerPart Layout { get; }Gets or sets a value indicating whether trailing spaces in text should be included in text measurement calculations.
[Browsable(false)]
public bool MeasureTrailingSpaces { get; set; }Implements:
Gets or sets the number of colors used in gradient background effects. This determines how many color properties are utilized.
public override int NumberOfColors { get; set; }Overrides:
Gets or sets a value indicating whether the element should be painted.
public override bool ShouldPaint { get; set; }Overrides:
Children visibility is not be affected.
Gets or sets a value indicating whether a horizontal line should be rendered across the element.
public virtual bool ShowHorizontalLine { get; set; }Gets or sets a value indicating whether keyboard access cues (underlines for mnemonics) should be displayed for this element.
[Browsable(false)]
public virtual bool ShowKeyboardCues { get; set; }Implements:
Gets or sets the SVG image to be displayed on this element as a scalable vector graphic.
public virtual RadSvgImage SvgImage { get; set; }Gets or sets the alignment of text within the element bounds, controlling both horizontal and vertical positioning.
public virtual ContentAlignment TextAlignment { get; set; }Implements:
Gets or sets the spatial relationship between text and image content. This determines how text and image are positioned relative to each other.
public TextImageRelation TextImageRelation { get; set; }This property is not relevant for this class.
public TextParams TextParams { get; }Gets or sets the text rendering hint that determines the quality and anti-aliasing mode used when rendering text on this element. This property affects the visual appearance and readability of text displayed by the element.
public virtual TextRenderingHint TextRenderingHint { get; set; }Gets or sets a value indicating whether text will automatically wrap to multiple lines when it exceeds the element's width.
public virtual bool TextWrap { get; set; }Implements:
Gets or sets a value indicating whether ampersand characters (&) in text will be treated as mnemonic access key indicators.
public virtual bool UseMnemonic { get; set; }Implements:
Methods
Arranges a single child element according to its fit-to-size mode within the allocated space.
protected virtual void ArrangeElement(RadElement element, SizeF finalSize)The child element to arrange.
finalSizeSizeFThe final size available for arranging the element.
Arranges the content and child elements within the final allocated space, positioning text, images, and child elements.
Calculates the final desired size by combining the element's content size with child elements' size requirements.
protected virtual SizeF CalculateDesiredSize(SizeF availableSize, SizeF desiredSize, SizeF elementsDesiredSize)The available space that a parent element can allocate.
desiredSizeSizeFThe desired size calculated from content and layout requirements.
elementsDesiredSizeSizeFThe desired size calculated from child elements.
Returns:The final desired size taking into account all size constraints.
Clips an image to fit within the specified rectangle and size constraints, creating a new image if necessary.
protected virtual Image ClipImage(Image image, Rectangle imageRectange, Size size)The source image to clip.
imageRectangeRectangleThe rectangle defining the clipping area within the source image.
sizeSizeThe target size for the clipped image.
Returns:The clipped image, or the original image if no clipping is needed.
Disposes of managed resources including cached images and SVG images when the element is being disposed.
protected override void DisposeManagedResources()Overrides:
Draws a horizontal line across the element when text is present, positioning the line based on text alignment and size.
protected virtual void DrawHorizontalLine(IGraphics graphics)The graphics context used for rendering the horizontal line.
Draws a horizontal line across the element when no text is present and ShowHorizontalLine is enabled.
protected virtual void DrawHorizontalLineWithoutText(IGraphics graphics)The graphics context used for rendering the horizontal line.
Gets the border thickness for this element instance by delegating to the static GetBorderThickness(LightVisualElement, bool) method.
protected virtual Padding GetBorderThickness(bool checkDrawBorder)When true, returns zero thickness if DrawBorder is false.
Returns:A Padding structure representing the border thickness.
Calculates the border thickness for a LightVisualElement based on its border configuration and drawing state.
public static Padding GetBorderThickness(LightVisualElement element, bool checkDrawBorder)The LightVisualElement instance to calculate border thickness for.
checkDrawBorderboolWhen true, returns zero thickness if DrawBorder is false; otherwise ignores the drawing state.
Returns:A Padding structure representing the calculated border thickness for all sides.
Calculates the client area offset by combining padding and optionally border thickness.
Calculates the client rectangle area available for content within the element bounds, optionally including border space.
protected virtual RectangleF GetClientRectangle(bool includeBorder, SizeF finalSize)When true, accounts for border thickness in the client rectangle calculation.
finalSizeSizeFThe total size of the element from which to calculate the client rectangle.
Returns:A RectangleF representing the available client area for content.
protected override RectangleF GetClientRectangle(SizeF finalSize)Overrides:
Calculates the clipping rectangle for this element, taking into account border thickness and padding.
protected override RectangleF GetClipRect()A RectangleF representing the clipping bounds for content rendering.
Overrides:
Gets the border width that should be used for painting operations, typically inherited from the parent element.
public override float GetPaintingBorderWidth()The border width in pixels, or 0 if no parent element is available.
Overrides:
Gets the IFilter instance that may be used to filter the properties, treated as Stylable for this element.
protected ContentAlignment GetTextAlignment(ContentAlignment textAlignment)Calculates the size required to display the text content within the proposed size constraints.
public SizeF GetTextSize(SizeF proposedSize, TextParams textParams)The proposed size constraints for the text measurement.
textParamsTextParamsThe text parameters containing formatting and display options.
Returns:A SizeF representing the calculated text size.
Implements:
Calculates the size required to display the text content using the specified text parameters.
public SizeF GetTextSize(TextParams textParams)The text parameters containing formatting and display options.
Returns:A SizeF representing the calculated text size.
Implements:
Initializes the internal fields and components of the LightVisualElement. This method sets up text primitives, image primitives, and layout management components.
protected override void InitializeFields()Overrides:
Maps a style property to another property. This method is used to map corresponding properties of LightVisualElement instances and BasePrimitive instances.
public override RadProperty MapStyleProperty(RadProperty propertyToMap, string settingType)An instance of the RadProperty class that represents the property to map.
settingTypestringReturns:An instance of the RadProperty class which represents the mapped property. If no property is found, the method returns null
Overrides:
Measures all child elements when auto-sizing is enabled, calculating the space required for child elements.
protected virtual SizeF MeasureElements(SizeF availableSize, SizeF clientSize, Padding borderThickness)The available space that a parent element can allocate.
clientSizeSizeFThe client area size available for content.
borderThicknessPaddingThe thickness of the border that affects available space.
Returns:The desired size needed to accommodate all child elements.
Measures the desired size of the text content given the available space and text parameters.
public SizeF MeasureOverride(SizeF availableSize, TextParams textParams)The available space for measuring the text content.
textParamsTextParamsThe text parameters containing formatting and display options.
Returns:A SizeF representing the desired size of the text content.
Implements:
Measures the desired size of the element by calculating the space needed for content, padding, and borders.
Called when animated image frame changes.
protected virtual void OnAnimatedImageFrameChanged()Handles state changes for bit flags, particularly managing text primitive implementation when HTML rendering is disabled.
Called when the element has been successfully loaded. That includes loading of all its children as well.
protected override void OnLoaded()Overrides:
Called when the mouse moves over the item, handling highlight and border highlight effects.
protected override void OnMouseMove(MouseEventArgs e)The mouse event arguments.
Overrides:
Handles mouse movement events for the text primitive, enabling text interaction features.
public void OnMouseMove(object sender, MouseEventArgs e)The source of the mouse move event.
eMouseEventArgsThe MouseEventArgs containing event data.
Implements:
Handles property change events by invalidating the fill cache and invoking the base class property change handler.
protected override void OnPropertyChanged(RadPropertyChangedEventArgs e)Event arguments containing information about the property that changed.
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:
Renders the background image of the element according to the specified BackgroundImageLayout setting.
protected virtual void PaintBackgroundImage(IGraphics graphics)The graphics context used for rendering the background image.
Orchestrates the painting of all content elements including background image, main image or SVG image, and text.
protected virtual void PaintContent(IGraphics graphics)The graphics context used for rendering content.
Performs the main painting operation for the element, rendering fill, content, and border in the correct order.
Renders the main image of the element, handling image animation and thread-safe access to the cached image.
protected virtual void PaintImage(IGraphics graphics)The graphics context used for rendering the image.
Paints the text primitive with the specified graphics context, transformation, and text parameters.
public void PaintPrimitive(IGraphics graphics, float angle, SizeF scale, TextParams textParams)The graphics context used for painting.
anglefloatThe rotation angle to apply during painting.
scaleSizeFThe scale factor to apply during painting.
textParamsTextParamsThe text parameters containing formatting and display options.
Implements:
Paints the text primitive with the specified graphics context and text parameters.
public void PaintPrimitive(IGraphics graphics, TextParams textParams)The graphics context used for painting.
textParamsTextParamsThe text parameters containing formatting and display options.
Implements:
Renders the text content of the element, including horizontal line effects when enabled.
protected virtual void PaintText(IGraphics graphics)The graphics context used for rendering text.
Determines whether the property defined by the provided property descriptor should be serialized.
public override bool? ShouldSerializeProperty(PropertyDescriptor property)bool?
Overrides:
Toggles the text primitive when text related properties are change.
protected virtual void ToggleTextPrimitive(RadProperty property)The changed property.