BorderPrimitive
Represents a primitive element that renders borders around other elements with comprehensive styling and customization options.
BorderPrimitive is a fundamental rendering component in the Telerik WinControls framework that provides sophisticated border rendering capabilities. It supports multiple border styles including solid, dotted, dashed, double borders, and complex multi-side border configurations with individual styling per side.
Key features include:
- Multiple border box styles: single border, four-sided borders, and outer-inner border combinations
- Individual side styling with different colors, widths, and styles for top, bottom, left, and right borders
- Support for various border drawing modes and gradient effects
- Integration with shape primitives for rounded corners and custom border shapes
- Automatic thickness calculation and parent element border synchronization
BorderPrimitive is commonly used in conjunction with FillPrimitive to create complete visual styling for RadElements, providing both background fills and border outlines. It automatically handles DPI scaling and provides optimized rendering performance through caching and buffer management.
The primitive integrates seamlessly with the theming system and supports inheritance of border properties from parent elements, making it suitable for complex nested control scenarios.
Definition
Namespace:Telerik.WinControls.Primitives
Assembly:Telerik.WinControls.dll
Syntax:
public class BorderPrimitive : BasePrimitive, IDisposable, INotifyPropertyChanged, ICustomTypeDescriptor, ISupportSystemSkin, IStylableNode, IPrimitive, IBorderElement, IBoxStyle, IBoxElement, IPrimitiveElement, IShapedElement
Inheritance: objectDisposableObjectRadObjectRadElementVisualElementBasePrimitiveBorderPrimitive...
Derived Classes:
Implements:
Inherited Members
Constructors
public BorderPrimitive()
Fields
Identifies the property that selects shared, per-side, or outer-and-inner border geometry.
public static readonly RadProperty BorderBoxStyleProperty
Identifies the custom dash lengths used when BorderDashStyle is custom.
public static readonly RadProperty BorderDashPatternProperty
Identifies the stroke pattern used to draw the border.
public static readonly RadProperty BorderDashStyleProperty
Identifies the property that controls which border sides cover one another at corners.
public static readonly RadProperty BorderDrawModeProperty
Identifies the color of the bottom border in four-border mode.
public static readonly RadProperty BottomColorProperty
Identifies the shadow color of the bottom border in four-border mode.
public static readonly RadProperty BottomShadowColorProperty
Identifies the bottom-side thickness used when BoxStyle is FourBorders.
public static readonly RadProperty BottomWidthProperty
Identifies an additional outer-border color used by gradient rendering.
public static RadProperty ForeColor2Property
Identifies an additional outer-border color used by gradient rendering.
public static RadProperty ForeColor3Property
Identifies an additional outer-border color used by gradient rendering.
public static RadProperty ForeColor4Property
Identifies the angle, in degrees, used by linear border gradients.
public static RadProperty GradientAngleProperty
Identifies the gradient effect applied to border colors.
public static RadProperty GradientStyleProperty
Identifies an additional inner-stroke color used by gradient rendering.
public static RadProperty InnerColor2Property
Identifies an additional inner-stroke color used by gradient rendering.
public static RadProperty InnerColor3Property
Identifies an additional inner-stroke color used by gradient rendering.
public static RadProperty InnerColor4Property
Identifies the primary color of the inner stroke in outer-and-inner border mode.
public static RadProperty InnerColorProperty
Identifies the color of the left border in four-border mode.
public static readonly RadProperty LeftColorProperty
Identifies the shadow color of the left border in four-border mode.
public static readonly RadProperty LeftShadowColorProperty
Identifies the left-side thickness used when BoxStyle is FourBorders.
public static readonly RadProperty LeftWidthProperty
Identifies the property that determines whether the border follows its parent's shape.
public static readonly RadProperty PaintUsingParentShapeProperty
Identifies the color of the right border in four-border mode.
public static readonly RadProperty RightColorProperty
Identifies the shadow color of the right border in four-border mode.
public static readonly RadProperty RightShadowColorProperty
Identifies the right-side thickness used when BoxStyle is FourBorders.
public static readonly RadProperty RightWidthProperty
Identifies the color of the top border in four-border mode.
public static readonly RadProperty TopColorProperty
Identifies the shadow color of the top border in four-border mode.
public static readonly RadProperty TopShadowColorProperty
Identifies the top-side thickness used when BoxStyle is FourBorders.
public static readonly RadProperty TopWidthProperty
Identifies the shared border thickness used when BoxStyle is SingleBorder.
public static readonly RadProperty WidthProperty
Properties
Specifies the pattern of dashed lines drawn when the BorderDashStyle is custom.
public float[] BorderDashPattern { get; set; }
Implements:
Specifies the style of dashed lines drawn with a border.
public DashStyle BorderDashStyle { get; set; }
Implements:
public BorderDrawModes BorderDrawMode { get; set; }
Implements:
Retrieves size of the combined bottom, right, upper, and left border.
[Browsable(false)]
public SizeF BorderSize { get; }
Implements:
Gets and sets the bottom border color. This applies only if FourBorders is chosen for BoxStyle property, and affects only the bottom border.
[TypeConverter(typeof(RadColorEditorConverter))]
public Color BottomColor { get; set; }
Implements:
Gets and sets the bottom shadow color. This option applies only if fourBorders is chosen, and affects only the bottom border.
[TypeConverter(typeof(RadColorEditorConverter))]
public Color BottomShadowColor { get; set; }
Implements:
Gets or sets a float value width. This property has effect only if FourBorders style is used in BoxStyle property, and affects only the bottom border.
public float BottomWidth { get; set; }
Implements:
Gets or sets the Border style. The two possible values are SingleBorder and FourBorder. In the single border case, all four sides share the same appearance although the entire border may have gradient. In four border case, each of the four sides may differ in appearance. For example, the left border may have different color, shadowcolor, and width from the rest. When SingleBorder is chosen, you should use the general properties such as width and color, and respectively, when the FourBorder style is chosen you should use properties prefixed with the corresponding side, for example, LeftColor, LeftWidth for the left side.
public BorderBoxStyle BoxStyle { get; set; }
Implements:
Gets or sets how the border fits within its parent; the default is FitToParentBounds.
public override RadFitToSizeMode FitToSizeMode { get; set; }
Overrides:
Gets or sets color used by radial, glass, office glass, gel, and vista gradients. This is one of the colors that are used in the gradient effect.
[TypeConverter(typeof(RadColorEditorConverter))]
public virtual Color ForeColor2 { get; set; }
Implements:
Gets or sets color used by radial, glass, office glass, and vista gradients. This is one of the colors that are used in the gradient effect.
[TypeConverter(typeof(RadColorEditorConverter))]
public virtual Color ForeColor3 { get; set; }
Implements:
Gets or sets color used by radial, glass, office glass, and vista gradients. This is one of the colors that are used in the gradient effect.
[TypeConverter(typeof(RadColorEditorConverter))]
public virtual Color ForeColor4 { get; set; }
Implements:
Gets or sets gradient angle for linear gradient measured in degrees.
public float GradientAngle { get; set; }
Implements:
Gets or sets gradient style. Possible styles are solid, linear, radial, glass, office glass, gel, and vista.
public GradientStyles GradientStyle { get; set; }
Implements:
Gets the horizontal width of the combined left and right border.
[Browsable(false)]
public float HorizontalWidth { get; }
Implements:
Gets or sets color used by radial, glass, office glass, gel, and vista gradients. This is one of the colors that are used in the gradient effect.
[TypeConverter(typeof(RadColorEditorConverter))]
public virtual Color InnerColor { get; set; }
Implements:
Gets or sets color used by radial, glass, office glass, gel, and vista gradients. This is one of the colors that are used in the gradient effect.
[TypeConverter(typeof(RadColorEditorConverter))]
public virtual Color InnerColor2 { get; set; }
Implements:
Gets or sets color used by radial, glass, office glass, gel, and vista gradients. This is one of the colors that are used in the gradient effect.
[TypeConverter(typeof(RadColorEditorConverter))]
public virtual Color InnerColor3 { get; set; }
Implements:
Gets or sets color used by radial, glass, office glass, gel, and vista gradients. This is one of the colors that are used in the gradient effect.
[TypeConverter(typeof(RadColorEditorConverter))]
public virtual Color InnerColor4 { get; set; }
Implements:
Gets and sets the left border color. This applies only if FourBorders is chosen for BoxStyle property, and affects only the left border.
[TypeConverter(typeof(RadColorEditorConverter))]
public Color LeftColor { get; set; }
Implements:
Gets and sets the left shadow color. This option applies only if fourBorders is chosen, and affects only the left border.
[TypeConverter(typeof(RadColorEditorConverter))]
public Color LeftShadowColor { get; set; }
Implements:
Gets or sets a float value width of the left border. This property has effect only if FourBorders style is used in BoxStyle property and affects only the width of the left border.
public float LeftWidth { get; set; }
Implements:
Gets the border offset of the primitive. It effectively retrieves the upper-left corner inside the primitive border. It takes into consideration the BoxStyle property and possible different widths of the left and the upper side.
[Browsable(false)]
public SizeF Offset { get; }
Implements:
Specifies whether the BorderPrimitive should draw the GraphicsPath defined by its Parent.Shape. If false, it will draw its bounding rectangle.
public bool PaintUsingParentShape { get; set; }
Gets and sets the right border color. This applies only if FourBorders is chosen for BoxStyle property, and affects only the right border.
[TypeConverter(typeof(RadColorEditorConverter))]
public Color RightColor { get; set; }
Implements:
Gets and sets the right shadow color. This option applies only if fourBorders is chosen, and affects only the right border.
[TypeConverter(typeof(RadColorEditorConverter))]
public Color RightShadowColor { get; set; }
Implements:
Gets or sets a float value width of the right border. This property has effect only if FourBorders style is used in BoxStyle property, and affects only the right border.
public float RightWidth { get; set; }
Implements:
Uses PaintUsingParentShape to determine whether border rendering follows the parent shape.
protected override bool ShouldPaintUsingParentShape { get; }
Overrides:
Gets and sets the top border color. This applies only if FourBorders is chosen for BoxStyle property, and affects only the top border.
[TypeConverter(typeof(RadColorEditorConverter))]
public Color TopColor { get; set; }
Implements:
Gets and sets the top shadow color. This option applies only if fourBorders is chosen, and affects only the top border.
[TypeConverter(typeof(RadColorEditorConverter))]
public Color TopShadowColor { get; set; }
Implements:
Gets or sets a float value width of the top border . This property has effect only if FourBorders style is used in BoxStyle property, and affects only the top border.
public float TopWidth { get; set; }
Implements:
Gets the vertical width of the combined bottom and upper border.
[Browsable(false)]
public float VerticalWidth { get; }
Implements:
Methods
Supplies border-specific defaults for color, sizing, and smoothing properties.
protected override object GetDefaultValue(RadPropertyValue propVal, object baseDefaultValue)
The property value being initialized.
baseDefaultValueobjectThe default value supplied by the base implementation.
Returns:The border-specific default for recognized properties, or baseDefaultValue otherwise.
Overrides:
Limits the properties exposed for styling to border, appearance, and behavior settings.
public override Filter GetStylablePropertiesFilter()
A filter combining the border, appearance, and behavior property groups.
Overrides:
Creates the renderer used to draw this border.
protected override void InitializeFields()
Overrides:
Measures the optional nested border in the space remaining after this border's thickness is accounted for.
Tracks nested border primitives so their thickness can be included in the parent border.
protected override void OnChildrenChanged(RadElement child, ItemsChangeOperation changeOperation)
The child element that was added or removed.
changeOperationItemsChangeOperationIndicates whether the child was added or removed.
Overrides:
Synchronizes the new parent element's border thickness with this border.
protected override void OnParentChanged(RadElement previousParent)
The parent the element had before the change.
Overrides:
Recalculates and synchronizes border thickness when border geometry or visibility changes.
protected override void OnPropertyChanged(RadPropertyChangedEventArgs e)
Information about the property change.
Overrides:
Renders the border primitive using the specified graphics context with rotation and scaling support.
public override void PaintPrimitive(IGraphics graphics, float angle, SizeF scale)
The graphics context to use for rendering the border.
anglefloatThe rotation angle in degrees to apply during rendering.
scaleSizeFThe scaling factor to apply during rendering.
Overrides:
This method delegates the actual border painting to the internal border implementation, which handles the complex rendering logic for different border styles, shapes, and effects. The rendering is optimized for performance and supports advanced features like anti-aliasing and gradient effects.
Applies border-specific rules when deciding whether designer serialization should include a property.
public override bool? ShouldSerializeProperty(PropertyDescriptor property)
bool?
Overrides:
Requests serialization for
SmoothingModewhen it is not AntiAlias and forFitToSizeModewhen it is not FitToParentBounds. Other properties use the base implementation.