Class RadTimeSpanPickerElement

Represents the main element that provides the time span picker functionality, serving as the core implementation for the RadTimeSpanPicker control with support for masked text input and popup-based editing.

Inheritance
System.Object
DisposableObject
RadObject
RadElement
VisualElement
RadComponentElement
RadItem
RadEditorElement
EditorBaseElement
PopupEditorBaseElement
RadTimeSpanPickerElement
Inherited Members
System.Object.Equals(System.Object)
System.Object.Equals(System.Object, System.Object)
System.Object.ReferenceEquals(System.Object, System.Object)
System.Object.GetHashCode()
System.Object.GetType()
System.Object.MemberwiseClone()
Namespace: Telerik.WinControls.UI
Assembly: Telerik.WinControls.UI.dll

Syntax

public class RadTimeSpanPickerElement : PopupEditorBaseElement, INotifyPropertyChanged, ICustomTypeDescriptor, ISupportSystemSkin, IComponent, IDisposable, IBindableComponent, ISupportDrag, ISupportDrop, IShortcutProvider, IStylableElement, IStylableNode, IInputEditor, IValueEditor, ISupportInitialize, ITimeSpanPickerContentElementOwner
Remarks

RadTimeSpanPickerElement extends PopupEditorBaseElement to provide comprehensive time span editing capabilities through both direct text input using masked edit boxes and popup-based selection interfaces. It implements ITimeSpanPickerContentElementOwner to coordinate with popup content components.

The element manages multiple child components including masked edit boxes for text input, dropdown buttons for popup access, and spin buttons for increment/decrement operations. It supports various edit modes defined by TimeSpanEditMode to control user interaction patterns.

Key features include culture-aware formatting, customizable step values for different time components, validation through minimum and maximum value constraints, and comprehensive event handling for value changes and popup lifecycle management.

Constructors

RadTimeSpanPickerElement()

Initializes a new instance of the RadTimeSpanPickerElement class with default settings.

Declaration
public RadTimeSpanPickerElement()

Fields

PopupMinSizeProperty

Identifies the PopupMinSize dependency property that specifies the minimum size constraints for the popup window.

Declaration
public static RadProperty PopupMinSizeProperty
Field Value
RadProperty

Properties

Culture

Gets or sets the culture information used for formatting and parsing time span values. This affects how time components are displayed and interpreted based on regional settings.

Declaration
public CultureInfo Culture { get; set; }
Property Value
System.Globalization.CultureInfo

Implements

DaysStep

Gets or sets the increment step for the days component when modifying time span values using spin buttons or keyboard navigation.

Declaration
public int DaysStep { get; set; }
Property Value
System.Int32

DownButton

Gets the button element used to decrease time span component values.

Declaration
public RadRepeatArrowElement DownButton { get; }
Property Value
RadRepeatArrowElement

DropDownAnimationEnabled

Gets or sets a value indicating whether the popup displays with animation effects when opening and closing.

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

DropDownButton

Gets the dropdown button element that opens the time span selection popup when clicked.

Declaration
public RadTimeDropDownButtonElement DropDownButton { get; }
Property Value
RadTimeDropDownButtonElement

EditMode

Gets or sets the edit mode that determines how users can interact with the control to modify time span values. This property controls whether editing is done through text input, popup interface, or both.

Declaration
public TimeSpanEditMode EditMode { get; set; }
Property Value
TimeSpanEditMode

EditorElement

Gets or sets the editor element reference. This property is hidden from serialization to prevent stack overflow exceptions

Declaration
public override RadItem EditorElement { get; set; }
Property Value
RadItem

Overrides

EnableNullValueInput

Gets or sets a value indicating whether users can set the time span value to null using keyboard shortcuts. When enabled, users can press Ctrl+Del or Ctrl+0 to clear the current value.

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

Format

Gets or sets the format string that determines how time span values are displayed and parsed in the text input. The format string controls which time components are shown and their formatting patterns.

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

Implements

HoursStep

Gets or sets the increment step for the hours component when modifying time span values using spin buttons or keyboard navigation.

Declaration
public int HoursStep { get; set; }
Property Value
System.Int32

MaskedEditBox

Gets the masked edit box element that provides text input functionality with time span validation and formatting.

Declaration
public virtual RadMaskedEditBoxElement MaskedEditBox { get; }
Property Value
RadMaskedEditBoxElement

