Class SfCalendarDatePicker

Represent 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
SfCalendarDatePicker
Implements
System.IDisposable
Inherited Members
Namespace: Syncfusion.UI.Xaml.Calendar
Assembly: Syncfusion.Calendar.WinUI.dll
Syntax
public class SfCalendarDatePicker : DateTimePickerBase, IDisposable
Examples
<calendar:SfCalendarDatePicker x:Name="calendarDatePicker" FirstDayOfWeek="Sunday" PlaceHolderText="select a date" />

Constructors

SfCalendarDatePicker()

Initializes a new instance of the SfCalendarDatePicker class.

Declaration
public SfCalendarDatePicker()
Examples
<calendar:SfCalendarDatePicker x:Name="calendarDatePicker" FirstDayOfWeek="Sunday" PlaceHolderText="select a date" />

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

The identifier for the CalendarIdentifier dependency property.

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.

DayOfWeekFormatProperty

Identifies DayOfWeekFormat dependency property.

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

The identifier for the DayOfWeekFormat dependency property.

DisplayDateFormatProperty

Identifies the DisplayDateFormat dependency property.

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

The identifier for the DisplayDateFormat dependency property.

DisplayModeProperty

Identifies DisplayMode dependency property.

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

The identifier for the DisplayMode dependency property.

DropDownWidthProperty

Identifies DropDownWidth dependency property.

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

The identifier for the DropDownWidth dependency property.

FirstDayOfWeekProperty

Identifies FirstDayOfWeek dependency property.

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

The identifier for the FirstDayOfWeek dependency property.

MaxDateProperty

Identifies the MaxDate dependency property.

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

The identifier for the MaxDate dependency property.

MaxDisplayModeProperty

Identifies MaxDisplayMode dependency property.

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

The identifier for the MaxDisplayMode dependency property.

MinDateProperty

Identifies the MinDate dependency property.

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

The identifier for the MinDate dependency property.

MinDisplayModeProperty

Identifies MinDisplayMode dependency property.

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

The identifier for the MinDisplayMode 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.

MonthHeaderFormatProperty

Identifies MonthHeaderFormat dependency property.

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

The identifier for the MonthHeaderFormat dependency property.

NumberOfWeeksInViewProperty

Identifies NumberOfWeeksInView dependency property.

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

The identifier for the NumberOfWeeksInView dependency property.

OutOfScopeVisibilityProperty

Identifies OutOfScopeVisibility dependency property.

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

The identifier for the OutOfScopeVisibility dependency property.

PlaceholderTextProperty

Identifies the 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 the SelectedDate dependency property.

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

The identifier for the SelectedDate dependency property.

SelectionHighlightModeProperty

Identifies SelectionHighlightMode dependency property.

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

The identifier for the SelectionHighlightMode dependency property.

SelectionShapeProperty

Identifies SelectionShape dependency property.

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

The identifier for the SelectionShape dependency property.

ShowWeekNumbersProperty

Identifies ShowWeekNumbers dependency property.

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

The identifier for the ShowWeekNumbers dependency property.

WeekNumberFormatProperty

Identifies WeekNumberFormat dependency property.

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

The identifier for the WeekNumberFormat dependency property.

WeekNumberRuleProperty

Identifies WeekNumberRule dependency property.

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

The identifier for the WeekNumberRule dependency property.

Properties

BlackoutDates

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

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

The default value is null.
Remarks

SfCalendarDatePicker disables the date, if the date is present in blackout dates collection.

Examples

Below example shows how to set blackout dates in SfCalendarDatePicker.

<Page.DataContext>
  <local:ViewModel x:Name="viewModel" />
 </Page.DataContext>
 <Grid>
     <calendar:SfCalendarDatePicker BlackoutDates = "{x:Bind viewModel.BlackOutDates}" FirstDayOfWeek="Sunday"/>
 </Grid>

CalendarIdentifier

Gets or sets the calendar system to use.

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

The default value is GregorianCalendar.
Remarks

All calendar types are supported except JapaneseCalendar and Lunar type calendars.

Examples
calendarDatePicker.CalendarIdentifier = Windows.Globalization.CalendarIdentifiers.Hebrew;

DayFormat

Gets or sets the date format in month view.

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

Default value is {day.integer}.
Examples

This example shows how to set date format in XAML.

<calendar:SfCalendarDatePicker x:Name="calendarDatePicker"  DateFormat="{}{day.integer(2)}" />

DayOfWeekFormat

Gets or sets the display format for the day name of the week headers in month view.

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

Default value is {dayofweek.abbreviated(2)}.
Examples

