Class SfDatePicker

Represents a control that allows users to pick a date from the drop-down list and edit the date using a masked input.

Inheritance
System.Object
SfDropDownBase
DateTimePickerBase
SfDatePicker
Implements
System.IDisposable
Inherited Members
Namespace: Syncfusion.UI.Xaml.Editors
Assembly: Syncfusion.Editors.WinUI.dll
Syntax
public class SfDatePicker : DateTimePickerBase, IDisposable
Examples

The below examples shows, how to initialize the SfDatePicker control.

<editors:SfDatePicker
    PlaceHolderText="Enter your date of birth."/>

Constructors

SfDatePicker()

Initializes a new instance of the SfDatePicker class.

Declaration
public SfDatePicker()

Fields

BlackoutDatesProperty

Identifies BlackoutDates dependency property.

Declaration
public static readonly DependencyProperty BlackoutDatesProperty
Field Value
Type Description
Microsoft.UI.Xaml.DependencyProperty

The identifier for the BlackoutDates dependency property.

CalendarIdentifierProperty

Identifies CalendarIdentifier dependency property.

Declaration
public static readonly DependencyProperty CalendarIdentifierProperty
Field Value
Type
Microsoft.UI.Xaml.DependencyProperty

DayFormatProperty

Identifies DayFormat dependency property.

Declaration
public static readonly DependencyProperty DayFormatProperty
Field Value
Type Description
Microsoft.UI.Xaml.DependencyProperty

The identifier for the DayFormat dependency property.

DisplayDateFormatProperty

Identifies DisplayDateFormat dependency property.

Declaration
public static readonly DependencyProperty DisplayDateFormatProperty
Field Value
Type Description
Microsoft.UI.Xaml.DependencyProperty

The identifier for the DisplayDateFormat dependency property.

DropDownHeaderProperty

Identifies DropDownHeader dependency property.

Declaration
public static readonly DependencyProperty DropDownHeaderProperty
Field Value
Type Description
Microsoft.UI.Xaml.DependencyProperty

The identifier for the DropDownHeader dependency property.

DropDownHeaderTemplateProperty

Identifies DropDownHeaderTemplate dependency property.

Declaration
public static readonly DependencyProperty DropDownHeaderTemplateProperty
Field Value
Type Description
Microsoft.UI.Xaml.DependencyProperty

The identifier for the DropDownHeaderTemplate dependency property.

ItemContainerStyleProperty

Identifies ItemContainerStyle dependency property.

Declaration
public static readonly DependencyProperty ItemContainerStyleProperty
Field Value
Type Description
Microsoft.UI.Xaml.DependencyProperty

The identifier for the ItemContainerStyle dependency property.

ItemHeightProperty

Identifies ItemHeight dependency property.

Declaration
public static readonly DependencyProperty ItemHeightProperty
Field Value
Type Description
Microsoft.UI.Xaml.DependencyProperty

The identifier for the ItemHeight dependency property.

ItemTemplateProperty

Identifies ItemTemplate dependency property.

Declaration
public static readonly DependencyProperty ItemTemplateProperty
Field Value
Type Description
Microsoft.UI.Xaml.DependencyProperty

The identifier for the ItemTemplate dependency property.

ItemTemplateSelectorProperty

Identifies ItemTemplateSelector dependency property.

Declaration
public static readonly DependencyProperty ItemTemplateSelectorProperty
Field Value
Type Description
Microsoft.UI.Xaml.DependencyProperty

The identifier for the ItemTemplateSelector dependency property.

ItemWidthProperty

Identifies ItemWidth dependency property.

Declaration
public static readonly DependencyProperty ItemWidthProperty
Field Value
Type Description
Microsoft.UI.Xaml.DependencyProperty

The identifier for the ItemWidth dependency property.

MaxDateProperty

Identifies MaxDate dependency property.

Declaration
public static readonly DependencyProperty MaxDateProperty
Field Value
Type Description
Microsoft.UI.Xaml.DependencyProperty

The identifier for the MaxDate dependency property.

MaxItemWidthProperty

Identifies MaxItemWidth dependency property.

Declaration
public static readonly DependencyProperty MaxItemWidthProperty
Field Value
Type Description
Microsoft.UI.Xaml.DependencyProperty

