Class RadRatingElement
Represents the core rating element that provides the visual and interactive functionality for rating controls. This element manages a collection of rating visual items (typically stars), handles user interactions for value selection, supports different selection modes and orientations, and provides comprehensive tooltip and hover feedback systems. It serves as the main implementation behind the RadRating control wrapper.
Inheritance
Inherited Members
Namespace: Telerik.WinControls.UI
Assembly: Telerik.WinControls.UI.dll
Syntax
public class RadRatingElement : StackLayoutElement, INotifyPropertyChanged, ICustomTypeDescriptor, ISupportSystemSkin, IComponent, IDisposable, IBindableComponent, ISupportDrag, ISupportDrop, IShortcutProvider, IStylableElement, IStylableNode, IPrimitiveElement, IShapedElement, IFillElement, IBorderElement, IBoxStyle, IBoxElement, IDrawFillElement, IImageElement, ITextPrimitive, ITextProviderConstructors
RadRatingElement()
Declaration
public RadRatingElement()Fields
ValueProperty
Identifies the Value dependency property. This property defines the current rating value with support for null values to indicate no rating. Changes to this property trigger layout updates and visual refresh operations.
Declaration
public static RadProperty ValuePropertyField Value
|
RadProperty
|
Properties
Caption
Gets or sets the text displayed in the caption label positioned above the rating items. This text typically serves as a title or primary label for the rating interface, providing context about what is being rated.
Declaration
public string Caption { get; set; }Property Value
|
System.String
A string representing the caption text. The default value is an empty string. |
CaptionElement
Gets the visual element that displays the caption text. This provides direct access to the caption element for advanced styling, theming, or layout customization.
Declaration
public LightVisualElement CaptionElement { get; }Property Value
|
LightVisualElement
A LightVisualElement representing the caption display element. |
Description
Gets or sets the text displayed in the description label positioned below the rating items. This text typically provides additional information, instructions, or context about the rating, such as explaining what different rating values represent or providing usage guidelines.
Declaration
public string Description { get; set; }Property Value
|
System.String
A string representing the description text. The default value is an empty string. |
DescriptionElement
Gets the visual element that displays the description text. This provides direct access to the description element for advanced styling, theming, or layout customization.
Declaration
public LightVisualElement DescriptionElement { get; }Property Value
|
LightVisualElement
A LightVisualElement representing the description display element. |
Direction
Gets or sets the direction in which rating items are painted and evaluated. This determines whether the rating starts from the beginning (Standard) or from the end (Reversed) of the item collection, affecting both visual appearance and value calculation during user interactions.
Declaration
public RatingDirection Direction { get; set; }Property Value
|
RatingDirection
A RatingDirection value that specifies the painting direction. The default is Standard. |
ElementOrientation
Gets or sets the orientation of the rating control, determining whether rating items are arranged horizontally or vertically. Changing the orientation affects both the visual layout and the interaction behavior of rating items, automatically updating the vertical properties of individual rating elements.
Declaration
public Orientation ElementOrientation { get; set; }Property Value
|
System.Windows.Forms.Orientation
An System.Windows.Forms.Orientation value that specifies the layout orientation. The default is System.Windows.Forms.Orientation.Horizontal. |
ElementsLayout
Gets the stack layout element that contains and arranges the rating visual items. This provides direct access to the layout container for advanced customization of item arrangement, spacing, and orientation behavior.
Declaration
public StackLayoutElement ElementsLayout { get; }Property Value
|
StackLayoutElement
A StackLayoutElement that manages the layout of rating items. |
HoverValue
Gets or sets the hover value that represents the rating value under the current mouse position. This value is used to provide visual feedback during mouse hover operations, allowing users to preview what their rating selection would be before clicking to confirm.
Declaration
public double HoverValue { get; set; }Property Value
|
System.Double
A double representing the hover value for visual feedback. |
IsInRadGridView
Gets or sets a value indicating whether this rating element is hosted within a RadGridView control. This property enables special handling and optimizations when the rating element is used as a grid cell editor, automatically propagating this state to all contained rating visual elements for consistent behavior.
Declaration
public bool IsInRadGridView { get; set; }Property Value
|
System.Boolean
true if the element is hosted in a RadGridView; otherwise, false. |
Items
Gets the collection of rating visual items that represent the individual rating elements. This collection contains the visual elements (such as stars, diamonds, or hearts) that users interact with to provide their rating. Items can be added, removed, or customized to create different rating interfaces.
Declaration
public RadItemOwnerCollection Items { get; }Property Value
|
RadItemOwnerCollection
A RadItemOwnerCollection containing the rating visual elements. |
Maximum
Gets or sets the maximum value that can be assigned to the rating element. This property defines the upper bound of the rating range and affects how rating items are interpreted. The maximum value must be greater than the minimum value to maintain a valid range.
Declaration
public double Maximum { get; set; }Property Value
|
System.Double
A double value representing the maximum rating. The default value is 100.0. |
Exceptions
|
System.ArgumentException
Thrown when the maximum value is set to be less than or equal to the minimum value. |
Minimum
Gets or sets the minimum value that can be assigned to the rating element. This property defines the lower bound of the rating range and affects how rating items are interpreted. The minimum value must be less than the maximum value to maintain a valid range.
Declaration
public double Minimum { get; set; }Property Value
|
System.Double
A double value representing the minimum rating. The default value is 0.0. |
Exceptions
|
System.ArgumentException
Thrown when the minimum value is set to be greater than or equal to the maximum value. |
PercentageRounding
Gets or sets the percentage threshold used for automatic value rounding near the minimum and maximum bounds. When user selections are within this percentage of the range extremes, the value automatically snaps to the minimum or maximum value for improved usability and to prevent accidental near-miss selections.
Declaration
public double PercentageRounding { get; set; }Property Value
|
System.Double
A double representing the percentage rounding threshold as a value between 0 and 100. The default value is 0.5. |
ReadOnly
Gets or sets a value indicating whether the rating element is in read-only mode. When read-only, users cannot interact with the rating items to change the value, but the value can still be set programmatically. This mode is useful for displaying ratings without allowing user modification, such as showing existing reviews or scores.
Declaration
public bool ReadOnly { get; set; }Property Value
|
System.Boolean
true if the rating element is read-only; otherwise, false. The default value is false. |
SelectedValue
Gets or sets the internal selected value that represents the user's current selection before it's committed. This value is used during interaction scenarios to track what the user has selected but may not yet be reflected in the final Value property. It supports percentage-based rounding for user-friendly value snapping near minimum and maximum bounds.
Declaration
public virtual double SelectedValue { get; set; }Property Value
|
System.Double
A double representing the selected value within the element's range. |
SelectionMode
Gets or sets the selection mode that determines how rating values are calculated and quantized during user interaction. This property controls the precision and behavior of value selection, supporting precise decimal values, half-item increments, or full-item selections based on user interaction patterns.
Declaration
public RatingSelectionMode SelectionMode { get; set; }Property Value
|
RatingSelectionMode
A RatingSelectionMode value that specifies the selection behavior. The default is Precise. |
ShouldPaintHover
Gets or sets a value indicating whether hover visual feedback should be displayed when users move their mouse over rating items. When enabled, rating items will show visual preview of the potential selection as the mouse moves across them. This enhances user experience by providing immediate visual feedback during interaction.
Declaration
public bool ShouldPaintHover { get; set; }Property Value
|
System.Boolean
true to display hover effects; false to disable hover visual feedback. The default value is true. |
SubCaption
Gets or sets the text displayed in the sub-caption label positioned between the caption and rating items. This text provides additional context or instructions for the rating interface, typically offering more detailed information than the main caption.
Declaration
public string SubCaption { get; set; }Property Value
|
System.String
A string representing the sub-caption text. The default value is an empty string. |
SubCaptionElement
Gets the visual element that displays the sub-caption text. This provides direct access to the sub-caption element for advanced styling, theming, or layout customization.
Declaration
public LightVisualElement SubCaptionElement { get; }Property Value
|
LightVisualElement
A LightVisualElement representing the sub-caption display element. |
ToolTipDuration
Gets or sets the duration in milliseconds that tooltips remain visible during user interaction. This property controls how long tooltips stay displayed when users hover over rating items, balancing information availability with interface cleanliness.
Declaration
public int ToolTipDuration { get; set; }Property Value
|
System.Int32
An integer representing the tooltip duration in milliseconds. The default value is 2000 (2 seconds). |
ToolTipFormatString
Gets or sets the format string used for displaying tooltip values during user interaction. This string uses standard .NET string formatting syntax to control how rating values are presented in tooltips when users hover over rating items.
Declaration
public string ToolTipFormatString { get; set; }Property Value
|
System.String
A format string for tooltip display. The default value is "{0:0.0}" to show one decimal place. |
ToolTipOffset
Gets or sets the offset position for tooltip display relative to the mouse cursor. This property controls where tooltips appear in relation to the current mouse position, allowing customization of tooltip placement to avoid cursor obstruction and improve readability.
Declaration
public Point ToolTipOffset { get; set; }Property Value
|
System.Drawing.Point
A System.Drawing.Point representing the tooltip offset in pixels. The default value is (10, 15). |
ToolTipPrecision
Gets or sets the precision threshold for tooltip value updates during mouse interaction. This value determines how much the current rating value must change before the tooltip content is updated, preventing excessive tooltip flickering during smooth mouse movements.
Declaration
public double ToolTipPrecision { get; set; }Property Value
|
System.Double
A double representing the precision threshold for tooltip updates. The default value is 0.1. |
Value
Gets or sets the current rating value as a nullable double. This is the primary property that represents the user's rating selection within the range defined by Minimum and Maximum properties. A null value indicates that no rating has been selected. Value changes trigger validation, range checking, and cancelable change events.
Declaration
public double? Value { get; set; }Property Value
|
System.Nullable<System.Double>
A nullable double representing the current rating value, or null if no rating is selected. |
Methods
CreateChildElements()
Creates and configures the child elements that comprise the rating interface. This method establishes the visual hierarchy including caption, sub-caption, description labels, and the main elements layout container. It also initializes the rating items collection with default item types and configures the overall layout properties.
Declaration
protected override void CreateChildElements()Overrides
GetElementIndex(Nullable<Double>)
Calculates and returns the zero-based index of the rating item that corresponds to the specified value. This method performs value-to-index mapping considering the current range, direction, and orientation settings to determine which rating item should be highlighted or selected.
Declaration
protected virtual int GetElementIndex(double? value)Parameters
|
System.Nullable<System.Double>
value
The rating value to convert to an item index. |
Returns
|
System.Int32
An integer representing the zero-based index of the corresponding rating item. |
GetNormalizedValue(Nullable<Double>)
Normalizes a rating value by subtracting the minimum value to create a zero-based range. This method converts absolute rating values to relative values within the rating range, handling null values appropriately for consistent calculations.
Declaration
protected virtual double GetNormalizedValue(double? value)Parameters
|
System.Nullable<System.Double>
value
The rating value to normalize, or null if no value is set. |
Returns
|
System.Double
A double representing the normalized value relative to the minimum bound. |
GetRelativePoint(Int32, RatingBaseVisualElement, Nullable<Double>)
Calculates the relative point within a rating visual element that corresponds to the specified value. This method determines the precise position within an individual rating item where the visual representation should be clipped or highlighted based on the partial value it represents.
Declaration
protected virtual Point GetRelativePoint(int elementIndex, RatingBaseVisualElement currentVisualElement, double? value)Parameters
|
System.Int32
elementIndex
The index of the rating element being calculated. |
|
RatingBaseVisualElement
currentVisualElement
The visual element for which to calculate the relative point. |
|
System.Nullable<System.Double>
value
The rating value to convert to a relative position. |
Returns
|
System.Drawing.Point
A System.Drawing.Point representing the relative position within the visual element. |
InitializeFields()
Initializes the fields and default values for the rating element. This method sets up default tooltip configuration, rounding behavior, and visual settings to provide a consistent baseline experience for rating interactions.
Declaration
protected override void InitializeFields()Overrides
MeasureOverride(SizeF)
Measures the desired size of the rating element based on its child elements and available space. This method calculates the optimal size by measuring all child elements (caption, sub-caption, rating items layout, and description) and determining the required width and height.
Declaration
protected override SizeF MeasureOverride(SizeF availableSize)Parameters
|
System.Drawing.SizeF
availableSize
The available size that this element can use to arrange its children. |
Returns
|
System.Drawing.SizeF
A System.Drawing.SizeF representing the desired size of the rating element. |
Overrides
OnClick(EventArgs)
Handles the click event to commit the current selected value as the rating value. This method validates that the click occurred within the rating items area and that the element is not in read-only mode before applying the selected value.
Declaration
protected override void OnClick(EventArgs e)Parameters
|
System.EventArgs
e
An System.EventArgs that contains the event data. |
Overrides
OnMouseDown(MouseEventArgs)
Handles the mouse down event to update the selected value and apply visual feedback. This method calculates the rating value based on the mouse position, updates the selected value, and triggers visual painting for the selected value layer.
Declaration
protected override void OnMouseDown(MouseEventArgs e)Parameters
|
System.Windows.Forms.MouseEventArgs
e
A System.Windows.Forms.MouseEventArgs that contains the event data. |
Overrides
OnMouseLeave(EventArgs)
Handles the mouse leave event by resetting all interactive visual states and hiding tooltips. This method ensures that hover effects and visual feedback are properly cleared when the mouse exits the rating element boundaries.
Declaration
protected override void OnMouseLeave(EventArgs e)Parameters
|
System.EventArgs
e
An System.EventArgs that contains the event data. |
Overrides
OnMouseMove(MouseEventArgs)
Handles mouse movement over the rating element, providing interactive feedback and tooltip display. This method processes mouse position to determine hover values, updates visual feedback, and manages tooltip display with precision-based updates. It respects read-only mode and handles both standard and right-to-left layout orientations.
Declaration
protected override void OnMouseMove(MouseEventArgs e)Parameters
|
System.Windows.Forms.MouseEventArgs
e
A System.Windows.Forms.MouseEventArgs that contains the event data. |
Overrides
OnMouseUp(MouseEventArgs)
Handles the mouse up event by resetting the selected value visual layer. This method clears the temporary selected value visual feedback, returning the rating items to their standard display state after the mouse button is released.
Declaration
protected override void OnMouseUp(MouseEventArgs e)Parameters
|
System.Windows.Forms.MouseEventArgs
e
A System.Windows.Forms.MouseEventArgs that contains the event data. |
Overrides
OnNotifyPropertyChanged(String)
Handles property change notifications and triggers appropriate visual updates. This method responds to key property changes that affect visual appearance, layout, or value representation, ensuring that the rating display remains synchronized with property values.
Declaration
protected override void OnNotifyPropertyChanged(string propertyName)Parameters
|
System.String
propertyName
The name of the property that changed. |
Overrides
OnPropertyChanged(RadPropertyChangedEventArgs)
Handles property change notifications for the rating element. This method responds to specific property changes such as RightToLeft and Bounds, ensuring that visual updates and layout recalculations occur when necessary.
Declaration
protected override void OnPropertyChanged(RadPropertyChangedEventArgs e)Parameters
|
RadPropertyChangedEventArgs
e
A RadPropertyChangedEventArgs that contains the event data. |
Overrides
OnValueChanged(EventArgs)
Raises the ValueChanged event with the specified event arguments. This method is called when the rating value has been successfully changed to notify any registered event handlers.
Declaration
protected virtual void OnValueChanged(EventArgs e)Parameters
|
System.EventArgs
e
An System.EventArgs that contains the event data. |
OnValueChanging(ValueChangingEventArgs)
Raises the ValueChanging event with the specified event arguments. This method is called before a value change occurs, allowing handlers to validate or cancel the change.
Declaration
protected virtual void OnValueChanging(ValueChangingEventArgs e)Parameters
|
ValueChangingEventArgs
e
A ValueChangingEventArgs that contains the event data and allows cancellation of the change. |
PaintValueLevel()
Updates the visual representation of the rating value by painting the appropriate visual layers. This method is called when the rating value changes to ensure that the visual display accurately reflects the current value state across all rating items.
Declaration
protected virtual void PaintValueLevel()ResetValues()
Resets all interactive visual states including hover effects, selected value feedback, and tooltip display. This method clears temporary visual states and hides tooltips, typically called when interaction ends or when the mouse leaves the rating element area.
Declaration
protected void ResetValues()UpdateCurrentValue(Int32, RatingVisualElement, MouseEventArgs)
Calculates and returns the rating value based on the current mouse position within a specific rating visual element. This method performs complex calculations considering the current selection mode, direction, orientation, and relative mouse position to determine the appropriate rating value for user feedback and selection.
Declaration
protected virtual double UpdateCurrentValue(int currentIndex, RatingVisualElement element, MouseEventArgs e)Parameters
|
System.Int32
currentIndex
The index of the current rating item being interacted with. |
|
RatingVisualElement
element
The specific RatingVisualElement under the mouse cursor. |
|
System.Windows.Forms.MouseEventArgs
e
The System.Windows.Forms.MouseEventArgs containing the current mouse position. |
Returns
|
System.Double
A double representing the calculated rating value based on the mouse interaction. |
VisualElementsBounds()
Calculates and returns the bounding rectangle that encompasses all rating visual elements. This method determines the overall area occupied by the rating items, which is used for hit testing, layout calculations, and interaction boundary detection.
Declaration
protected Rectangle VisualElementsBounds()Returns
|
System.Drawing.Rectangle
A System.Drawing.Rectangle representing the bounds of all rating visual elements. |
Events
ValueChanged
Occurs after the value of the rating element has been changed through user interaction or programmatic assignment. This event is fired after the value change is complete and all related processing has been finished.
Declaration
public event EventHandler ValueChangedEvent Type
|
System.EventHandler
|
ValueChanging
Occurs before the value of the rating element is changed, providing an opportunity to cancel the change. This cancelable event allows validation or conditional approval of value changes before they are applied, enabling custom business logic or user confirmation scenarios.
Declaration
public event ValueChangingEventHandler ValueChangingEvent Type
|
ValueChangingEventHandler
|
