Class RadRangeSelector

A range selector control that allows users to select a range within a data set by manipulating thumb controls. The RadRangeSelector provides visual range selection capabilities with associated control integration, supporting both horizontal and vertical orientations with customizable update modes and scale elements.

Inheritance
System.Object
RadControl
RadRangeSelector
Inherited Members
Namespace: Telerik.WinControls.UI
Assembly: Telerik.WinControls.UI.dll

Syntax

public class RadRangeSelector : RadControl, INotifyPropertyChanged, ISupportInitializeNotification, IComponentTreeHandler, ILayoutHandler, IPCHost, IAnalyticsProvider, ISupportInitialize

Constructors

RadRangeSelector()

Initializes a new instance of the RadRangeSelector class with default settings. Sets up event wiring and disables item tooltips by default.

Declaration
public RadRangeSelector()

Properties

AssociatedControl

Gets or sets the control that is associated with this range selector for synchronized range operations. The associated control will be updated when the range selection changes, typically used with chart controls. Setting this to null removes the association, and setting it to another RadRangeSelector is ignored.

Declaration
public RadControl AssociatedControl { get; set; }
Property Value
RadControl

AutoSize

Gets or sets a value indicating whether the range selector control automatically adjusts its size to fit its content. When enabled, the control will resize itself based on its content requirements and layout constraints.

Declaration
public override bool AutoSize { get; }
Property Value
System.Boolean

Overrides

BackColor

This property is not relevant for this class. The RadRangeSelector consists of multiple visual elements and separate settings are provided to customize their appearance.

Declaration
public override Color BackColor { get; set; }
Property Value
System.Drawing.Color

Overrides

DefaultSize

Gets the default size of the range selector control when no explicit size is specified. The default dimensions are optimized for typical range selection scenarios.

Declaration
protected override Size DefaultSize { get; }
Property Value
System.Drawing.Size

The default System.Drawing.Size of 400x150 pixels for the control.

EndRange

Gets or sets the ending value of the selected range within the range selector. This value represents the position of the right thumb in horizontal orientation or the top thumb in vertical orientation.

Declaration
public float EndRange { get; set; }
Property Value
System.Single

ForeColor

This property is not relevant for this class. The RadRangeSelector consists of multiple visual elements and separate settings are provided to customize their appearance.

Declaration
public override Color ForeColor { get; set; }
Property Value
System.Drawing.Color

Overrides

Orientation

Gets or sets the orientation of the range selector, determining whether it displays horizontally or vertically. Changing the orientation automatically swaps the width and height dimensions of the control.

Declaration
public Orientation Orientation { get; set; }
Property Value
System.Windows.Forms.Orientation

RangeSelectorElement

Gets the main RadRangeSelectorElement that provides the core functionality and visual representation. This element encapsulates all range selection logic, thumb controls, and visual rendering.

Declaration
public RadRangeSelectorElement RangeSelectorElement { get; }
Property Value
RadRangeSelectorElement

RangeSelectorViewZoomEnd

Gets or sets the end position of the zoom view within the range selector's viewport. This property controls which portion of the associated data is visible in the range selector's background view.

Declaration
public float RangeSelectorViewZoomEnd { get; set; }
Property Value
System.Single

RangeSelectorViewZoomStart

Gets or sets the start position of the zoom view within the range selector's viewport. This property controls which portion of the associated data is visible in the range selector's background view.

Declaration
public float RangeSelectorViewZoomStart { get; set; }
Property Value
System.Single

ShowButtons

Gets or sets a value indicating whether the range selector's thumb handles are visible and can be manipulated by users. When disabled, users cannot interact with the thumb controls to change the selected range.

Declaration
public bool ShowButtons { get; set; }
Property Value
System.Boolean

ShowItemToolTips

Gets or sets a value indicating whether ToolTips are shown for the RadItem objects contained in the range selector. By default, tooltips are disabled for range selector elements to prevent interference with range selection operations.

Declaration
public override bool ShowItemToolTips { get; set; }
Property Value
System.Boolean

Overrides

StartRange

Gets or sets the starting value of the selected range within the range selector. This value represents the position of the left thumb in horizontal orientation or the bottom thumb in vertical orientation.

Declaration
public float StartRange { get; set; }
Property Value
System.Single

Text

This property is not relevant for this class.

Declaration
public override string Text { get; set; }
Property Value
System.String

Overrides

UpdateMode

Gets or sets the update mode that determines when the associated control is updated during range selection operations. Immediate updates the control continuously during thumb movement, while Deferred updates only when the thumb is released.

Declaration
public UpdateMode UpdateMode { get; set; }
Property Value
UpdateMode

