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

DateTimePickerBase.AllowNullProperty

DateTimePickerBase.EditModeProperty

DateTimePickerBase.ShowClearButtonProperty

DateTimePickerBase.HeaderProperty

DateTimePickerBase.HeaderTemplateProperty

DateTimePickerBase.DescriptionProperty

DateTimePickerBase.OnKeyDown(KeyRoutedEventArgs)

DateTimePickerBase.OnKeyUp(KeyRoutedEventArgs)

DateTimePickerBase.OnGotFocus(RoutedEventArgs)

DateTimePickerBase.OnPointerEntered(PointerRoutedEventArgs)

DateTimePickerBase.OnPointerExited(PointerRoutedEventArgs)

DateTimePickerBase.OnPointerPressed(PointerRoutedEventArgs)

DateTimePickerBase.AllowNull

DateTimePickerBase.EditMode

DateTimePickerBase.ShowClearButton

DateTimePickerBase.Header

DateTimePickerBase.HeaderTemplate

DateTimePickerBase.Description

SfDropDownBase.ContentProperty

SfDropDownBase.ContentTemplateProperty

SfDropDownBase.DropDownButtonTemplateProperty

SfDropDownBase.DropDownHeightProperty

SfDropDownBase.DropDownModeProperty

SfDropDownBase.DropDownPlacementProperty

SfDropDownBase.ShowDropDownButtonProperty

SfDropDownBase.ShowSubmitButtonsProperty

SfDropDownBase.IsOpenProperty

SfDropDownBase.Dispose()

SfDropDownBase.OnPrimaryButtonClicked()

SfDropDownBase.OnDeclineButtonClicked()

SfDropDownBase.OpenDropDown()

SfDropDownBase.CloseDropDown()

SfDropDownBase.Content

SfDropDownBase.ContentTemplate

SfDropDownBase.DropDownButtonTemplate

SfDropDownBase.DropDownHeight

SfDropDownBase.DropDownMode

SfDropDownBase.DropDownPlacement

SfDropDownBase.IsOpen

SfDropDownBase.ShowDropDownButton

SfDropDownBase.ShowSubmitButtons

SfDropDownBase.DropDownOpened

SfDropDownBase.DropDownClosed

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	Description
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

DateTimePickerBase.AttachFlyout()

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

SfDropDownBase.Dispose(Boolean)

OnAcceptButtonClicked()

Called when Accept button is clicked.

Declaration

protected override void OnAcceptButtonClicked()

Overrides

SfDropDownBase.OnAcceptButtonClicked()

OnApplyTemplate()

Declaration

protected override void OnApplyTemplate()

Overrides

DateTimePickerBase.OnApplyTemplate()

OnCreateAutomationPeer()

Declaration

protected override AutomationPeer OnCreateAutomationPeer()

Returns

Type	Description
Microsoft.UI.Xaml.Automation.Peers.AutomationPeer

UpdateValues()

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

Declaration

protected override void UpdateValues()

Overrides

DateTimePickerBase.UpdateValues()

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	Description
System.EventHandler<DateTimeFieldItemPreparedEventArgs>

Remarks

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

Examples

• XAML
• C#

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	Description
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	Description
System.EventHandler<SelectedDateTimeChangedEventArgs>

SelectedDateChanging

Occurs before the SelectedDate value is changed.

Declaration

public event EventHandler<DateChangingEventArgs> SelectedDateChanging

Event Type

Type	Description
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