The identifier for the MaxItemWidth dependency property.

MinDateProperty

Identifies MinDate dependency property.

Declaration
public static readonly DependencyProperty MinDateProperty
Field Value
Type Description
Microsoft.UI.Xaml.DependencyProperty

The identifier for the MinDate dependency property.

MinItemWidthProperty

Identifies MinItemWidth dependency property.

Declaration
public static readonly DependencyProperty MinItemWidthProperty
Field Value
Type Description
Microsoft.UI.Xaml.DependencyProperty

The identifier for the MinItemWidth dependency property.

MonthFormatProperty

Identifies MonthFormat dependency property.

Declaration
public static readonly DependencyProperty MonthFormatProperty
Field Value
Type Description
Microsoft.UI.Xaml.DependencyProperty

The identifier for the MonthFormat dependency property.

PlaceholderTextProperty

Identifies PlaceholderText dependency property.

Declaration
public static readonly DependencyProperty PlaceholderTextProperty
Field Value
Type Description
Microsoft.UI.Xaml.DependencyProperty

The identifier for the PlaceholderText dependency property.

SelectedDateProperty

Identifies SelectedDate dependency property.

Declaration
public static readonly DependencyProperty SelectedDateProperty
Field Value
Type Description
Microsoft.UI.Xaml.DependencyProperty

The identifier for the SelectedDate dependency property.

ShowColumnHeadersProperty

Identifies ShowColumnHeaders dependency property.

Declaration
public static readonly DependencyProperty ShowColumnHeadersProperty
Field Value
Type Description
Microsoft.UI.Xaml.DependencyProperty

The identifier for the ShowColumnHeaders dependency property.

ShowDropDownHeaderProperty

Identifies ShowDropDownHeader dependency property.

Declaration
public static readonly DependencyProperty ShowDropDownHeaderProperty
Field Value
Type Description
Microsoft.UI.Xaml.DependencyProperty

The identifier for the ShowDropDownHeader dependency property.

VisibleItemsCountProperty

Identifies VisibleItemsCount dependency property.

Declaration
public static readonly DependencyProperty VisibleItemsCountProperty
Field Value
Type Description
Microsoft.UI.Xaml.DependencyProperty

The identifier for the VisibleItemsCount dependency property.

YearFormatProperty

Identifies YearFormat dependency property.

Declaration
public static readonly DependencyProperty YearFormatProperty
Field Value
Type Description
Microsoft.UI.Xaml.DependencyProperty

The identifier for the YearFormat dependency property.

Properties

BlackoutDates

Gets or sets the collection of restricted dates, that is not allowed to select.

Declaration
public DateTimeOffsetCollection BlackoutDates { get; set; }
Property Value
Type Description
DateTimeOffsetCollection

The default value is null.
Examples

The following example shows how to add date in BlackoutDates collections.

SfDatePicker datepicker = new SfDatePicker();
datepicker.BlackoutDates = new DateTimeOffsetCollection();
datepicker.BlackoutDates.Add(DateTimeOffset.Now.AddDays(-7));
Exceptions
Type Condition
System.ArgumentOutOfRangeException

Blackout date should not be selected.

CalendarIdentifier

Gets or sets the calendar system to use.

Declaration
public string CalendarIdentifier { get; set; }
Property Value
Type Description
System.String

The default calendar is GregorianCalendar.
Remarks

Set the CalendarIdentifier property to specify the calendar system used by the SfDatePicker. The SfDatePicker supports all calendar systems in the CalendarIdentifiers class except System.Globalization.JapaneseCalendar and Lunar type calendars. Mask editing is supported only for System.Globalization.GregorianCalendar.

Examples

The following example shows how to set the CalendarIdentifier in SfDatePicker.

datePicker.CalendarIdentifier = Windows.Globalization.CalendarIdentifiers.Julian;

DayFormat

Gets or sets the display format for the day values shown in drop down.

Declaration
public string DayFormat { get; set; }
Property Value
Type Description
System.String

The default value is {}{day.integer}.
Remarks

For the complete list of format templates and format patterns, refer DateTimeFormatter class documentation.

Examples

