XCalendar

XCalendar

A cross-platform plugin for .NET providing a Calendar API and DateTime extensions.

UI controls are available for Xamarin Forms and .NET MAUI, able to run on any platform the respective framework supports.

• Getting Started
• Sample App
• Wiki
• Roadmap
• Nuget Package (.NET)
• Nuget Package (Xamarin Forms)
• Nuget Package (.NET MAUI)

Features

• Ability to use the Calendar from code without referencing a UI framework.
• Ability to use and reference your own models by implementing interfaces like ICalendar, ICalendarDay, or IEvent.
• Ability to set the number of rows/weeks shown or have it be automatic.
• Ability to change the start of the week to any day of the week.
• Ability to select single, multiple or a range of dates.
• Ability to specify a selection direction, for example restricting range selection from start to finish or finish to start
• Ability to restrict navigation to a range of dates and define how the calendar loops.
• Ability to specify your own custom order of days of week, with support for duplicates and non-chronological orders.
• Fully customisable CalendarView with custom controls, templates, and exposed default styles and commands.
• Support for localising text (such as days of the week and day numbers).
• And more!

Roadmap

Features (Xamarin Forms/MAUI)

• Default calendar control that exposes many customisation properties, making the calendar easier to use out-of-the-box instead of requiring usage of templates and styles.
• Default implementation of selection and navigation commands, making the calendar easier to use out-of-the-box.
• Default feature-based calendar controls such as "EventCalendar"/"AppointmentCalendar".
• Some type of time schedule control Discussion 153
• Culture/Locale property for CalendarView
• YearView
• DecadeView
• CenturyView
• Day, Month, and year properties as an alternative to NavigatedDate.

Maui Community Toolkit

Follow the discussion for moving XCalendar into the Maui Community Toolkit here.

Images

Standard Calendar

Custom Days Of Week (Unordered/Duplicates)

Custom Days Of Week (3 Days Of Week)

Custom Week Amount (1 Week)

Custom Week Amount (2 Weeks)

Day Styles

Sample App

The sample app has a flyout menu where you can access the following pages:

Playground Page

A page where you can modify almost every single property of the CalendarView. Perfect for a quick look, showcases, tests and experiments!

Examples Page

A page where you can search for examples of how to use XCalendar.

Examples include:

Event Calendar

Custom DatePicker Dialog

Selection

Using DayView

Customising A Day

Animated Swipable Calendar

https://user-images.githubusercontent.com/73718829/209573341-b506e399-631b-4cdd-b840-d17bb5ddfb85.mp4

Connecting Selected Days

Duolingo Streak Calendar

Basic Usage

.NET

Install the NuGet package

• https://www.nuget.org/packages/XCalendar.Core

Now you can use the Calendar

public Calendar MyCalendar { get; set; } = new Calendar();

Xamarin Forms

Install the NuGet package

• https://www.nuget.org/packages/XCalendar.Forms

Create a Calendar in your ViewModel

public Calendar MyCalendar { get; set; } = new Calendar();

Add the following xmlns to your page or view

xmlns:xc="clr-namespace:XCalendar.Forms.Views;assembly=XCalendar.Forms"

Bind to the properties of your Calendar

Alternatively, these properties can be set directly from code-behind without the use of MVVM.

Youtube Tutorial (Outdated - Uses version 1.2.1 for Xamarin Forms)

)

.NET MAUI

Install the NuGet package

• https://www.nuget.org/packages/XCalendar.Maui

Create a Calendar in your ViewModel

public Calendar MyCalendar { get; set; } = new Calendar();

Add the following xmlns to your page or view

xmlns:xc="clr-namespace:XCalendar.Maui.Views;assembly=XCalendar.Maui"

Bind to the properties of your Calendar

Alternatively, these properties can be set directly from code-behind without the use of MVVM.

Navigation Overview

Calendar

Navigation can be performed by setting the NavigatedDate property of the Calendar.

Alternatively, navigation can be performed using the Navigate method; it takes a parameter specifying the TimeSpan to navigate by. The Calendar can handle exceptions caused by non-representable dates such as DateTime.MaxValue.AddDays(1).

Variable time units such as months can be obtained by using the'AddMonths' method on a DateTime and subtracting the result from the current date. The 'TryAdd' and 'TrySubtract' methods in DateTimeExtensions are useful if you ever plan to navigate to the bounds of the DateTime struct.

Limiting

Navigation can be limited to a specific range of dates by changing the NavigationLowerBound and NavigationUpperBound properties of the Calendar.

Looping

You can specify the behaviour of the CalendarView when trying to navigate outside the bounds defined by NavigationLowerBound and NavigationUpperBound by changing the NavigationLoopMode property.

CalendarView

The CalendarView does not have navigation built into it by default. Instead, it exposes the BackwardsArrowCommand, BackwardsArrowCommandParameter, ForwardsArrowCommand, and ForwardsArrowCommandParameter which can be used to implement this functionality.

The CalendarView displays its navigation bar using a NavigationView. Its appearance can be changed using the NavigationViewTemplate property of the CalendarView.

Displaying Dates Overview

Calendar

Start of the Week

You can specify what day of the week should be considered as the start by setting the StartOfWeek property of the Calendar.

For Example:

• When StartOfWeek is DayOfWeek.Monday, the first row of February 2022 would be 1st Feb - 7th Feb.
• When StartOfWeek is DayOfWeek.Wednesday, the first row of February 2022 would be 26th Jan - 1st Feb
• When StartOfWeek is DayOfWeek.Sunday, the first row of February 2022 would be 31st Jan - 6th Feb

Rows

You can set how many rows you want to display by changing the Rows property of the Calendar.

Alternatively, the Calendar can automatically set the Rows value to the minimum amount needed to display every week of the NavigatedDate's month. This can be done by setting the AutoRows property of the Calendar to true. You can ensure that AutoRows always uses the highest Rows value required in the year by setting the AutoRowsIsConsistent property of the Calendar to true.

For example, when the start of the week is Monday, these are the values that will be calculated using AutoRows:

Day Of Week Order

The displayed dates are stored in the DayNamesOrder property.

The value of the DayNamesOrder is automatically calculated by the Calendar based on the values of its StartOfWeek and CustomDayNamesOrder:

• First, the Calendar determines the default order of the days of the week using the value of the StartOfWeek property of the Calendar.
• Then, the Calendar creates a default list of dates based on the days of week in the calculated order.
• If the CustomDayNamesOrder property of the Calendar is null, these default dates will be shown.
• If the CustomDayNamesOrder property of the Calendar is not null, the Calendar will cherry-pick values from these default dates, mapping their DayOfWeek to the values specified in the CustomDayNamesOrder property and shows the result.

The CustomDayNamesOrder property supports duplicates and non-chronological orders, but must contain at least one value.

CustomDayNamesOrder Examples