Class SfDateTimeEdit

Represents a Windows control that allows the user to select a date and a time and to display the date and time with a specified format. It offers different editing mode and also allows to set null value.

Inheritance

System.Object

BaseControl

SfDateTimeEdit

Implements

IThemeProvider

IVisualStyle

System.IDisposable

Inherited Members

BaseControl.CanApplyTheme

BaseControl.CanOverrideStyle

BaseControl.ControlName

BaseControl.GetActiveThemeName()

BaseControl.IsVisualStyleEnabled

BaseControl.IThemeProvider.BaseThemeName

BaseControl.IVisualStyle.VisualTheme

BaseControl.ThemeName

BaseControl.ThemeNameChanged

Namespace: Syncfusion.WinForms.Input

Assembly: Syncfusion.SfInput.WinForms.dll

Syntax

public class SfDateTimeEdit : BaseControl, IThemeProvider, IVisualStyle, IDisposable

Remarks

The SfDateTimeEdit control makes it easy to work with dates and times because it handles a lot of the data validation automatically.

Examples

This example shows how to initialize the SfDateTimeEdit control.

       
// Create a new SfDateTimeEdit control and initialize it.
SfDateTimeEdit sfDateTimeEdit1 = new SfDateTimeEdit();
// Configure control to allow null value
sfDateTimeEdit1.AllowNull = true;
// Set the MinDate and MaxDate.
sfDateTimeEdit1.MinDateTime = new DateTime(2017, 1, 1);
sfDateTimeEdit1.MaxDateTime = new DateTime(2019, 12, 31);
// Set the CustomFormat string. 
sfDateTimeEdit1.Format = "MMMM - dd - yyyy";       /// sfDateTimeEdit1.DateTimePattern = DateTimePattern.Custom;
// Display the control as an up-down control.
sfDateTimeEdit1.ShowUpDown = true;

Constructors

SfDateTimeEdit()

Initializes a new instance of the SfDateTimeEdit class.

Declaration

public SfDateTimeEdit()

Properties

AccessibilityEnabled

Gets or sets a value indicating whether the control should enable Accessibility support in SfCalendar

Declaration

public bool AccessibilityEnabled { get; set; }

Property Value

Type
System.Boolean

AllowNull

Gets or sets a value indicating whether SfDateTimeEdit allows null value.

Declaration

public bool AllowNull { get; set; }

Property Value

Type
System.Boolean

Remarks

None Button of DropDown Calendar will be visible always when AllowNull is True

AllowValueChangeOnMouseWheel

Gets or sets a value indicating whether the Value change can occur on mouse wheel.

Declaration

public bool AllowValueChangeOnMouseWheel { get; set; }

Property Value

Type
System.Boolean

Remarks

AllowValueChangeOnMouseWheel applicable only for Mask.

Culture

Gets or sets the System.Globalization.CultureInfo that represents formatting for date time in SfDateTimeEdit.

Declaration

public CultureInfo Culture { get; set; }

Property Value

Type
System.Globalization.CultureInfo

DateTimeEditingMode

Gets or sets the editing mode that decides how to insert the input values for SfDateTimeEdit from keyboard.

Declaration

public DateTimeEditingMode DateTimeEditingMode { get; set; }

Property Value

Type
DateTimeEditingMode

DateTimeIcon

Gets or sets the image for the date and time icon in the dropdown button of the SfDateTimeEdit control.

Declaration

public Image DateTimeIcon { get; set; }

Property Value

Type	Description
System.Drawing.Image	An System.Drawing.Image object representing the icon for the date and time dropdown button. If set to null, the default icon will be used.

Remarks

The assigned image will be used as the icon in the dropdown button of the SfDateTimeEdit control. The image provided should ideally be 16x16 pixels. If the image exceeds this size, it will be automatically resized to 16x16 pixels. Note that custom images may not fully support the hover, highlighted, and pressed states of the dropdown button, similar to how the default calendar icon behaves with and without themes. For complete customization of the dropdown button area by your own, you can override the DrawDropDownButton(Graphics) method.

Examples

SfDateTimeEdit dateTimeEdit = new SfDateTimeEdit();
dateTimeEdit.DateTimeIcon = Image.FromFile("custom_icon.png");

DateTimePattern

Gets or sets the display pattern that decides whether Selected Value displayed in Short, Long or Custom pattern.