MaxValue

Gets or sets the maximumvalue that can be selected in the control. Values above this maximum will not be accepted or displayed.

Declaration
public TimeSpan MaxValue { get; set; }
Property Value
System.TimeSpan

MillisecondsStep

Gets or sets the increment step for the milliseconds component when modifying time span values using spin buttons or keyboard navigation.

Declaration
public int MillisecondsStep { get; set; }
Property Value
System.Int32

MinutesStep

Gets or sets the increment step for the minutes component when modifying time span values using spin buttons or keyboard navigation.

Declaration
public int MinutesStep { get; set; }
Property Value
System.Int32

MinValue

Gets or sets the minimumvalue that can be selected in the control. Values below this minimum will not be accepted or displayed.

Declaration
public TimeSpan MinValue { get; set; }
Property Value
System.TimeSpan

NullText

Gets or sets the placeholder text displayed when the control has no time span value set. This text provides guidance to users about the expected input format.

Declaration
[RadDefaultValue("NullText", typeof(RadTextBoxItem))]
[RadDescription("NullText", typeof(RadTextBoxItem))]
public string NullText { get; set; }
Property Value
System.String

PopupContentElement

Gets the popup content element that provides the interactive time span selection interface within the popup.

Declaration
public virtual ITimeSpanPickerContentElement PopupContentElement { get; }
Property Value
ITimeSpanPickerContentElement

PopupForm

Gets the popup form that contains the time span selection interface.

Declaration
public RadTimeSpanPickerPopup PopupForm { get; }
Property Value
RadTimeSpanPickerPopup

PopupMinSize

Gets or sets the minimum size constraints for the popup window that contains the time span selection interface.

Declaration
public Size PopupMinSize { get; set; }
Property Value
System.Drawing.Size

ReadOnly

Gets or sets a value indicating whether the control is in read-only mode. When true, users cannot modify the time span value through either text input or popup interaction.

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

SecondsStep

Gets or sets the increment step for the seconds component when modifying time span values using spin buttons or keyboard navigation.

Declaration
public int SecondsStep { get; set; }
Property Value
System.Int32

ShowDropDownButton

Gets or sets a value indicating whether the dropdown button that opens the popup is visible and accessible to users.

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

ShowSpinButtons

Gets or sets a value indicating whether the spin buttons for incrementing and decrementing time span components are visible. When enabled, users can use up/down buttons to modify the selected time component.

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

SpinButtonsStackLayout

Gets the stack layout element that serves as a container for the spin buttons (up and down arrows).

Declaration
public StackLayoutElement SpinButtonsStackLayout { get; }
Property Value
StackLayoutElement

TextAlign

Gets or sets the text alignment of within the masked edit box.

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

ThemeEffectiveType

Gets the type used for theming this element, allowing it to inherit styles from RadTimePickerElement.

Declaration
protected override Type ThemeEffectiveType { get; }
Property Value
System.Type

Overrides

TimeSpanProvider

Gets the mask provider that manages time span formatting and editing behavior for the masked edit box. This provider controls how editing is performed for each time component (days, hours, minutes, seconds, milliseconds).

Declaration
public MaskTimeSpanProvider TimeSpanProvider { get; }
Property Value
MaskTimeSpanProvider

Implements

UpButton

Gets the increment button element used to increase time span component values.

Declaration
public RadRepeatArrowElement UpButton { get; }
Property Value
RadRepeatArrowElement

Value

Gets or sets the value of the RadTimeSpanPickerElement. The value can be null if no time span is selected or if null input is enabled.

Declaration
public override object Value { get; set; }
Property Value
System.Object

Overrides
Implements

Methods

CloseOwnerPopup()

Closes the popup window when called by the popup content element.

Declaration
public void CloseOwnerPopup()
Implements

CreateButtonsStack()

Creates the stack layout element that serves as a container for the up and down arrow buttons.

Declaration
protected virtual StackLayoutElement CreateButtonsStack()
Returns
StackLayoutElement

A new instance of StackLayoutElement configured for vertical button arrangement.

CreateChildElements()

Creates and initializes all child elements including the masked edit box, dropdown button, spin buttons, and layout containers.

Declaration
protected override void CreateChildElements()
Overrides

CreateDownButton()

Creates the decrement button element used to decrease time span component values.