Methods

CreateChildItems(RadElement)

Creates the child elements by instantiating the main RadRangeSelectorElement and adding it to the element tree. This establishes the core visual and functional structure of the range selector.

Declaration
protected override void CreateChildItems(RadElement parent)
Parameters
RadElement parent

The parent RadElement that will contain the child elements.
Overrides

CreateRangeSelectorElement()

Creates and returns a new instance of RadRangeSelectorElement. Override this method to provide a custom range selector element implementation.

Declaration
protected virtual RadRangeSelectorElement CreateRangeSelectorElement()
Returns
RadRangeSelectorElement

A new RadRangeSelectorElement instance.

Dispose(Boolean)

Releases the unmanaged resources used by the RadRangeSelector and optionally releases the managed resources. Unwires all event handlers before disposing the control.

Declaration
protected override void Dispose(bool disposing)
Parameters
System.Boolean disposing

true to release both managed and unmanaged resources; false to release only unmanaged resources.
Overrides

InitializeRootElement(RootRadElement)

Initializes the root element by setting vertical stretch behavior and calling the base implementation. This ensures the range selector can properly fill its container vertically.

Declaration
protected override void InitializeRootElement(RootRadElement rootElement)
Parameters
RootRadElement rootElement

The root RootRadElement to initialize.
Overrides

OnLoad(Size)

Called when the control is loaded with the specified desired size. Applies themes to the element tree to ensure proper visual styling.

Declaration
protected override void OnLoad(Size desiredSize)
Parameters
System.Drawing.Size desiredSize

The desired System.Drawing.Size for the control.
Overrides

OnRightToLeftChanged(EventArgs)

Overrides the right-to-left change notification to prevent default processing. The range selector handles right-to-left layout changes through its internal element structure.

Declaration
protected override void OnRightToLeftChanged(EventArgs e)
Parameters
System.EventArgs e

An System.EventArgs that contains the event data.
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 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 any registered event 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 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 any registered event 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 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 any registered event handlers.

Declaration
public virtual void OnThumbRightValueChanged(EventArgs e)
Parameters
System.EventArgs e

OnThumbRightValueChanging(ValueChangingEventArgs)

Raises the ThumbRightValueChanging event with the specified event arguments. This method is called before the right thumb value changes, allowing 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.

UnwireEvents()

Unwires event handlers from the range selector element and associated control. Unsubscribes from all previously wired events to prevent memory leaks.

Declaration
protected virtual void UnwireEvents()

WireEvents()

Wires event handlers to the range selector element's events if the element exists. Subscribes to thumb value changing/changed events, selection events, and scale initialization events.

Declaration
protected virtual void WireEvents()

Events

ScaleInitializing

Occurs when a scale element within the range selector is being initialized. This event provides access to scale elements during their creation, allowing for customization of scale appearance and behavior.

Declaration
public event ScaleInitializingEventHandler ScaleInitializing
Event Type
ScaleInitializingEventHandler

SelectionChanged

Occurs when the entire selection range has been changed successfully. This event is fired after all selection changes are complete and the range selector is in a consistent state.

Declaration
public event EventHandler SelectionChanged
Event Type
System.EventHandler

SelectionChanging

Occurs when the entire selection range is about to change, providing an opportunity to cancel the change. This event is triggered when both thumbs move simultaneously or when the selected range is modified programmatically.

Declaration
public event RangeSelectorSelectionChangingEventHandler SelectionChanging
Event Type
RangeSelectorSelectionChangingEventHandler

ThumbLeftValueChanged

Occurs when the value of the left thumb has been changed successfully. This event is fired after the value change is complete and all related processing has been finished.

Declaration
public event EventHandler ThumbLeftValueChanged
Event Type
System.EventHandler

ThumbLeftValueChanging

Occurs when the value of the left thumb is about to change, providing an opportunity to cancel or modify the change. This event allows validation and conditional approval of left thumb movements before they are applied.

Declaration
public event ValueChangingEventHandler ThumbLeftValueChanging
Event Type
ValueChangingEventHandler

ThumbRightValueChanged

Occurs when the value of the right thumb has been changed successfully. This event is fired after the value change is complete and all related processing has been finished.

Declaration
public event EventHandler ThumbRightValueChanged
Event Type
System.EventHandler

ThumbRightValueChanging

Occurs when the value of the right thumb is about to change, providing an opportunity to cancel or modify the change. This event allows validation and conditional approval of right thumb movements before they are applied.

Declaration
public event ValueChangingEventHandler ThumbRightValueChanging
Event Type
ValueChangingEventHandler

Extension Methods