Class RadRangeSelectorElement
Represents the main visual element of the RadRangeSelector control that provides range selection functionality with thumb controls, scale elements, and integration with associated controls for synchronized data visualization.
Inheritance
Inherited Members
Namespace: Telerik.WinControls.UI
Assembly: Telerik.WinControls.UI.dll
Syntax
public class RadRangeSelectorElement : RangeSelectorVisualElementWithOrientation, INotifyPropertyChanged, ICustomTypeDescriptor, ISupportSystemSkin, IComponent, IDisposable, IBindableComponent, ISupportDrag, ISupportDrop, IShortcutProvider, IStylableElement, IStylableNode, IPrimitiveElement, IShapedElement, IFillElement, IBorderElement, IBoxStyle, IBoxElement, IDrawFillElement, IImageElement, ITextPrimitive, ITextProviderConstructors
RadRangeSelectorElement()
Declaration
public RadRangeSelectorElement()Properties
AssociatedElement
Gets or sets the RadElement that is associated with this range selector for synchronized operations.
Declaration
public RadElement AssociatedElement { get; set; }Property Value
|
RadElement
|
BodyElement
Gets the RangeSelectorBodyElement that contains the main visual and interactive components including thumb controls, selection area, and view container for the associated control.
Declaration
public RangeSelectorBodyElement BodyElement { get; }Property Value
|
RangeSelectorBodyElement
|
BottomRightScales
Gets the collection of scale container elements positioned at the bottom (horizontal orientation) or right (vertical orientation). These scales provide additional visual indicators and value references for the range selection area.
Declaration
public List<RangeSelectorScaleContainerElement> BottomRightScales { get; }Property Value
|
System.Collections.Generic.List<RangeSelectorScaleContainerElement>
|
EnableFastScrolling
Gets or sets a value indicating whether fast scrolling mode is enabled for improved performance during rapid navigation. When enabled, scroll operations may defer certain updates to maintain responsiveness during high-frequency interactions. This is particularly useful for large data sets where continuous updates might impact performance.
Declaration
public bool EnableFastScrolling { get; set; }Property Value
|
System.Boolean
|
EndRange
Gets or sets the ending value of the selected range as a percentage (0-100). This value represents the position of the right thumb in horizontal orientation or top thumb in vertical orientation.
Declaration
public float EndRange { get; set; }Property Value
|
System.Single
|
LayoutsRefreshRate
Gets or sets the refresh rate for layout operations in milliseconds. This property controls how frequently layout updates occur during interactive operations, balancing visual responsiveness with performance requirements.
Declaration
public int LayoutsRefreshRate { get; set; }Property Value
|
System.Int32
|
MinSelectionLength
Gets or sets the minimum allowed length of the selection range as a percentage (3-99). This constraint prevents users from creating invalid or too-narrow selections that might cause usability issues. The value affects both programmatic and interactive range modifications.
Declaration
public int MinSelectionLength { get; set; }Property Value
|
System.Int32
|
Orientation
Gets or sets the orientation of the range selector, determining the layout direction and thumb movement patterns. System.Windows.Forms.Orientation.Horizontal arranges controls horizontally with left-right thumb movement, while System.Windows.Forms.Orientation.Vertical arranges controls vertically with up-down thumb movement.
Declaration
public Orientation Orientation { get; set; }Property Value
|
System.Windows.Forms.Orientation
|
RangeSelectorViewZoomEnd
Gets or sets the ending position of the zoom view within the range selector's viewport as a percentage (0-100). This property controls which portion of the associated control's data is visible in the range selector's background view. Changes to this value update the corresponding scroll element position.
Declaration
public float RangeSelectorViewZoomEnd { get; set; }Property Value
|
System.Single
|
RangeSelectorViewZoomStart
Gets or sets the starting position of the zoom view within the range selector's viewport as a percentage (0-100). This property controls which portion of the associated control's data is visible in the range selector's background view. Changes to this value update the corresponding scroll element position.
Declaration
public float RangeSelectorViewZoomStart { get; set; }Property Value
|
System.Single
|
ScrollSelectorElement
Gets the RangeSelectorScrollElement that provides scroll functionality and zoom controls for navigating through larger data sets within the range selector view.
Declaration
public RangeSelectorScrollElement ScrollSelectorElement { get; }Property Value
|
RangeSelectorScrollElement
|
ScrollViewPosition
Gets or sets the position where the scroll view element is displayed within the range selector layout. TopLeft positions it at the top (horizontal) or left (vertical), while BottomRight positions it at the bottom (horizontal) or right (vertical).
Declaration
public ViewPosition ScrollViewPosition { get; set; }Property Value
|
ViewPosition
|
SelectionRectangleEnd
Gets or sets the ending position of the selection rectangle as a percentage (0-100). The selection rectangle provides an alternative selection mechanism and represents the larger of the two selection values. Values are constrained to the 0-100 range for valid percentage representation.
Declaration
public float SelectionRectangleEnd { get; set; }Property Value
|
System.Single
|
SelectionRectangleStart
Gets or sets the starting position of the selection rectangle as a percentage (0-100). The selection rectangle provides an alternative selection mechanism and represents the smaller of the two selection values. Values are constrained to the 0-100 range for valid percentage representation.
Declaration
public float SelectionRectangleStart { get; set; }Property Value
|
System.Single
|
ShowButtons
Gets or sets a value indicating whether the range selector's thumb handles and navigation buttons are visible and interactive. When disabled, users cannot directly manipulate the thumbs to change the selected range, but the range can still be modified programmatically. This property is useful for display-only scenarios where range selection should be controlled externally.
Declaration
public bool ShowButtons { get; set; }Property Value
|
System.Boolean
|
ShowScroll
Gets or sets a value indicating whether the scroll element is visible and functional. The scroll element allows users to navigate through larger data sets by adjusting the zoom view. Returns false if no associated element is set or if the associated element does not implement IRangeSelectorElement.
Declaration
public bool ShowScroll { get; set; }Property Value
|
System.Boolean
|
StartRange
Gets or sets the starting value of the selected range as a percentage (0-100). This value represents the position of the left thumb in horizontal orientation or bottom thumb in vertical orientation.
Declaration
public float StartRange { get; set; }Property Value
|
System.Single
|
TopLeftScales
Gets the collection of scale container elements positioned at the top (horizontal orientation) or left (vertical orientation). These scales provide visual indicators and value references for the range selection area.
Declaration
public List<RangeSelectorScaleContainerElement> TopLeftScales { get; }Property Value
|
System.Collections.Generic.List<RangeSelectorScaleContainerElement>
|
TotalZoomFactor
Gets the calculated total zoom factor that combines the base zoom factor with view zoom settings. This read-only property represents the effective zoom level applied to the associated element, taking into account both the ZoomFactor and the current zoom start/end positions. Returns 1.0 if no associated element implementing IRangeSelectorElement is present.
Declaration
public float TotalZoomFactor { get; }Property Value
|
System.Single
|
UpdateMode
Gets or sets the update mode that controls when the associated control receives range change notifications. Immediate provides real-time updates during thumb dragging operations, while Deferred delays updates until the user completes the range modification.
Declaration
public UpdateMode UpdateMode { get; set; }Property Value
|
UpdateMode
|
ZoomFactor
Gets or sets a zoom factor that affects the visual scaling of the associated control within the range selector view. Higher values increase the zoom level, making data appear larger within the background view area. This factor is combined with view zoom settings to calculate the total zoom effect.
Declaration
public float ZoomFactor { get; set; }Property Value
|
System.Single
|
Methods
ArrangeOverride(SizeF)
Arranges child elements within the final size allocated to the range selector element. Positions scales, body element, and scroll element according to the current orientation and scroll view position settings.
Declaration
protected override SizeF ArrangeOverride(SizeF finalSize)Parameters
|
System.Drawing.SizeF
finalSize
The final area within the parent that this element should use to arrange itself and its children. |
Returns
|
System.Drawing.SizeF
The actual System.Drawing.SizeF used by the element after arranging its children. |
Overrides
CreateChildElements()
Creates the child elements that compose the range selector, including the main body element and scroll element. Establishes the fundamental visual structure by adding core components to the element hierarchy.
Declaration
protected override void CreateChildElements()Overrides
InitializeElements()
Initializes the range selector elements with settings from the associated control and configures scale elements. This method rebuilds the element hierarchy based on the current associated element, processes scale initialization events, and establishes the proper visual structure for range selection operations.
Declaration
public virtual void InitializeElements()InitializeFields()
Initializes the fields of the range selector element by setting stretch behavior for both horizontal and vertical directions. This ensures the element can properly fill its available space in both dimensions.
Declaration
protected override void InitializeFields()Overrides
MeasureOverride(SizeF)
Measures the desired size of the range selector element and its children based on the available space and orientation. Calculates space requirements for scales, body element, and scroll element, arranging them according to the current orientation.
Declaration
protected override SizeF MeasureOverride(SizeF availableSize)Parameters
|
System.Drawing.SizeF
availableSize
The available space that the parent element can allocate to this element. |
Returns
|
System.Drawing.SizeF
The desired System.Drawing.SizeF that this element requires to display its content properly. |
Overrides
OnLoaded()
Called when the element is loaded and visible, triggering initialization of child elements. This ensures that all range selector components are properly configured when the element becomes active.
Declaration
protected override void OnLoaded()Overrides
OnNotifyPropertyChanged(String)
Handles property change notifications and triggers appropriate updates for orientation, zoom, and range changes. This method coordinates updates across child elements when critical properties change, ensuring consistent visual state.
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 from the base class and triggers additional processing for specific properties. Ensures that right-to-left property changes are properly propagated through the notification system.
Declaration
protected override void OnPropertyChanged(RadPropertyChangedEventArgs e)Parameters
|
RadPropertyChangedEventArgs
e
A RadPropertyChangedEventArgs that contains information about the changed property. |
Overrides
OnScaleInitializing(ScaleInitializingEventArgs)
Raises the ScaleInitializing event with the specified event arguments. This method is called when a scale element is being initialized, providing access to the scale for customization.
Declaration
public virtual void OnScaleInitializing(ScaleInitializingEventArgs e)Parameters
|
ScaleInitializingEventArgs
e
A ScaleInitializingEventArgs that contains the event data including the scale element being initialized. |
OnSelectionChanged(EventArgs)
Raises the SelectionChanged event with the specified event arguments. This method is called when the entire selection range has been successfully changed to notify registered handlers.
Declaration
public virtual void OnSelectionChanged(EventArgs e)Parameters
|
System.EventArgs
e
An System.EventArgs that contains the event data. |
OnSelectionChanging(RangeSelectorSelectionChangingEventArgs)
Raises the SelectionChanging event with the specified event arguments. This method is called when the entire selection range is about to change, allowing registered handlers to validate or cancel the change.
Declaration
public virtual void OnSelectionChanging(RangeSelectorSelectionChangingEventArgs e)Parameters
|
RangeSelectorSelectionChangingEventArgs
e
A RangeSelectorSelectionChangingEventArgs that contains the event data and allows cancellation of the change. |
OnThumbLeftValueChanged(EventArgs)
Raises the ThumbLeftValueChanged event with the specified event arguments. This method is called when the left thumb value has been successfully changed to notify registered handlers.
Declaration
public virtual void OnThumbLeftValueChanged(EventArgs e)Parameters
|
System.EventArgs
e
An System.EventArgs that contains the event data. |
OnThumbLeftValueChanging(ValueChangingEventArgs)
Raises the ThumbLeftValueChanging event with the specified event arguments. This method is called before the left thumb value changes, allowing registered handlers to validate or cancel the change.
Declaration
public virtual void OnThumbLeftValueChanging(ValueChangingEventArgs e)Parameters
|
ValueChangingEventArgs
e
A ValueChangingEventArgs that contains the event data and allows cancellation of the change. |
OnThumbRightValueChanged(EventArgs)
Raises the ThumbRightValueChanged event with the specified event arguments. This method is called when the right thumb value has been successfully changed to notify registered handlers.
Declaration
public virtual void OnThumbRightValueChanged(EventArgs e)Parameters
|
System.EventArgs
e
An System.EventArgs that contains the event data. |
OnThumbRightValueChanging(ValueChangingEventArgs)
Raises the ThumbRightValueChanging event with the specified event arguments. This method is called before the right thumb value changes, allowing registered handlers to validate or cancel the change.
Declaration
public virtual void OnThumbRightValueChanging(ValueChangingEventArgs e)Parameters
|
ValueChangingEventArgs
e
A ValueChangingEventArgs that contains the event data and allows cancellation of the change. |
Events
ScaleInitializing
Occurs when a scale element is being initialized, providing access to customize scale appearance and behavior. This cancelable event allows handlers to modify scale properties, change positioning, or prevent specific scales from being displayed.
Declaration
public event ScaleInitializingEventHandler ScaleInitializingEvent Type
|
ScaleInitializingEventHandler
|
SelectionChanged
Occurs when the entire selection range has been successfully changed. This event is fired after all range modifications are complete and the range selector is in a consistent state.
Declaration
public event EventHandler SelectionChangedEvent Type
|
System.EventHandler
|
SelectionChanging
Occurs when the entire selection range is about to change, providing an opportunity to validate or cancel the modification. This cancelable event is triggered when both thumbs move simultaneously or when the range is modified programmatically, allowing for comprehensive range validation before the change is applied.
Declaration
public event RangeSelectorSelectionChangingEventHandler SelectionChangingEvent Type
|
RangeSelectorSelectionChangingEventHandler
|
ThumbLeftValueChanged
Occurs when the value of the left thumb has been successfully changed. This event is fired after the left thumb position update is complete and all related processing has finished.
Declaration
public event EventHandler ThumbLeftValueChangedEvent Type
|
System.EventHandler
|
ThumbLeftValueChanging
Occurs when the value of the left thumb is about to change, providing an opportunity to validate or cancel the modification. This cancelable event allows handlers to implement custom validation logic before the left thumb position is updated.
Declaration
public event ValueChangingEventHandler ThumbLeftValueChangingEvent Type
|
ValueChangingEventHandler
|
ThumbRightValueChanged
Occurs when the value of the right thumb has been successfully changed. This event is fired after the right thumb position update is complete and all related processing has finished.
Declaration
public event EventHandler ThumbRightValueChangedEvent Type
|
System.EventHandler
|
ThumbRightValueChanging
Occurs when the value of the right thumb is about to change, providing an opportunity to validate or cancel the modification. This cancelable event allows handlers to implement custom validation logic before the right thumb position is updated.
Declaration
public event ValueChangingEventHandler ThumbRightValueChangingEvent Type
|
ValueChangingEventHandler
|