Declaration
protected virtual RadRepeatArrowElement CreateDownButton()
Returns
RadRepeatArrowElement

A RadRepeatArrowElement configured as a down arrow button.

CreateDropDownButtonElement()

Creates the dropdown button element that opens the time span selection popup when clicked.

Declaration
protected virtual RadTimeDropDownButtonElement CreateDropDownButtonElement()
Returns
RadTimeDropDownButtonElement

A new instance of RadTimeDropDownButtonElement.

CreateMaskedEditBoxElement()

Creates the masked edit box element that provides text input functionality with time span validation and formatting.

Declaration
protected virtual RadMaskedEditBoxElement CreateMaskedEditBoxElement()
Returns
RadMaskedEditBoxElement

A new instance of RadMaskedEditBoxElement configured for time span input.

CreatePopupForm()

Creates the popup form instance that contains the time span selection interface. Override this method to provide a popup with specialized content for time span selection.

Declaration
protected override RadPopupControlBase CreatePopupForm()
Returns
RadPopupControlBase

A new instance of RadTimeSpanPickerPopup configured for this element.
Overrides

CreateUpButton()

Creates the increment button element used to increase time span component values.

Declaration
protected virtual RadRepeatArrowElement CreateUpButton()
Returns
RadRepeatArrowElement

A RadRepeatArrowElement configured as an up arrow button.

DisposeManagedResources()

Releases managed resources by unsubscribing from events and disposing child elements.

Declaration
protected override void DisposeManagedResources()
Overrides

GetInitialPopupSize()

Gets the initial size for the popup when it's first displayed, providing a large default that will be adjusted based on content.

Declaration
protected override Size GetInitialPopupSize()
Returns
System.Drawing.Size

A System.Drawing.Size representing the initial popup dimensions.
Overrides

GetPopupSize(RadPopupControlBase, Boolean)

Calculates and returns the optimal size for the popup based on its content and minimum size constraints.

Declaration
protected override Size GetPopupSize(RadPopupControlBase popup, bool measure)
Parameters
RadPopupControlBase popup

The popup control to calculate size for.
System.Boolean measure

Indicates whether to perform measurement calculations.
Returns
System.Drawing.Size

A System.Drawing.Size representing the calculated popup dimensions.
Overrides

InitializeFields()

Initializes the default field values for the time span picker element.

Declaration
protected override void InitializeFields()
Overrides

MaskEditBox_Click(Object, EventArgs)

Handles the click event from the masked edit box and forwards it to subscribers.

Declaration
protected virtual void MaskEditBox_Click(object sender, EventArgs e)
Parameters
System.Object sender

The source of the event.
System.EventArgs e

Event data.

MaskEditBox_KeyDown(Object, KeyEventArgs)

Handles the key down event from the masked edit box and forwards it to subscribers.

Declaration
protected virtual void MaskEditBox_KeyDown(object sender, KeyEventArgs e)
Parameters
System.Object sender

The source of the event.
System.Windows.Forms.KeyEventArgs e

Event data containing key information.

MaskEditBox_KeyPress(Object, KeyPressEventArgs)

Handles the key press event from the masked edit box and forwards it to subscribers.

Declaration
protected virtual void MaskEditBox_KeyPress(object sender, KeyPressEventArgs e)
Parameters
System.Object sender

The source of the event.
System.Windows.Forms.KeyPressEventArgs e

Event data containing key press information.

MaskEditBox_MouseUp(Object, MouseEventArgs)

Handles the mouse up event from the masked edit box and forwards it to subscribers.

Declaration
protected virtual void MaskEditBox_MouseUp(object sender, MouseEventArgs e)
Parameters
System.Object sender

The source of the event.
System.Windows.Forms.MouseEventArgs e

Event data containing mouse information.

MaskEditBox_MouseWheel(Object, MouseEventArgs)

Handles the mouse wheel event from the masked edit box and forwards it to subscribers.

Declaration
protected virtual void MaskEditBox_MouseWheel(object sender, MouseEventArgs e)
Parameters
System.Object sender

The source of the event.
System.Windows.Forms.MouseEventArgs e

Event data containing mouse wheel information.

MeasureOverride(SizeF)

Measures the desired size of the element within the available space, ensuring proper layout constraints are respected.

Declaration
protected override SizeF MeasureOverride(SizeF availableSize)
Parameters
System.Drawing.SizeF availableSize

