Table of Contents

Class Calendar

Namespace
Avalonia.Controls
Assembly
Avalonia.Controls.dll

Represents a control that enables a user to select a date by using a visual calendar display.

[TemplatePart("PART_CalendarItem", typeof(CalendarItem))]
[TemplatePart("PART_Root", typeof(Panel))]
public class Calendar : TemplatedControl, INotifyPropertyChanged, IDataContextProvider, ILogical, IThemeVariantHost, IResourceHost, IResourceNode, IStyleHost, ISetLogicalParent, ISetInheritanceParent, ISupportInitialize, IStyleable, INamed, IInputElement, IDataTemplateHost, ISetterValue
Inheritance
Calendar
Implements
Inherited Members
Extension Methods

Remarks

A Calendar control can be used on its own, or as a drop-down part of a DatePicker control. For more information, see DatePicker. A Calendar displays either the days of a month, the months of a year, or the years of a decade, depending on the value of the DisplayMode property. When displaying the days of a month, the user can select a date, a range of dates, or multiple ranges of dates. The kinds of selections that are allowed are controlled by the SelectionMode property.

The range of dates displayed is governed by the DisplayDateStart and DisplayDateEnd properties. If DisplayMode is Year or Decade, only months or years that contain displayable dates will be displayed. Setting the displayable range to a range that does not include the current DisplayDate will throw an ArgumentOutOfRangeException.

The BlackoutDates property can be used to specify dates that cannot be selected. These dates will be displayed as dimmed and disabled.

By default, Today is highlighted. This can be disabled by setting IsTodayHighlighted to false.

The Calendar control provides basic navigation using either the mouse or keyboard. The following table summarizes keyboard navigation. 

        Key Combination     DisplayMode     Action
        ARROW               Any             Change focused date, unselect
                                            all selected dates, and select
                                            new focused date.

        SHIFT+ARROW         Any             If SelectionMode is not set to
                                            SingleDate or None begin
                                            selecting a range of dates.

        CTRL+UP ARROW       Any             Switch to the next larger
                                            DisplayMode.  If DisplayMode is
                                            already Decade, no action.

        CTRL+DOWN ARROW     Any             Switch to the next smaller
                                            DisplayMode.  If DisplayMode is
                                            already Month, no action.

        SPACEBAR            Month           Select focused date.

        SPACEBAR            Year or Decade  Switch DisplayMode to the Month
                                            or Year represented by focused
                                            item.
    </p>

XAML Usage for Classes Derived from Calendar If you define a class that derives from Calendar, the class can be used as an object element in XAML, and all of the inherited properties and events that show a XAML usage in the reference for the Calendar members can have the same XAML usage for the derived class. However, the object element itself must have a different prefix mapping than the controls: mapping shown in the usages, because the derived class comes from an assembly and namespace that you create and define. You must define your own prefix mapping to an XML namespace to use the class as an object element in XAML.

Constructors

Calendar()

Initializes a new instance of the System.Windows.Controls.Calendar class.

public Calendar()

Fields

DisplayDateEndProperty 

public static readonly StyledProperty<DateTime?> DisplayDateEndProperty

Field Value

StyledProperty<DateTime?>

DisplayDateProperty 

public static readonly StyledProperty<DateTime> DisplayDateProperty

Field Value

StyledProperty<DateTime>

DisplayDateStartProperty 

public static readonly StyledProperty<DateTime?> DisplayDateStartProperty

Field Value

StyledProperty<DateTime?>

DisplayModeProperty 

public static readonly StyledProperty<CalendarMode> DisplayModeProperty

Field Value

StyledProperty<CalendarMode>

FirstDayOfWeekProperty 

public static readonly StyledProperty<DayOfWeek> FirstDayOfWeekProperty

Field Value

StyledProperty<DayOfWeek>

HeaderBackgroundProperty 

public static readonly StyledProperty<IBrush?> HeaderBackgroundProperty

Field Value

StyledProperty<IBrush>