Declaration

public DateTimePattern DateTimePattern { get; set; }

Property Value

Type
DateTimePattern

DateTimeText

Gets or sets the Display Text for Value field of SfDateTimeEdit. Value will be updated based on the changes in DateTimeText.

Declaration

public string DateTimeText { get; set; }

Property Value

Type
System.String

DefaultSize

Gets the size of the SfDateTimeEdit control.

Declaration

protected override Size DefaultSize { get; }

Property Value

Type	Description
System.Drawing.Size	Returns the default size

DropDownButtonWidth

Gets or sets the width of the DropDownButton in SfDateTimeEdit

Declaration

[Obsolete("DropDownButtonWidth is deprecated. This property has no effect. You can no longer change the size of the drop-down button.")]
public int DropDownButtonWidth { get; set; }

Property Value

Type
System.Int32

DropDownPopupAlignment

Gets or sets a side value that indicating DropDown Popup alignment relative to the SfDateTimeEdit control.

Declaration

public DropDownPopupAlignment DropDownPopupAlignment { get; set; }

Property Value

Type
DropDownPopupAlignment

DropDownSize

Gets or sets a size of DropDown Popup Calendar in SfDateTimeEdit

Declaration

public Size DropDownSize { get; set; }

Property Value

Type
System.Drawing.Size

Font

Overrides the base class font property.

Declaration

public override Font Font { get; set; }

Property Value

Type
System.Drawing.Font

ForeColor

Gets or sets the foreground color of the SfDateTimeEdit control.

Declaration

public override Color ForeColor { get; set; }

Property Value

Type
System.Drawing.Color

Format

Gets or sets the Format that decides how the Selected Value will be displayed for Custom.

Declaration

public string Format { get; set; }

Property Value

Type
System.String

Remarks

Format applicable only for Custom

InterceptArrowKeys

Gets or sets a value indicating whether the user can use the ARROW keys to change values and navigate between date time fields in SfDateTimeEdit.

Declaration

public bool InterceptArrowKeys { get; set; }

Property Value

Type
System.Boolean

Remarks

Set InterceptArrowKeys to false restrict Up and Down Arrow keys to change the Value and Right and Left Arrow keys to navigate between date time fields of SfDateTimeEdit

IsDropDownOpen

Gets a value indicating whether the DropDown Popup is in open state or not in SfDateTimeEdit.

Declaration

public bool IsDropDownOpen { get; }

Property Value

Type
System.Boolean

MaxDateTime

Gets or sets a value indicating maximum value constraint for SfDateTimeEdit. This restricts to set the Value greater than specific DateTime.

Declaration

public DateTime MaxDateTime { get; set; }

Property Value

Type
System.DateTime

Remarks

MaxDateTime should be greater than MinDateTime of SfDateTimeEdit.

MinDateTime

Gets or sets a value indicating minimum value constraint for SfDateTimeEdit. This restricts to set the Value lesser than specific DateTime.

Declaration

public DateTime MinDateTime { get; set; }

Property Value

Type
System.DateTime

Remarks

MinDateTime should be lesser than MaxDateTime of SfDateTimeEdit.

MonthCalendar

Gets the DropDown SfCalendar used to pick the date for SfDateTimeEdit.

Declaration

public SfCalendar MonthCalendar { get; }

Property Value

Type
SfCalendar

ReadOnly

Gets or sets a value indicating whether text in the DateTimeEdit is read-only.

Declaration

public bool ReadOnly { get; set; }

Property Value

Type
System.Boolean

Remarks

Set ReadOnly as true restricts the text editing in SfDateTimeEdit and user can change the Value only by clicking UpDown buttons or pick the date from the DropDown SfCalendar.

RightToLeft

Gets or sets a value indicating whether control's elements are aligned in right-to-left layout.

Declaration

public RightToLeft RightToLeft { get; set; }

Property Value

Type
System.Windows.Forms.RightToLeft

SelectedField

Gets or sets a value indicating whether selected field of the SfDateTimeEdit.

Declaration

public DateTimeField SelectedField { get; set; }

Property Value

Type
DateTimeField

ShowDropDown

Gets or sets a value indicating whether the DropDown button visible.

Declaration

public bool ShowDropDown { get; set; }

Property Value

Type
System.Boolean

ShowToolTip

