diff --git a/README.md b/README.md new file mode 100644 index 0000000..e4d20e7 --- /dev/null +++ b/README.md @@ -0,0 +1,121 @@ +# XCalendar + +A plugin for Xamarin Forms providing a highly flexible calendar control with complex behaviour. + +## Sample +Take a look at the sample app, it has a page where you can modify every single non-cosmetic property. Perfect for a quick look, tests and experiments! + +## Warning +BindableProperty.CoerceValue is broken in the recent versions of Xamarin Forms. This control may not display changes to some properties until navigating after the change. + +## Usage + +### Install the NuGet package + * https://www.nuget.org/packages/Plugin.XCalendar/ + +### Add the following xmlns to your page +```xaml +xmlns:xc="clr-namespace:XCalendar;assembly=XCalendar" +``` +### Now you can start using the CalendarView +```xaml + + + + + +``` + +## Control Properties +Every single control property can be modified within the sample app. If a property doesn't seem to make sense, try experimenting with it! +All control properties (Except `Days`) are backed by a BindableProperty. + +#### `NavigatedDate` +The date the calendar is currently navigated to. + +#### `TodayDate` +The date the calendar will treat as 'Today'. + +#### `StartOfWeek` +The day of the week that will be considered as the start of the week. Used for internal logic. + +#### `DayNamesOrder` +The configuration in which the row dates should be displayed in. There must be at least one `DayOfWeek` in the list. Purely visual. + +#### `DayNamesOrderUsesStartOfWeek` +Determines if the calendar should shift the elements in `DayNamesOrder` to the left until the first element is equal to the `StartOfWeek`. + +#### `Rows` +The number of rows to display. Each row represents one week. + +#### `AutoRows` +Whether the calendar should automatically determine the minimum number of rows needed to display the month or not. + +#### `AutoRowsIsConsistent` +Determines if the `AutoRows` property should display the same number of rows throughout each month in the year. + +#### `NavigationMode` +The time unit the `NavigatedDate` will change by when navigating. +* `ByWeek` Add/subtract 7 days when navigating. +* `ByMonth` Add/subtract 1 month when navigating. +* `ByYear` Add/subtract 1 year when navigating. +* `ByPage` Add/subtract by `Rows` * 7. Each row represents one week and each week has 7 days. + +#### `DayRangeMinimumDate` +The lower bound of the dates the calendar considers as 'In Range'. Inclusive. + +#### `DayRangeMaximumDate` +The upper bound of the dates the calendar considers as 'In range'. Inclusive. + +#### `NavigationLimitMode` +The behaviour of the calendar when navigating to an unrepresenable `DateTime` or outside the bounds of `DayRangeMinimumDate` and `DayRangeMaximumDate`. +(Yes I'm aware of the length of some of these) +* `DontLoop` Don't loop when navigating to an unrepresentable `DateTime` +* `LoopMinimum` Loop to DateTime.MaxValue when trying to navigate past DateTime.MinValue. +* `LoopMaximum` Loop to DateTime.MinValue when trying to navigate past DateTime.MaxValue. +* `LoopMiniumAndMaximum` Loop to DateTime.MaxValue when trying to navigate past DateTime.MinValue, loop to DateTime.MinValue when trying to navigate past DateTime.MaxValue. +* `ClampToDayRangeAndDontLoop` Don't loop when navigating past `DayRangeMinimumDate` or `DayRangeMaximumDate`. +* `ClampToDayRangeAndLoopMinimum` Loop to `DayRangeMaximumDate` when trying to navigate past `DayRangeMinimumDate`. +* `ClampToDayRangeAndLoopMaximum` Loop to `DayRangeMinimumDate` when trying to navigate past `DayRangeMaximumDate`. +* `ClampToDayRangeAndLoopMinimumAndMaximum` Loop to `DayRangeMaximumDate` when trying to navigate past `DayRangeMinimumDate`, loop to `DayRangeMinimumDate` when trying to navigate past `DayRangeMaximumDate`. + +#### `SelectionMode` +How the calendar implements date selection. +* `None` No dates can be selected. +* `Single` One date can be selected. +* `Multiple` Multiple dates can be selected. + +#### `SelectedDate` +The date that has been selected when `SelectionMode` is set to `Single`. This is not cleared when `SelectionMode` changes to something else. +#### `SelectedDates` +The dates that have been selected when `SelectionMode` is set to `Multiple`. This is not cleared when `SelectionMode` changes to something else. + +#### `PageStartMode` +How the calendar will use the `NavigatedDate` to generate the first date in the page (and therefore the subsequent sequence of dates). +* `FirstDayOfWeek` Use the first date in `NavigatedDate`'s Week. +* `FirstDayOfMonth` Use the first date in the first week of `NavigatedDate`'s Month. +* `FirstDayOfYear` Use the first date in the first week of `NavigatedDate`'s Year. + +#### `Days` +The days displayed by the current page. Note that displayed days != displayed dates. +For example if `DayNamesOrder` is "Monday, Monday, Monday Tuesday" and the row is displaying the week of 10th January 2022 - 16th January 2022, there would be 4 days displayed but only 2 dates displayed: 10th January 2022 and 11th January 2022. + +## Customisation Properties +All customisation properties are backed by a BindableProperty. + +#### `NavigationTemplate` +Control what the view displaying the navigation should look like. +#### `DayNamesTemplate` +Control what the view displaying the `DayNamesOrder` should look like. +#### `DayNameTemplate` +Control how an individual `DayOfWeek` in the `DayNamesOrder` should be displayed. +#### `MonthViewTemplate` +Control what the view displaying the `Days` should look like. +#### `DayTemplate` +Control how an individual `CalendarDay` in `Days` should be displayed. + +#### And More