IsTodayHighlightedProperty 

public static readonly StyledProperty<bool> IsTodayHighlightedProperty

Field Value

StyledProperty<bool>

SelectedDateProperty 

public static readonly StyledProperty<DateTime?> SelectedDateProperty

Field Value

StyledProperty<DateTime?>

SelectionModeProperty 

public static readonly StyledProperty<CalendarSelectionMode> SelectionModeProperty

Field Value

StyledProperty<CalendarSelectionMode>

Properties

BlackoutDates

Gets a collection of dates that are marked as not selectable.

public CalendarBlackoutDatesCollection BlackoutDates { get; }

Property Value

CalendarBlackoutDatesCollection

A collection of dates that cannot be selected. The default value is an empty collection.

Remarks

Dates in this collection will appear as disabled on the calendar.

To make all past dates not selectable, you can use the AddDatesInPast method provided by the collection returned by this property.

Exceptions

ArgumentOutOfRangeException

Adding a date to this collection when it is already selected or adding a date outside the range specified by DisplayDateStart and DisplayDateEnd.

DisplayDate

Gets or sets the date to display.

public DateTime DisplayDate { get; set; }

Property Value

DateTime

The date to display.

Remarks

This property allows the developer to specify a date to display. If this property is a null reference (Nothing in Visual Basic), SelectedDate is displayed. If SelectedDate is also a null reference (Nothing in Visual Basic), Today is displayed. The default is Today.

To set this property in XAML, use a date specified in the format yyyy/mm/dd. The mm and dd components must always consist of two characters, with a leading zero if necessary. For instance, the month of May should be specified as 05.

Exceptions

ArgumentOutOfRangeException

The given date is not in the range specified by System.Windows.Controls.Calendar.DisplayDateStart and System.Windows.Controls.Calendar.DisplayDateEnd.

DisplayDateEnd

Gets or sets the last date to be displayed.

public DateTime? DisplayDateEnd { get; set; }

Property Value

DateTime?

The last date to display.

Remarks

To set this property in XAML, use a date specified in the format yyyy/mm/dd. The mm and dd components must always consist of two characters, with a leading zero if necessary. For instance, the month of May should be specified as 05.

DisplayDateStart

Gets or sets the first date to be displayed.

public DateTime? DisplayDateStart { get; set; }

Property Value

DateTime?

The first date to display.

Remarks

To set this property in XAML, use a date specified in the format yyyy/mm/dd. The mm and dd components must always consist of two characters, with a leading zero if necessary. For instance, the month of May should be specified as 05.

DisplayMode

Gets or sets a value indicating whether the calendar is displayed in months, years, or decades.

public CalendarMode DisplayMode { get; set; }

Property Value

CalendarMode

A value indicating what length of time the System.Windows.Controls.Calendar should display.

FirstDayOfWeek

Gets or sets the day that is considered the beginning of the week.

public DayOfWeek FirstDayOfWeek { get; set; }

Property Value

DayOfWeek

A DayOfWeek representing the beginning of the week. The default is Sunday.

HeaderBackground 

public IBrush? HeaderBackground { get; set; }

Property Value

IBrush

IsTodayHighlighted

Gets or sets a value indicating whether the current date is highlighted.

public bool IsTodayHighlighted { get; set; }

Property Value

bool

True if the current date is highlighted; otherwise, false. The default is true.

SelectedDate

Gets or sets the currently selected date.

public DateTime? SelectedDate { get; set; }

Property Value

DateTime?

The date currently selected. The default is null.

Remarks

Use this property when SelectionMode is set to SingleDate. In other modes, this property will always be the first date in SelectedDates.

Exceptions

ArgumentOutOfRangeException

The given date is outside the range specified by System.Windows.Controls.Calendar.DisplayDateStart and System.Windows.Controls.Calendar.DisplayDateEnd -or- The given date is in the System.Windows.Controls.Calendar.BlackoutDates collection.

InvalidOperationException

