Class SfCalendar

Represents a control that allows user to browse, select one or more date in Month, Year, Decade and Century view.

Inheritance

System.Object

SfCalendar

Implements

System.IDisposable

Namespace: Syncfusion.UI.Xaml.Calendar

Assembly: Syncfusion.Calendar.WinUI.dll

Syntax

public class SfCalendar : Control, IDisposable

Examples

<calendar:SfCalendar
    SelectionMode="Single"
    FirstDayOfWeek="Sunday"/>

Constructors

SfCalendar()

Initializes a new instance of the SfCalendar class.

Declaration

public SfCalendar()

Examples

<calendar:SfCalendar
    SelectionMode="Single"
    FirstDayOfWeek="Sunday"/>

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.

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.

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.

HeaderInfoProperty

Identifies HeaderInfo dependency property.

Declaration

public static readonly DependencyProperty HeaderInfoProperty

Field Value

Type	Description
Microsoft.UI.Xaml.DependencyProperty	The identifier for the HeaderInfo 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.

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

NavigationDirectionProperty

Identifies NavigationDirection dependency property.

Declaration

public static readonly DependencyProperty NavigationDirectionProperty

Field Value

Type	Description
Microsoft.UI.Xaml.DependencyProperty	The identifier for the NavigationDirection 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.

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.

SelectedDatesProperty

Identifies SelectedDates dependency property.

Declaration

public static readonly DependencyProperty SelectedDatesProperty

Field Value

Type	Description
Microsoft.UI.Xaml.DependencyProperty	The identifier for the SelectedDates dependency property.

SelectedRangeProperty

Identifies SelectedRange dependency property.

Declaration

public static readonly DependencyProperty SelectedRangeProperty

Field Value

Type	Description
Microsoft.UI.Xaml.DependencyProperty	The identifier for the SelectedRange 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.

SelectionModeProperty

Identifies SelectionMode dependency property.

Declaration

public static readonly DependencyProperty SelectionModeProperty

Field Value

Type	Description
Microsoft.UI.Xaml.DependencyProperty	The identifier for the SelectionMode 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 in SfCalendar.

Declaration

public DateTimeOffsetCollection BlackoutDates { get; set; }

Property Value

Type	Description
DateTimeOffsetCollection	The default value is null.

Remarks

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

Examples

• XAML
• C#

Below example shows how to set blackout dates in SfCalendar.

<Page.DataContext>
  <local:ViewModel x:Name="viewModel" />
 </Page.DataContext>
 <Grid>
     <calendar:SfCalendar 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

calendar.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

• XAML
• C#

This example shows how to set date format in XAML.

<calendar:SfCalendar
    x:Name="calendar"
    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

• XAML
• C#

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

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

DisplayMode

Gets or sets a value that indicates the active view (month, year, decade or century) to be displayed while loading. 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.

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.

HeaderInfo

Gets the navigation header information.

Declaration

public CalendarHeaderInfo HeaderInfo { get; }

Property Value

Type	Description
CalendarHeaderInfo

Remarks

Gets the information shown in header based on DisplayMode. When view is month, gets the DisplayText value based on MonthHeaderFormat value.

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.

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

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

• XAML
• C#

This example shows how to set month format in XAML.

<calendar:SfCalendar x:Name="calendar" 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

• XAML
• C#

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

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

NavigationDirection

Gets or sets the navigation direction of view (horizontal and vertical). The panning, scrolling and navigation of views are performed based on navigation direction.

Declaration

public Orientation NavigationDirection { get; set; }

Property Value

Type	Description
Microsoft.UI.Xaml.Controls.Orientation	The default value is Orientation.Vertical.

Remarks

Calendar animates the views during navigation. Calendar allows to navigate between views by mouse scroll, panning or by clicking the preview and next buttons in header.

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.

SelectedDate

Gets or sets the selected date in single selection mode.

Declaration

public Nullable<DateTimeOffset> SelectedDate { get; set; }

Property Value

Type	Description
System.Nullable<System.DateTimeOffset>	The default value is null.

Remarks

Returns null if no date is selected. When value is changed, SelectedDateChanged event is raised. In Multiple mode, first date in SelectedDates will be assigned to SelectedDate. When SelectionMode is range or multiple, changing value of this property does not have any effect.

Exceptions

Type	Condition
System.InvalidOperationException	Should not set SelectedDate property when SelectionMode property value is None.

SelectedDates

Gets or sets the selected dates in multiple date selection mode.

Declaration

public DateTimeOffsetCollection SelectedDates { get; set; }

Property Value

Type	Description
DateTimeOffsetCollection	The default value is an empty collection.

Remarks