Gets or sets a value that determines whether a tooltip can be displayed or not when the mouse hovers over the control.

Declaration

public bool ShowToolTip { get; set; }

Property Value

Type
System.Boolean

ShowUpDown

Gets or sets a value indicating whether the UpDown buttons are visible.

Declaration

public bool ShowUpDown { get; set; }

Property Value

Type
System.Boolean

Style

Gets the DateTimeEditVisualStyle value used to customize the appearance of the SfDateTimeEdit.

Declaration

public DateTimeEditVisualStyle Style { get; }

Property Value

Type
DateTimeEditVisualStyle

Text

Gets or Sets the Text to allow for setting of the value through string. Also, return a formatted Value when getting the text.

Declaration

public override string Text { get; set; }

Property Value

Type
System.String

ToolTipOption

Gets or sets the options for the tooltip to be displayed when hovering on the control.

Declaration

public ToolTipOptions ToolTipOption { get; set; }

Property Value

Type
ToolTipOptions

ToolTipText

Gets or sets the custom text for SfDateTimeEdit tooltip.

Declaration

public string ToolTipText { get; set; }

Property Value

Type
System.String

ValidationOption

Gets or sets the Validation Option that decides how the value will be changed when validation failed.

Declaration

public ValidationResetOption ValidationOption { get; set; }

Property Value

Type
ValidationResetOption

Remarks

Validation will take place when user press Enter key and LostFocus from the SfDateTimeEdit control or Pick the Date from the DropDown SfCalendar. If validation failed, Value will reset based on ValidationOption

Value

Gets or sets the selected date time value for the SfDateTimeEdit.

Declaration

public DateTime? Value { get; set; }

Property Value

Type
System.Nullable<System.DateTime>

Remarks

Value can be set as null when AllowNull is true.

Watermark

Gets or sets the Watermark Text that displays in SfDateTimeEdit when the Value is null.

Declaration

public string Watermark { get; set; }

Property Value

Type
System.String

Remarks

Watermark text applicable when DateTimeEditingMode is Default.

Methods

ClosePopup()

Close the DropDown SfCalendar if it is already opened.

Declaration

public void ClosePopup()

CreateAccessibilityInstance()

Creates a new accessibility object in SfDateTimeEdit.

Declaration

protected override AccessibleObject CreateAccessibilityInstance()

Returns

Type	Description
System.Windows.Forms.AccessibleObject	A new System.Windows.Forms.AccessibleObject for the SfDateTimeEdit, when AccessibilityEnabled is set as true

Dispose(Boolean)

Releases the unmanaged resources used by the SfDateTimeEdit and its child controls and optionally releases the managed resources.

Declaration

protected override void Dispose(bool disposing)

Parameters

Type	Name	Description
System.Boolean	disposing	true to release both managed and unmanaged resources; false to release only unmanaged resources.

DrawDropDownButton(Graphics)

Renders the dropdown button within the control. This method is responsible for drawing the visual representation of the dropdown button using the specified System.Drawing.Graphics object. It can be overridden in derived classes to customize the appearance of the dropdown button.

Declaration

protected virtual void DrawDropDownButton(Graphics g)

Parameters

Type	Name	Description
System.Drawing.Graphics	g	The System.Drawing.Graphics object used to perform drawing operations. This provides methods for drawing shapes, text, and images.

Remarks

Override this method in a derived class to customize how the dropdown button is rendered.
Ensure that base implementation is called if you want to retain the existing drawing logic and extend it.

GetControlName(String)

Helps to apply the ControlName settings in control

Declaration

public override string GetControlName(string controlName)

Parameters

Type	Name	Description
System.String	controlName	The name of the control

Returns

Type	Description
System.String	The name of the control

Overrides

BaseControl.GetControlName(String)

OnBackColorChanged(EventArgs)

Raises the SfDateTimeEdit back color changed event.

Declaration

protected override void OnBackColorChanged(EventArgs e)

Parameters

Type	Name	Description
System.EventArgs	e	An System.EventArgs that contains the event data.

OnCanApplyThemeChanged(Boolean)

Helps to apply the CanApplyTheme settings in control

Declaration

public override void OnCanApplyThemeChanged(bool canApplyTheme)

Parameters

Type	Name	Description
System.Boolean	canApplyTheme	Indicates whether ThemeName can be applied from the SkinManager control.

Overrides