This example shows how to set days name format in XAML.

<calendar:SfCalendarDatePicker x:Name="calendarDatePicker" DayOfWeekFormat="{}{dayofweek.abbreviated(3)}" />

DisplayDateFormat

Gets or sets the display or editing format of SelectedDate.

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

The default value is d.
Examples
<calendar:SfCalendarDatePicker x:Name="calendarDatePicker"
                               FormatString="MM/yyyy"
                              />
public MainPage()
{
    this.InitializeComponent();
    SfCalendarDatePicker calendarDatePicker = new SfCalendarDatePicker();
    calendarDatePicker.FormatString = "MM/yyyy";
}

DisplayMode

Gets or sets a value that indicates the active view (month, year, decade or century) to be displayed while loading dropdown calendar. Based on MinDisplayMode, date selection is performed.

Declaration
public CalendarDisplayMode DisplayMode { get; set; }
Property Value
Type Description
CalendarDisplayMode

The default value is Month.
Remarks

DisplayMode value should be within MinDisplayMode and MaxDisplayMode properties views.

DropDownWidth

Gets or sets the width of the drop down popup in SfCalendarDatePicker control.

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

The default value is Auto.
Remarks

When DropDownWidth is auto, popup width changes based on size required by Content.

FirstDayOfWeek

Gets or sets a value that indicates which day is shown as the first day of the week.

Declaration
public FirstDayOfWeek FirstDayOfWeek { get; set; }
Property Value
Type Description
FirstDayOfWeek

The default value is Auto.
Remarks

Auto will select the FirstDayOfWeek based on current culture.

MaxDate

Gets or sets the last date to display.

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

The default value is 12/31/2120.
Remarks

MaxDate value should be greater than MinDate.

Exceptions
Type Condition
System.InvalidOperationException

MaxDate value should not be less than MinDate value.

MaxDisplayMode

Gets or sets a value indicating the maximum view that can be navigated.

Declaration
public CalendarDisplayMode MaxDisplayMode { get; set; }
Property Value
Type Description
CalendarDisplayMode

The default value is Century.
Remarks

MaxDisplayMode value should be greater than MinDisplayMode value.

Exceptions
Type Condition
System.InvalidOperationException

MaxDisplayMode value should not be less than MinDisplayMode value.

MinDate

Gets or sets the first date to display.

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

The default value is 1/1/1920.
Remarks

MinDate value should be less than MaxDate.

Exceptions
Type Condition
System.InvalidOperationException

MinDate value should not be greater than MaxDate value.

MinDisplayMode

Gets or sets a value indicating the minimum view that can be navigated.

Declaration
public CalendarDisplayMode MinDisplayMode { get; set; }
Property Value
Type Description
CalendarDisplayMode

The default value is Month.
Remarks

MinDisplayMode value should be less than MaxDisplayMode value.

Exceptions
Type Condition
System.InvalidOperationException

MinDisplayMode value should not be greater than MaxDisplayMode value.

MonthFormat

Gets or sets the month format in year view.

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

Default value is {month.abbreviated}.
Examples

This example shows how to set month format in XAML.

<calendar:SfCalendarDatePicker x:Name="calendarDatePicker" MonthFormat="{}{month.full}" />

MonthHeaderFormat

Gets or sets header format in month view.

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

Default value is month year.
Examples

This example shows how to set days name format in XAML.

<calendar:SfCalendarDatePicker x:Name="calendarDatePicker" MonthHeaderFormat="{}{month.abbreviated} {year.abbreviated}" />

NumberOfWeeksInView

Gets or sets the number of weeks that is shown in month view.

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

The default value is 6.

OutOfScopeVisibility

Gets or sets a value indicating the dates that falls out of current calendar scope is rendered.

Declaration
public OutOfScopeVisibility OutOfScopeVisibility { get; set; }
Property Value
Type Description
OutOfScopeVisibility

The default value is Enabled.
Remarks

When OutOfScopeVisibility value is Disabled, then the out-of-scope calendar items are displayed in same appearance as normal items. When OutOfScopeVisibility value is Enabled, then the out-of-scope calendar items are shown with a unique foreground color. When OutOfScopeVisibility value is Hidden, then the out-of-scope calendar items will not be displayed.

PlaceholderText

Gets or sets the text displayed in the editor textbox.

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

The default value is "Select a date".
Remarks

A string value that specifies the string displayed in the editor textbox when the SelectedDate is set to null.

SelectedDate

Gets or sets the currently selected date for SfCalendarDatePicker.

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

The default value is null.
Remarks