The available space for the element.
Returns
System.Drawing.SizeF

The desired size of the element.
Overrides

OnLoaded()

Handles the element loaded event to configure the masked edit box border visibility.

Declaration
protected override void OnLoaded()
Overrides

OnPopupClosed(Object, RadPopupClosedEventArgs)

Handles the popup closed event to update element states and clear popup content selection.

Declaration
protected virtual void OnPopupClosed(object sender, RadPopupClosedEventArgs args)
Parameters
System.Object sender

The source of the event.
RadPopupClosedEventArgs args

Event data for the popup closed event.

OnPopupClosing(RadPopupClosingEventArgs)

Handles the popup closing event and prevents premature closure when the mouse is over the dropdown button.

Declaration
protected override void OnPopupClosing(RadPopupClosingEventArgs e)
Parameters
RadPopupClosingEventArgs e

Event data containing close reason and cancellation information.
Overrides

OnPopupOpened(Object, EventArgs)

Handles the popup opened event to update element states and set focus to the popup form.

Declaration
protected virtual void OnPopupOpened(object sender, EventArgs e)
Parameters
System.Object sender

The source of the event.
System.EventArgs e

Event data.

OnPropertyChanged(RadPropertyChangedEventArgs)

Handles property change events and updates RTL support for child elements when the RightToLeft property changes.

Declaration
protected override void OnPropertyChanged(RadPropertyChangedEventArgs e)
Parameters
RadPropertyChangedEventArgs e

Event data containing property change information.
Overrides

OnValueChanged(Object, EventArgs)

Handles the value changed event from the masked edit box, tracks analytics, and forwards the event to subscribers.

Declaration
protected virtual void OnValueChanged(object sender, EventArgs e)
Parameters
System.Object sender

The source of the event.
System.EventArgs e

Event data.

OnValueChanging(Object, CancelEventArgs)

Handles the value changing event from the masked edit box and forwards it to subscribers.

Declaration
protected virtual void OnValueChanging(object sender, CancelEventArgs e)
Parameters
System.Object sender

The source of the event.
System.ComponentModel.CancelEventArgs e

Event data containing cancellation information.

SetupEditMode(TimeSpanEditMode)

Configures the element's behavior based on the specified edit mode, controlling text box read-only state and button visibility.

Declaration
protected virtual void SetupEditMode(TimeSpanEditMode timeSpanEditMode)
Parameters
TimeSpanEditMode timeSpanEditMode

The edit mode to apply to the element.

UnwireEvents()

Unsubscribes from all previously subscribed events to prevent memory leaks and unwanted event handling.

Declaration
protected virtual void UnwireEvents()

UpdatePopupLocalizationStrings()

Updates the localization strings used in the popup content to reflect the current localization provider settings.

Declaration
protected virtual void UpdatePopupLocalizationStrings()

WireEvents()

Subscribes to necessary events from child elements and external providers to coordinate element behavior.

Declaration
protected virtual void WireEvents()

Events

Click

Occurs when the element is clicked.

Declaration
public event EventHandler Click
Event Type
System.EventHandler

KeyDown

Occurs when the user presses a key while the element has focus.

Declaration
public event KeyEventHandler KeyDown
Event Type
System.Windows.Forms.KeyEventHandler

KeyPress

Occurs when the user presses and releases a key while the element has focus.

Declaration
public event KeyPressEventHandler KeyPress
Event Type
System.Windows.Forms.KeyPressEventHandler

KeyUp

Occurs when the user releases a key while the element has focus.

Declaration
public event KeyEventHandler KeyUp
Event Type
System.Windows.Forms.KeyEventHandler

MouseUp

Occurs when the user releases a mouse button while the mouse pointer is over the element.

Declaration
public event MouseEventHandler MouseUp
Event Type
System.Windows.Forms.MouseEventHandler

MouseWheel

Occurs when the mouse wheel moves while the element has focus.

Declaration
public event MouseEventHandler MouseWheel
Event Type
System.Windows.Forms.MouseEventHandler

ValueChanged

Occurs when the time span value has been successfully changed.

Declaration
public event EventHandler ValueChanged
Event Type
System.EventHandler

ValueChanging

Occurs when the time span value is about to be changed and allows the operation to be canceled.

Declaration
public event CancelEventHandler ValueChanging
Event Type
System.ComponentModel.CancelEventHandler

Extension Methods