BaseControl.OnCanApplyThemeChanged(Boolean)

OnCanOverrideStyleChanged(Boolean)

Helps to apply the CanOverrideStyle settings in control

Declaration

public override void OnCanOverrideStyleChanged(bool canOverrideStyle)

Parameters

Type	Name	Description
System.Boolean	canOverrideStyle	Indicates whether the sample level customization settings can be retained or overridden with Theme settings.

Overrides

BaseControl.OnCanOverrideStyleChanged(Boolean)

OnEnabledChanged(EventArgs)

Raises the SfDateTimeEdit enable changed event.

Declaration

protected override void OnEnabledChanged(EventArgs e)

Parameters

Type	Name	Description
System.EventArgs	e	An System.EventArgs that contains the event data.

OnFontChanged(EventArgs)

Raises the SfDateTimeEdit font changed event.

Declaration

protected override void OnFontChanged(EventArgs e)

Parameters

Type	Name	Description
System.EventArgs	e	An System.EventArgs that contains the event data.

OnGotFocus(EventArgs)

Raises the SfDateTimeEdit GotFocus event.

Declaration

protected override void OnGotFocus(EventArgs e)

Parameters

Type	Name	Description
System.EventArgs	e	An System.EventArgs that contains the event data.

OnLayout(LayoutEventArgs)

Raises the System.Windows.Forms.Control.Layout event.

Declaration

protected override void OnLayout(LayoutEventArgs levent)

Parameters

Type	Name	Description
System.Windows.Forms.LayoutEventArgs	levent	A System.Windows.Forms.LayoutEventArgs that contains the event data.

OnLostFocus(EventArgs)

Raises the SfDateTimeEdit LostFocus event.

Declaration

protected override void OnLostFocus(EventArgs e)

Parameters

Type	Name	Description
System.EventArgs	e	An System.EventArgs that contains the event data.

OnMouseDown(MouseEventArgs)

Raises the System.Windows.Forms.Control.MouseDown event.

Declaration

protected override void OnMouseDown(MouseEventArgs e)

Parameters

Type	Name	Description
System.Windows.Forms.MouseEventArgs	e	A System.Windows.Forms.MouseEventArgs that contains the event data.

OnMouseEnter(EventArgs)

Raises the SfDateTimeEdit Mouse Hover event.

Declaration

protected override void OnMouseEnter(EventArgs e)

Parameters

Type	Name	Description
System.EventArgs	e	An System.EventArgs that contains the event data.

OnMouseLeave(EventArgs)

Raises the SfDateTimeEdit Mouse Leave event.

Declaration

protected override void OnMouseLeave(EventArgs e)

Parameters

Type	Name	Description
System.EventArgs	e	An System.EventArgs that contains the event data.s

OnPaint(PaintEventArgs)

Paints the background of the control.

Declaration

protected override void OnPaint(PaintEventArgs e)

Parameters

Type	Name	Description
System.Windows.Forms.PaintEventArgs	e	A System.Windows.Forms.PaintEventArgs that contains information about the SfDateTimeEdit to paint.

OnPaintBackground(PaintEventArgs)

Paints the background of the control.

Declaration

protected override void OnPaintBackground(PaintEventArgs paintevent)

Parameters

Type	Name	Description
System.Windows.Forms.PaintEventArgs	paintevent	A System.Windows.Forms.PaintEventArgs that contains information about the control to paint.

OnParentChanged(EventArgs)

Invoke when the parent has been changed

Declaration

protected override void OnParentChanged(EventArgs e)

Parameters

Type	Name	Description
System.EventArgs	e	Represents the base class for classes that contain event data, and provides a value to use for events that do not include event data.

OnParentRightToLeftChanged(EventArgs)

Raises the SfDateTimeEdit Parent RightToLeft changed event.

Declaration

protected override void OnParentRightToLeftChanged(EventArgs e)

Parameters

Type	Name	Description
System.EventArgs	e	An System.EventArgs that contains the event data.

OnRightToLeftChanged(EventArgs)

Raises the SfDateTimeEdit Right to left changed event.

Declaration

protected override void OnRightToLeftChanged(EventArgs e)

Parameters

Type	Name	Description
System.EventArgs	e	An System.EventArgs that contains the event data.

OnSizeChanged(EventArgs)

Raises the System.Windows.Forms.Control.SizeChanged event.

Declaration