If set to anything other than null when System.Windows.Controls.Calendar.SelectionMode is set to System.Windows.Controls.CalendarSelectionMode.None.

SelectedDates

Gets a collection of selected dates.

public SelectedDatesCollection SelectedDates { get; }

Property Value

SelectedDatesCollection

A System.Windows.Controls.SelectedDatesCollection object that contains the currently selected dates. The default is an empty collection.

Remarks

Dates can be added to the collection either individually or in a range using the AddRange method. Depending on the value of the SelectionMode property, adding a date or range to the collection may cause it to be cleared. The following table lists how CalendarSelectionMode affects the SelectedDates property.

CalendarSelectionMode   Description
None                    No selections are allowed.  SelectedDate
                        cannot be set and no values can be added
                        to SelectedDates.

SingleDate              Only a single date can be selected,
                        either by setting SelectedDate or the
                        first value in SelectedDates.  AddRange
                        cannot be used.

SingleRange             A single range of dates can be selected.
                        Setting SelectedDate, adding a date
                        individually to SelectedDates, or using
                        AddRange will clear all previous values
                        from SelectedDates.
MultipleRange           Multiple non-contiguous ranges of dates
                        can be selected. Adding a date
                        individually to SelectedDates or using
                        AddRange will not clear SelectedDates.
                        Setting SelectedDate will still clear
                        SelectedDates, but additional dates or
                        range can then be added.  Adding a range
                        that includes some dates that are
                        already selected or overlaps with
                        another range results in the union of
                        the ranges and does not cause an
                        exception.

SelectionMode

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

public CalendarSelectionMode SelectionMode { get; set; }

Property Value

CalendarSelectionMode

A value that indicates the current selection mode. The default is System.Windows.Controls.CalendarSelectionMode.SingleDate.

Remarks

This property determines whether the Calendar allows no selection, selection of a single date, or selection of multiple dates. The selection mode is specified with the CalendarSelectionMode enumeration.

When this property is changed, all selected dates will be cleared.

Methods

OnApplyTemplate(TemplateAppliedEventArgs)

Builds the visual tree for the System.Windows.Controls.Calendar when a new template is applied.

protected override void OnApplyTemplate(TemplateAppliedEventArgs e)

Parameters

e TemplateAppliedEventArgs

OnGotFocus(GotFocusEventArgs)

Called before the GotFocus event occurs.

protected override void OnGotFocus(GotFocusEventArgs e)

Parameters

e GotFocusEventArgs

The event args.

OnLostFocus(RoutedEventArgs)

Called before the LostFocus event occurs.

protected override void OnLostFocus(RoutedEventArgs e)

Parameters

e RoutedEventArgs

The event args.

OnPointerReleased(PointerReleasedEventArgs)

Called before the PointerReleased event occurs.

protected override void OnPointerReleased(PointerReleasedEventArgs e)

Parameters

e PointerReleasedEventArgs

The event args.

OnPointerWheelChanged(PointerWheelEventArgs)

Default mouse wheel handler for the calendar control.

protected override void OnPointerWheelChanged(PointerWheelEventArgs e)

Parameters

e PointerWheelEventArgs

Mouse wheel event args.

ToString() 

public override string ToString()

Returns

string

Events

DisplayDateChanged

Occurs when the System.Windows.Controls.Calendar.DisplayDate property is changed.

public event EventHandler<CalendarDateChangedEventArgs>? DisplayDateChanged

Event Type

EventHandler<CalendarDateChangedEventArgs>

Remarks

This event occurs after DisplayDate is assigned its new value.

DisplayModeChanged

Occurs when the System.Windows.Controls.Calendar.DisplayMode property is changed.

public event EventHandler<CalendarModeChangedEventArgs>? DisplayModeChanged

Event Type

EventHandler<CalendarModeChangedEventArgs>

SelectedDatesChanged 

public event EventHandler<SelectionChangedEventArgs>? SelectedDatesChanged

Event Type

EventHandler<SelectionChangedEventArgs>