Here's a SfDatePicker formatted using format templates and format string. Both will produce same results.

DisplayDateFormat

Gets or sets the pattern used to format the SelectedDate in editor.

Declaration
public string DisplayDateFormat { get; set; }
Property Value
Type Description
System.String

The default value is "d".
Remarks

Refer DayFormat, MonthFormat and YearFormat to format the date which is shown in drop-down.

DropDownHeader

Gets or sets the content of drop-down's header.

Declaration
public object DropDownHeader { get; set; }
Property Value
Type Description
System.Object

The default value is null.
Remarks

The drop-down header will be automatically collapsed, when value is null. You can set a data template for the Header value by using the DropDownHeaderTemplate property.

Examples
<editors:SfDatePicker x:Name="datepicker" DropdownHeader="Select a date" />

DropDownHeaderTemplate

Gets or sets the DataTemplate used to display the content of the drop-down's header.

Declaration
public DataTemplate DropDownHeaderTemplate { get; set; }
Property Value
Type Description
Microsoft.UI.Xaml.DataTemplate

The default value is null.
Remarks

The drop-down header will be automatically collapsed, when DropDownHeader is null. The DropDownHeader value is the data context of this DataTemplate.

Examples

The following example shows how to define a DropDownHeaderTemplate for the SfDatePicker control.

<Page.Resources>
    <DataTemplate x:Name="DropdownHeaderTemplate">
        <Grid Background="PaleGreen">
            <TextBlock
                HorizontalAlignment="Center"
                VerticalAlignment="Center"
                Foreground="Red"
                Text="{Binding}" />
        </Grid>
    </DataTemplate>
</Page.Resources>
<Grid>
    <editors:SfDatePicker
        x:Name="datepicker"
        DropdownHeaderTemplate="{StaticResource DropdownHeaderTemplate}" />
</Grid>

ItemContainerStyle

Gets or sets the Microsoft.UI.Xaml.Style that is applied to the SpinnerItem generated for each item in SpinnerColumnView.

Declaration
public Style ItemContainerStyle { get; set; }
Property Value
Type Description
Microsoft.UI.Xaml.Style

The default value is null.
Examples

The following example shows how to define a ItemContainerStyle for the SfDatePicker control.

 <Page.Resources>
     <Style x:Key="ItemContainerStyle" TargetType="syncfusion:SpinnerItem">
         <Setter Property="FontStyle" Value="Oblique" />
     </Style>
 </Page.Resources>
 <Grid>
     <editors:SfDatePicker
          x:Name="datepicker"
          ItemContainerStyle="{StaticResource ItemContainerStyle}" />
 </Grid>

ItemHeight

Gets or sets the uniform height for all SpinnerItem in SpinnerColumnView.

Declaration
public double ItemHeight { get; set; }
Property Value
Type Description
System.Double

The default value is 40.
Remarks

ItemHeight does not supports System.Double.NaN value.

ItemTemplate

Gets or sets the DataTemplate used to display each item in SpinnerColumnView.

Declaration
public DataTemplate ItemTemplate { get; set; }
Property Value
Type Description
Microsoft.UI.Xaml.DataTemplate

The default value is null.
Remarks

The DateTimeFieldItemInfo is the data context of this DataTemplate.

Examples

The following example shows how to define a ItemTemplate for the SfDatePicker control.

<Page.Resources>
    <DataTemplate x:Name="ItemTemplate">
        <Grid
            HorizontalAlignment="Center"
            VerticalAlignment="Center"
            Background="pink">
            <TextBlock
                Foreground="Red"
                Text="{Binding DisplayText}" />
        </Grid>
    </DataTemplate>
</Page.Resources>
<Grid>
    <editors:SfDatePicker
        x:Name="datepicker"
        ItemTemplate="{StaticResource ItemTemplate}" />
</Grid>

ItemTemplateSelector

Gets or sets the custom logic for choosing a template used to display each item.

Declaration
public DataTemplateSelector ItemTemplateSelector { get; set; }
Property Value
Type Description
Microsoft.UI.Xaml.Controls.DataTemplateSelector

The default is null.
Remarks

DateTimeFieldItemInfo is the data context of this DataTemplateSelector.