protected override void OnSizeChanged(EventArgs e)

Parameters

Type	Name	Description
System.EventArgs	e	An System.EventArgs that contains the event data.

OnThemeNameChanged(String)

Helps to apply the ThemeName settings in control

Declaration

public override void OnThemeNameChanged(string themeName)

Parameters

Type	Name	Description
System.String	themeName	The ThemeName of the Control

Overrides

BaseControl.OnThemeNameChanged(String)

ProcessCmdKey(ref Message, Keys)

Processes a command key.

Declaration

protected override bool ProcessCmdKey(ref Message msg, Keys keyData)

Parameters

Type	Name	Description
System.Windows.Forms.Message	msg	A System.Windows.Forms.Message, passed by reference, that represents the Win32 message to process.
System.Windows.Forms.Keys	keyData	One of the System.Windows.Forms.Keys values that represents the key to process

Returns

Type	Description
System.Boolean	true if the keystroke was processed and consumed by the control; otherwise, false to allow further processing.

RaiseThemeChanged(Object, ThemeChangedEventArgs)

Raises the ThemeNameChanged and ThemeChanged event when theme name changed.

Declaration

protected override void RaiseThemeChanged(object sender, ThemeChangedEventArgs args)

Parameters

Type	Name	Description
System.Object	sender	The sender value.
ThemeChangedEventArgs	args	A ThemeChangedEventArgs contains the event data.

Overrides

BaseControl.RaiseThemeChanged(Object, ThemeChangedEventArgs)

ResetRightToLeft()

Resets the RightToLeft back to its default value.

Declaration

public override void ResetRightToLeft()

ShowPopup()

Opens the DropDown SfCalendar to pick the date for Value

Declaration

public void ShowPopup()

Events

DateTimeValidating

Occurs before Value property change

Declaration

public event ValidatingEventHandler DateTimeValidating

Event Type

Type
ValidatingEventHandler

Remarks

Value change occurs press Enter key after complete editing or Pick the date from the DropDown Calendar

DropDownClosed

Occurs when the DropDown Calendar is closed.

Declaration

public event EventHandler DropDownClosed

Event Type

Type
System.EventHandler

Remarks

DropDown calendar will get close when DropDown calendar control lost its focus by press on any other control or after pick the selected date from DropDown calendar for SfDateTimeEdit. DropDown Calendar will get close even we press the below combinations.

ALT + Down
ALT + UP

DropDownClosing

Occurs before close the DropDown Calendar.

Declaration

public event CancelEventHandler DropDownClosing

Event Type

Type
System.ComponentModel.CancelEventHandler

Remarks

DropDownOpened

Occurs when the DropDown Calendar opened.

Declaration

public event EventHandler DropDownOpened

Event Type

Type
System.EventHandler

Remarks

DropDown calendar get open when click on the DropDown icon in SfDateTimeEdit or by press ALT + DOWN arrow keys.

DropDownOpening

Occurs before open the DropDown Calendar.

Declaration

public event CancelEventHandler DropDownOpening

Event Type

Type
System.ComponentModel.CancelEventHandler

Remarks

DropDown calendar get open when click on the DropDown icon in SfDateTimeEdit or by press ALT + DOWN arrow keys.

ThemeChanged

Occurs when theme name of the SfCalendar has changed.

Declaration

public event ThemeChangedEventHandler ThemeChanged

Event Type

Type
ThemeChangedEventHandler

ToolTipOpened

The TooltipOpened event is raised when the tooltip associated with the SfDateTimeEdit control has been opened and is visible to the user.

Declaration

public event EventHandler<DateTimeEditToolTipOpenedEventArgs> ToolTipOpened

Event Type

Type
System.EventHandler<DateTimeEditToolTipOpenedEventArgs>

ToolTipOpening

The TooltipOpening event is raised just before the tooltip associated with the SfDateTimeEdit control is opened and becomes visible to the user.

Declaration

public event EventHandler<DateTimeEditToolTipOpeningEventArgs> ToolTipOpening

Event Type

Type
System.EventHandler<DateTimeEditToolTipOpeningEventArgs>

ValueChanged

Occurs when the Value changed.

Declaration

public event DateTimeValueChangedEventHandler ValueChanged

Event Type

Type
DateTimeValueChangedEventHandler

Implements

IThemeProvider

IVisualStyle

System.IDisposable