WinUI

Upgrade Guide User Guide Demos Support Forums Download
  • Upgrade Guide
  • User Guide
  • Demos
  • Support
  • Forums
  • Download
Class SfCalendar - WinUI API Reference | Syncfusion

    Show / Hide Table of Contents

    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
    Namespace: Syncfusion.UI.Xaml.Calendar
    Assembly: Syncfusion.Calendar.WinUI.dll
    Syntax
    public class SfCalendar : Control
    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>

    Below example shows how to set blackout dates in SfCalendar.

    public class ViewModel
    {
      public DateTimeOffsetCollection BlackOutDates;
        public ViewModel()
       {
         BlackOutDates = new DateTimeOffsetCollection();
         BlackOutDates.Add(new DateTimeOffset(DateTime.Now.AddDays(-2)));
         BlackOutDates.Add(new DateTimeOffset(DateTime.Now.AddDays(2)));
       }
    }

    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)}" />

    This example shows how to set date format in C#.

    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)}"/>

    This example shows how to set days name format in C#.

    calendar.MonthFormat = "{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}" />

    This example shows how to set month format in C#.

    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}" />

    This example shows how to set month header format in C#.

    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

    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>
    Back to top Generated by DocFX
    Copyright © 2001 - 2022 Syncfusion Inc. All Rights Reserved