Examples

The following example shows how to define a ItemTemplateSelector for the SfDatePicker control.

<Application.Resources>
    <DataTemplate x:Name="SelectorItemTemplate1">
        <Grid Background="Pink">
            <TextBlock Foreground="Yellow" Text="{Binding DisplayText}" />
        </Grid>
    </DataTemplate>
    <DataTemplate x:Name="SelectorItemTemplate2">
        <Grid Background="Orange">
            <TextBlock Foreground="Red" Text="{Binding DisplayText}" />
        </Grid>
    </DataTemplate>
</Application.Resources>
<Page.Resources>
    <local:DayTemplateSelector x:Key="dayTemplateSelector" />
</Page.Resources>
<Grid>
    <editors:SfDatePicker
        x:Name="datepicker"
        ItemTemplateSelector="{StaticResource dayTemplateSelector}" />
</Grid>
public MainPage()
{
   this.InitializeComponent();
   ObservableCollection<string> dayCollection = new ObservableCollection<string>();
   for (int i = 1; i <= 31; i++)
   {
       dayCollection.Add(i.ToString());
   }
   dayColumn.ItemsSource = dayCollection;
}

public class DayTemplateSelector : DataTemplateSelector
{
   protected override DataTemplate SelectTemplateCore(object item, DependencyObject container)
   {
     if (item != null)
     {
        DateTimeFieldItemInfo dateTimeField = item as DateTimeFieldItemInfo;
        if (dateTimeField.Field == DateTimeField.Day)
        {
           if (int.Parse(dateTimeField.DisplayText) < 15)
               return Application.Current.Resources["SelectorItemTemplate1"] as DataTemplate;
           else
               return Application.Current.Resources["SelectorItemTemplate2"] as DataTemplate;
        }
     }
     return base.SelectTemplateCore(item, container);
   }
}

ItemWidth

Gets or sets the uniform width for all SpinnerItem in SpinnerColumnView.

Declaration
public double ItemWidth { get; set; }
Property Value
Type Description
System.Double

The default value is 80.
Remarks

If ItemWidth is NaN, item will automatically resize according to its content.

MaxDate

Gets or sets the maximum Gregorian date available for picking.

Declaration
public DateTimeOffset MaxDate { get; set; }
Property Value
Type Description
System.DateTimeOffset

The default value is 12/31/2120.

MaxItemWidth

Gets or sets the maximum width for all SpinnerItem in SpinnerColumnView.

Declaration
public double MaxItemWidth { get; set; }
Property Value
Type Description
System.Double

The default value is System.Double.PositiveInfinity.

MinDate

Gets or sets the minimum Gregorian date available for picking.

Declaration
public DateTimeOffset MinDate { get; set; }
Property Value
Type Description
System.DateTimeOffset

The default value is 1/1/1920.

MinItemWidth

Gets or sets the minimum width for all SpinnerItem in SpinnerColumnView.

Declaration
public double MinItemWidth { get; set; }
Property Value
Type Description
System.Double

The default value is 0.

MonthFormat

Gets or sets the display format for the month values shown in drop down.

Declaration
public string MonthFormat { get; set; }
Property Value
Type Description
System.String

The default value is {}{month.abbreviated}.
Remarks

For the complete list of format templates and format patterns, refer DateTimeFormatter class documentation.

Examples

Here's a SfDatePicker formatted using format templates and format string. Both will produce same results.

PlaceholderText

Gets or sets the text that is displayed in the editor until the SelectedDate is changed by a user action or some other operation.

Declaration
public string PlaceholderText { get; set; }
Property Value
Type Description
System.String

The default value is "Select a date".

SelectedDate

Gets or sets the currently selected date for SfDatePicker.

Declaration
public Nullable<DateTimeOffset> SelectedDate { get; set; }
Property Value
Type Description
System.Nullable<System.DateTimeOffset>

The default value is null.
Remarks

SelectedDateChanging event will be fired before date is being changed. Date change can be canceled using this event. SelectedDateChanged event will be fired when SelectedDate is changed.

ShowColumnHeaders

Gets or sets a value indicating whether the Header of each column in drop-down can be shown or not.