Return empty collection, when nothing is selected. When collection is changed, SelectedDatesChanged event is raised. When SelectionMode is single or range, changing value of this property does not have any effect.

Exceptions

Type	Condition
System.InvalidOperationException	should not set SelectedDates value when SelectionMode property value is None.

SelectedRange

Gets or sets the selected date range in range selection mode.

Declaration

public DateTimeOffsetRange SelectedRange { get; set; }

Property Value

Type	Description
DateTimeOffsetRange	The default value is null.

Remarks

When the selected range is changed, SelectedDateRangeChanged event is raised. In multiple or single selection mode, changing value of this property does not have any effect.

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.

SelectionMode

Gets or sets a value that indicates what kind of selections are allowed.

Declaration

public CalendarSelectionMode SelectionMode { get; set; }

Property Value

Type	Description
CalendarSelectionMode	The default value is Single.

Remarks

Disable selection by setting None value. Select multiple dates by setting Multiple value. Select date range by setting Range value.

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 Circle.

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

WeekNumberRule

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

https://docs.microsoft.com/en-us/dotnet/standard/base-types/custom-numeric-format-strings#character-literals

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

Dispose()

Disposes all the resources used by the SfCalendar class.

Declaration

public void Dispose()

Dispose(Boolean)

Disposes all the resources used by the SfCalendar class.

Declaration

protected virtual void Dispose(bool disposing)

Parameters

Type	Name	Description
System.Boolean	disposing	Indicates whether the call is from Dispose method or from a System.GC.SuppressFinalize(System.Object).

MeasureOverride(Size)

Declaration

protected override Size MeasureOverride(Size availableSize)

Parameters

Type	Name	Description
Windows.Foundation.Size	availableSize

Returns

Type	Description
Windows.Foundation.Size

OnApplyTemplate()

Declaration

protected override void OnApplyTemplate()

OnCreateAutomationPeer()

Declaration

protected override AutomationPeer OnCreateAutomationPeer()

Returns

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

OnGotFocus(RoutedEventArgs)

Declaration

protected override void OnGotFocus(RoutedEventArgs e)

Parameters

Type	Name	Description
Microsoft.UI.Xaml.RoutedEventArgs	e

OnKeyDown(KeyRoutedEventArgs)

Declaration

protected override void OnKeyDown(KeyRoutedEventArgs e)

Parameters

Type	Name	Description
Microsoft.UI.Xaml.Input.KeyRoutedEventArgs	e

OnManipulationDelta(ManipulationDeltaRoutedEventArgs)

Declaration

protected override void OnManipulationDelta(ManipulationDeltaRoutedEventArgs e)

Parameters

Type	Name	Description
Microsoft.UI.Xaml.Input.ManipulationDeltaRoutedEventArgs	e

OnPointerWheelChanged(PointerRoutedEventArgs)

Declaration

protected override void OnPointerWheelChanged(PointerRoutedEventArgs e)

Parameters

Type	Name	Description
Microsoft.UI.Xaml.Input.PointerRoutedEventArgs	e

SetDisplayDate(DateTimeOffset)

Shows the specified date in the calendar.

Declaration

public void SetDisplayDate(DateTimeOffset scrollTo)

Parameters

Type	Name	Description
System.DateTimeOffset	scrollTo	The date to show in the calendar.

Remarks

Given date will be brought into view, provided that the value is within MinDate and MaxDate.

Events

ItemPrepared

Occurs when calendar item is preparing.

Declaration

public event EventHandler<CalendarItemPreparedEventArgs> ItemPrepared

Event Type

Type	Description
System.EventHandler<CalendarItemPreparedEventArgs>

Remarks

A date can be blackout setting IsBlackout to true. Content and appearance of items can be customized using this event.

Examples

public MainPage()
{
    this.InitializeComponent();
    SfCalendar calendar = new SfCalendar();
    calendar.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 SelectedDate is changed.

Declaration

public event EventHandler<SelectedDateChangedEventArgs> SelectedDateChanged

Event Type

Type	Description
System.EventHandler<SelectedDateChangedEventArgs>

SelectedDateRangeChanged

Occurs when SelectedRange changes.

Declaration

public event EventHandler<SelectedDateRangeChangedEventArgs> SelectedDateRangeChanged

Event Type

Type	Description
System.EventHandler<SelectedDateRangeChangedEventArgs>

SelectedDatesChanged

Occurs when the collection of SelectedDates changes.

Declaration

public event EventHandler<SelectedDatesChangedEventArgs> SelectedDatesChanged

Event Type

Type	Description
System.EventHandler<SelectedDatesChangedEventArgs>

Implements

System.IDisposable