SelectedDateChanged event is invoked, when selected date is changed. SelectedDate will be displayed in editor textbox SfCalendarDatePicker.

SelectionHighlightMode

Gets or sets a value on how to highlight the selected date or dates.

Declaration
public SelectionHighlightMode SelectionHighlightMode { get; set; }
Property Value
Type Description
SelectionHighlightMode

The default value is Outline.
Remarks

When value is Outline, border of selected date is highlighted and background of today date is highlighted. When value is Filled, background of selected date is highlighted and border of today date is highlighted.

SelectionShape

Gets or sets a value to change the shape of selected dates.

Declaration
public SelectionShape SelectionShape { get; set; }
Property Value
Type Description
SelectionShape

The default value is Rectangle.
Remarks

When value is Rectangle the selected date cells are highlighted in rectangle shape. When value is Circle the selected date cells are highlighted in circle shape.

ShowWeekNumbers

Gets or sets a value indicating whether to show the week numbers.

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

true if the week numbers can be displayed; otherwise, false. The default value is false.
Remarks

The week number can be formatted using WeekNumberFormat The UI can be customized using the CalendarItem.ItemTempalateSelectorproperty.

See Also

WeekNumberFormat

Gets or sets a value that specifies the format of the week number.

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

The default value is string.Empty.
Remarks

When the value is “W 0”, week numbers are shown as W 1, W 2, W 3, … When the value is “00”, week numbers are shown as 01, 02, 03, …, 10, 11, ….

See Also

WeekNumberRule

Gets or sets a value that specifies the rule for the first week of the year.

Declaration
public CalendarWeekRule WeekNumberRule { get; set; }
Property Value
Type Description
System.Globalization.CalendarWeekRule

The default value is System.Globalization.CalendarWeekRule.FirstDay.
Remarks

When the WeekNumberRule value is System.Globalization.CalendarWeekRule.FirstDay, then the first week of the year starts on the first day of the year. When the WeekNumberRule value is System.Globalization.CalendarWeekRule.FirstFourDayWeek, then the first week should have at least four days. When the WeekNumberRule value is System.Globalization.CalendarWeekRule.FirstFullWeek, then the first week should have all the seven days.

Methods

AttachFlyout()

Attaches the DropDownFlyout to SfCalendarDatePicker.

Declaration
protected override void AttachFlyout()
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 Description
Microsoft.UI.Xaml.Automation.Peers.AutomationPeer

UpdateValues()

Updates the Syncfusion.UI.Xaml.Editors.DateTimeHandler properties value.

Declaration
protected override void UpdateValues()
Overrides

Events

CalendarItemPrepared

Occurs when calendar item is preparing.

Declaration
public event EventHandler<CalendarItemPreparedEventArgs> CalendarItemPrepared
Event Type
Type Description
System.EventHandler<CalendarItemPreparedEventArgs>
Remarks

Allows to change the text of specific dates using DisplayText.

Examples
public MainPage()
{
    this.InitializeComponent();
    SfCalendarDatePicker calendarDatePicker = new SfCalendarDatePicker();
    calendarDatePicker.ItemPrepared += Blockout_ItemPrepared;
}
// Blackout all weekends when calender item is being prepared.
private void Blockout_ItemPrepared(object sender, CalendarItemPreparedEventArgs e)
{
    if (e.ItemInfo.ItemType == CalendarItemType.Day &&
        (e.ItemInfo.Date.DayOfWeek == DayOfWeek.Saturday ||
        e.ItemInfo.Date.DayOfWeek == DayOfWeek.Sunday))
    {
        e.ItemInfo.IsBlackout = true;
    }
}

SelectedDateChanged

Occurs when the SelectedDate value is changed.

Declaration
public event EventHandler<SelectedDateChangedEventArgs> SelectedDateChanged
Event Type
Type Description
System.EventHandler<SelectedDateChangedEventArgs>

SelectedDateChanging

Occurs before when the SelectedDate value is changed.

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

Allows to prevent setting the today date as selected date when today's date is in BlackoutDates collection.

Examples
public MainPage()
{
this.InitializeComponent();
SfCalendarDatePicker calendarDatePicker = new SfCalendarDatePicker();
calendarDatePicker.DateChanging += calendarDatePicker_DateChanging;
}
// cancels the selected date changing process.
private void calendarDatePicker_DateChanging(object sender, DateChangingEventArgs e)
{
 if(calendarDatePicker.BlackoutDates.Contains((DateTimeOffset) e.NewDate))
 {
  e.Cancel = true;
 }
}

Implements

System.IDisposable