Declaration
public bool ShowColumnHeaders { get; set; }
Property Value
Type Description
System.Boolean

true if drop-down column Header can be shown; otherwise, false.The default value is true.

ShowDropDownHeader

Gets or sets a value indicating whether the drop-down Header can be shown or not.

Declaration
public bool ShowDropDownHeader { get; set; }
Property Value
Type Description
System.Boolean

true if drop-down Header is shown; otherwise, false.The default value is false.

VisibleItemsCount

Gets or sets the number of SpinnerItem that is visible in the drop-down.

Declaration
public int VisibleItemsCount { get; set; }
Property Value
Type Description
System.Int32

The default value is 7.
Examples
<editors:SfDatePicker x:Name="datePicker" VisibleItemsCount="5" />

YearFormat

Gets or sets the display format for the year values shown in drop down.

Declaration
public string YearFormat { get; set; }
Property Value
Type Description
System.String

The default value is {}{year.full}.
Remarks

For the complete list of format templates and format patterns, refer DateTimeFormatter class documentation.

Examples

Here's a SfDatePicker formatted using format templates and format string. Both will produce same results.

Methods

AttachFlyout()

override the base.

Declaration
protected override void AttachFlyout()
Overrides

Dispose(Boolean)

Release the unmanaged resources of SfDropDownBase.

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

Used to indicate perform dispose or not.
Overrides

OnAcceptButtonClicked()

Called when Accept button is clicked.

Declaration
protected override void OnAcceptButtonClicked()
Overrides

OnApplyTemplate()

Declaration
protected override void OnApplyTemplate()
Overrides

OnCreateAutomationPeer()

Declaration
protected override AutomationPeer OnCreateAutomationPeer()
Returns
Type
Microsoft.UI.Xaml.Automation.Peers.AutomationPeer

UpdateValues()

Helps to update Syncfusion.UI.Xaml.Editors.DateTimeHandler properties value.

Declaration
protected override void UpdateValues()
Overrides

Events

DateFieldItemPrepared

Occurs when a SpinnerItem is loading, for each items in column or date field.

Declaration
public event EventHandler<DateTimeFieldItemPreparedEventArgs> DateFieldItemPrepared
Event Type
Type
System.EventHandler<DateTimeFieldItemPreparedEventArgs>
Remarks

Content and appearance of items in drop-down can be customized using this event.

Examples

This example shows how to change background of blackout dates in XAML.

<editors:SfDatePicker DateFieldItemPrepared="OnDateFieldItemPrepared"
                      HorizontalAlignment="Center"
                      VerticalAlignment="Center" />

DateFieldPrepared

Occurs when a column or date field is loading.

Declaration
public event EventHandler<DateTimeFieldPreparedEventArgs> DateFieldPrepared
Event Type
Type
System.EventHandler<DateTimeFieldPreparedEventArgs>
Remarks

The date or month or year field in dropdown can be customized by this event.

Examples
<editors:SfDatePicker DateFieldPrepared="OnDateFieldPrepared"
                      HorizontalAlignment="Center"
                      VerticalAlignment="Center">
</editors:SfDatePicker>
private void OnDateFieldPrepared(object sender, Syncfusion.UI.Xaml.Editors.DateTimeFieldPreparedEventArgs e)
{
   if (e.Column != null && e.Column.Field == Syncfusion.UI.Xaml.Editors.DateTimeField.Day)
   {
       e.Column.Format = "ddd dd";
   }
}

SelectedDateChanged

Occurs when the SelectedDate value is changed.

Declaration
public event EventHandler<SelectedDateTimeChangedEventArgs> SelectedDateChanged
Event Type
Type
System.EventHandler<SelectedDateTimeChangedEventArgs>

SelectedDateChanging

Occurs before the SelectedDate value is changed.

Declaration
public event EventHandler<DateChangingEventArgs> SelectedDateChanging
Event Type
Type
System.EventHandler<DateChangingEventArgs>
Remarks

When editing date as input, DateFieldItemPrepared will not be triggered, hence it is not possible to decide that the given input is a blackout date or not. However, once editing is completed, SelectedDateChanging event will be triggered. Here we can cancel the date from selection, if it is a blackout date.

Implements

System.IDisposable