From 030d4cce413225e7fed9d86a4014d89802cd8f73 Mon Sep 17 00:00:00 2001 From: Kizito Nwose Date: Thu, 1 Aug 2024 17:51:51 +0200 Subject: [PATCH] Update docs --- docs/Compose.md | 29 ++++ docs/View.md | 161 +++++++++++++++--- .../kizitonwose/calendar/view/CalendarView.kt | 20 ++- .../com/kizitonwose/calendar/view/DaySize.kt | 13 +- .../kizitonwose/calendar/view/MonthHeight.kt | 33 ++-- .../calendar/view/WeekCalendarView.kt | 20 ++- .../calendar/view/YearCalendarView.kt | 27 +-- view/src/main/res/values/attrs.xml | 25 ++- 8 files changed, 257 insertions(+), 71 deletions(-) diff --git a/docs/Compose.md b/docs/Compose.md index e4955195..257c6d37 100644 --- a/docs/Compose.md +++ b/docs/Compose.md @@ -134,6 +134,35 @@ fun MainScreen() { } ``` +`HorizontalYearCalendar` and `VerticalYearCalendar`: + +```kotlin +@Composable +fun MainScreen() { + val currentYear = remember { Year.now() } + val startYear = remember { currentYear.minusYears(100) } // Adjust as needed + val endYear = remember { currentYear.plusYears(100) } // Adjust as needed + val firstDayOfWeek = remember { firstDayOfWeekFromLocale() } // Available from the library + + val state = rememberYearCalendarState( + startYear = startYear, + endYear = endYear, + firstVisibleYear = currentYear, + firstDayOfWeek = firstDayOfWeek, + ) + HorizontalYearCalendar( + state = state, + dayContent = { Day(it) }, + ) + +// If you need a vertical year calendar. +// VerticalYearCalendar( +// state = state, +// dayContent = { Day(it) } +// ) +} +``` + Your `Day` composable in its simplest form would be: ```kotlin diff --git a/docs/View.md b/docs/View.md index 8b167b28..995e530b 100644 --- a/docs/View.md +++ b/docs/View.md @@ -15,6 +15,7 @@ * [Date Selection](#date-selection) * [Disabling dates](#disabling-dates) - [Week view](#week-view) +- [Year view](#year-view) - [FAQ](#faq) - [Migration](#migration) @@ -32,16 +33,19 @@ Add the library to your project [here](https://github.com/kizitonwose/Calendar#s ## Class information -The library can be used via two classes: +The library can be used via three classes: `CalendarView`: The typical month-based calendar. `WeekCalendarView`: The week-based calendar. -Both classes extend from `RecyclerView` so you can use all `RecyclerView` customizations like decorators etc. +`YearCalendarView`: The year-based calendar. -In the examples below, we will mostly use the `CalendarView` class since the two classes share the same basic concept. If you want a week-based calendar, replace `CalendarView` in your xml/code with `WeekCalendarView`. -Most xml attributes and class properties/methods with the name prefix/suffix `month` (e.g `monthHeaderResource`) in the `CalendarView` will have an equivalent with the name prefix/suffix `week` (e.g `weekHeaderResource`) in the `WeekCalendarView`. +These classes extend from `RecyclerView` so you can use all `RecyclerView` customizations like decorators etc. + +In the examples below, we will mostly use the `CalendarView` class since the three classes share the same basic concept. If you want a week-based calendar, replace `CalendarView` in your xml/code with `WeekCalendarView`. If you want a year-based calendar, replace `CalendarView` in your xml/code with `YearCalendarView`. + +Most xml attributes and class properties/methods with the name prefix/suffix `month` (e.g `monthHeaderResource`) in the `CalendarView` will have an equivalent with the name prefix/suffix `week` (e.g `weekHeaderResource`) in the `WeekCalendarView` and the name prefix/suffix `year` (e.g `yearHeaderResource`) in the `YearCalendarView`. ## Usage @@ -103,8 +107,8 @@ Setup the desired dates in your Fragment or Activity: **`CalendarView` setup:** ```kotlin val currentMonth = YearMonth.now() -val startMonth = currentMonth.minusMonths(100) // Adjust as needed -val endMonth = currentMonth.plusMonths(100) // Adjust as needed +val startMonth = currentMonth.minusMonths(100) // Adjust as needed +val endMonth = currentMonth.plusMonths(100) // Adjust as needed val firstDayOfWeek = firstDayOfWeekFromLocale() // Available from the library calendarView.setup(startMonth, endMonth, firstDayOfWeek) calendarView.scrollToMonth(currentMonth) @@ -125,12 +129,32 @@ calendarView.scrollToMonth(currentMonth) val currentDate = LocalDate.now() val currentMonth = YearMonth.now() val startDate = currentMonth.minusMonths(100).atStartOfMonth() // Adjust as needed -val endDate = currentMonth.plusMonths(100).atEndOfMonth() // Adjust as needed +val endDate = currentMonth.plusMonths(100).atEndOfMonth() // Adjust as needed val firstDayOfWeek = firstDayOfWeekFromLocale() // Available from the library weekCalendarView.setup(startDate, endDate, firstDayOfWeek) weekCalendarView.scrollToWeek(currentDate) ``` +**`YearCalendarView` setup:** + +```diff +- +``` + +```kotlin +val currentYear = Year.now() +val startYear = currentYear.minusYears(100) // Adjust as needed +val endYear = currentYear.plusYears(100) // Adjust as needed +val firstDayOfWeek = firstDayOfWeekFromLocale() // Available from the library +yearCalendarView.setup(startYear, endYear, firstDayOfWeek) +yearCalendarView.scrollToYear(currentYear) +``` + **And that's all you need for simple usage! But keep reading, there's more!** ### First day of the week and Day of week titles. @@ -300,7 +324,7 @@ You can do more than just use the day titles as the header. For example, you can #### XML (All prefixed `cv_` for clarity) -**The following attributes are available for both `CalendarView` and `WeekCalendarView` classes:** +**The following attributes are available for `CalendarView`, `WeekCalendarView` and `YearCalendarView` classes:** - **dayViewResource**: The xml resource that is inflated and used as the day cell view. This must be provided. @@ -313,15 +337,15 @@ You can do more than just use the day titles as the header. For example, you can 2. **seventhWidth**: Each day will have its width matching the width of the calendar divided by 7. The day is allowed to determine its height by setting a specific value or using `LayoutParams.WRAP_CONTENT` 3. **freeForm**: This day is allowed to determine its width and height by setting specific values or using `LayoutParams.WRAP_CONTENT`. -**The following attributes are available for ONLY `CalendarView` class:** +**The following attributes are available for `CalendarView` and `YearCalendarView` classes:** -- **monthHeaderResource**: The xml resource that is inflated and used as a header for every month. +- **monthHeaderResource**: The xml resource that is inflated and used as a header for each month. -- **monthFooterResource**: The xml resource that is inflated and used as a footer for every month. +- **monthFooterResource**: The xml resource that is inflated and used as a footer for each month. - **orientation**: The calendar scroll direction, can be `horizontal` or `vertical`. Default is `horizontal`. -- **monthViewClass**: A ViewGroup which is instantiated and used as the container for each month. This class must have a constructor which takes only a Context. You should exclude the name and constructor of this class from code obfuscation if enabled. +- **monthViewClass**: A ViewGroup that is instantiated and used as the container for each month. This class must have a constructor which takes only a Context. You should exclude the name and constructor of this class from code obfuscation if enabled. - **outDateStyle**: This determines how outDates are generated for each month on the calendar. Can be one of two values: 1. **endOfRow**: The calendar will generate `outDates` until it reaches the end of the month row. This means that if a month has 5 rows, it will display 5 rows and if a month has 6 rows, it will display 6 rows. @@ -353,6 +377,28 @@ calendarView.dayBinder = object : MonthDayBinder { `monthDates` have their `position` property set to `DayPosition.MonthDate` as seen in the code snippet above. +**The following attributes are available for ONLY `YearCalendarView` class:** + +- **yearHeaderResource**: The xml resource that is inflated and used as a header for each year. + +- **yearFooterResource**: The xml resource that is inflated and used as a footer for each year. + +- **yearViewClass**: A ViewGroup that is instantiated and used as the container for each year. This class must have a constructor which takes only a Context. You should exclude the name and constructor of this class from code obfuscation if enabled. + +- **monthColumns**: The number of month columns in each year. Must be from 1 to 12. + +- **monthHorizontalSpacing**: The horizontal spacing between month columns in each year. + +- **monthVerticalSpacing**: The vertical spacing between month rows in each year. + +- **monthHeight**: This determines how the height of each month row on the calendar is calculated. Can be one of two values: + 1. **followDaySize**: Each month row height is determined by the `daySize` value set on the calendar. Effectively, this is `wrap-content` if the value is `Square`, + `SeventhWidth`, or `FreeForm`, and will be equal to the calendar height divided by the number of rows if the value is `Rectangle`. When used together with `Rectangle`, + the calendar months and days will uniformly stretch to fill the parent's height. + 2. **fill**: Each month row height will be the calender height divided by the number of rows on the calendar. This means that the calendar months will be distributed + uniformly to fill the parent's height. However, the day content height will independently determine its height. This allows you to spread the calendar months evenly across the screen while + a `daySize` value of `Square` if you want square day content or `SeventhWidth` if you want to set a specific height value for the day content. + **The following attributes are available for ONLY `WeekCalendarView` class:** - **weekHeaderResource**: The xml resource that is inflated and used as a header for every week. @@ -371,9 +417,9 @@ All the respective XML attributes listed above are also available as properties - **dayBinder**: An instance of `MonthDayBinder` for managing day cell views. -- **monthHeaderBinder**: An instance of `MonthHeaderFooterBinder` for managing header views. The header view is shown above each month on the Calendar. +- **monthHeaderBinder**: An instance of `MonthHeaderFooterBinder` for managing header views. The header view is shown above each month on the calendar. -- **monthFooterBinder**: An instance of `MonthHeaderFooterBinder` for managing footer views. The footer view is shown below each month on the Calendar. +- **monthFooterBinder**: An instance of `MonthHeaderFooterBinder` for managing footer views. The footer view is shown below each month on the calendar. - **monthMargins**: The margins, in pixels to be applied on each month view. This can be used to add a space between two months. @@ -383,12 +429,32 @@ All the respective XML attributes listed above are also available as properties - **dayBinder**: An instance of `WeekDayBinder` for managing day cell views. -- **weekHeaderBinder**: An instance of `WeekHeaderFooterBinder` for managing header views. The header view is shown above each week on the Calendar. +- **weekHeaderBinder**: An instance of `WeekHeaderFooterBinder` for managing the header views shown above each week on the calendar. -- **weekFooterBinder**: An instance of `WeekHeaderFooterBinder` for managing footer views. The footer view is shown below each week on the Calendar. +- **weekFooterBinder**: An instance of `WeekHeaderFooterBinder` for managing the footer views shown below each week on the calendar. - **weekMargins**: The margins, in pixels to be applied on each week view. This can be used to add a space between two weeks. +**`YearCalendarView` properties:** + +- **yearScrollListener**: Called when the calendar scrolls to a new year. Mostly beneficial if `scrollPaged` is `true`. + +- **dayBinder**: An instance of `MonthDayBinder` for managing day cell views. + +- **monthHeaderBinder**: An instance of `MonthHeaderFooterBinder` for managing the header views shown above each month on the calendar. + +- **monthFooterBinder**: An instance of `MonthHeaderFooterBinder` for managing the footer views shown below each month on the calendar. + +- **monthMargins**: The margins, in pixels to be applied on each month view. This can be used to add a space between two months. + +- **yearHeaderBinder**: An instance of `YearHeaderFooterBinder` for managing the header views shown above each year on the calendar. + +- **yearFooterBinder**: An instance of `YearHeaderFooterBinder` for managing the footer views shown below each year on the calendar. + +- **yearMargins**: The margins, in pixels to be applied on each year view. This is the container in which the year header, body and footer are placed. For example, this can be used to add a space between two years. + +- **yearBodyMargins**: The margins, in pixels to be applied on each year body view. This is the grid in which the months in each year are shown, excluding the year header and footer. + ### Methods **`CalendarView` methods:** @@ -403,11 +469,11 @@ All the respective XML attributes listed above are also available as properties - **notifyCalendarChanged()**: Reload the entire calendar. -- **findFirstVisibleMonth()** and **findLastVisibleMonth()**: Find the first and last visible months on the CalendarView respectively. +- **findFirstVisibleMonth()** and **findLastVisibleMonth()**: Find the first and last visible months on the calendar respectively. -- **findFirstVisibleDay()** and **findLastVisibleDay()**: Find the first and last visible days on the CalendarView respectively. +- **findFirstVisibleDay()** and **findLastVisibleDay()**: Find the first and last visible days on the calendar respectively. -- **updateMonthData()**: Update the CalendarView's start month or end month or the first day of week after the initial setup. The currently visible month is preserved. The calendar can handle really large date ranges so you may want to setup the calendar with a large date range instead of updating the range frequently. +- **updateMonthData()**: Update the calendar's start month or end month or the first day of week after the initial setup. The currently visible month is preserved. The calendar can handle really large date ranges so you may want to setup the calendar with a large date range instead of updating the range frequently. **`WeekCalendarView` methods:** @@ -425,11 +491,34 @@ All the respective XML attributes listed above are also available as properties - **findFirstVisibleDay()** and **findLastVisibleDay()**: Find the first and last visible days on the calendar respectively. -- **updateWeekData()**: Update the WeeCalendarView's start date or end date or the first day of week after the initial setup. The currently visible week is preserved. The calendar can handle really large date ranges so you may want to setup the calendar with a large date range instead of updating the range frequently. +- **updateWeekData()**: Update the calendar's start date or end date or the first day of week after the initial setup. The currently visible week is preserved. The calendar can handle really large date ranges so you may want to setup the calendar with a large date range instead of updating the range frequently. + +**`YearCalendarView` methods:** + +- **scrollToDate(date: LocalDate)**: Scroll to a specific date on the calendar. Use `smoothScrollToDate()` to get a smooth scrolling animation. + +- **scrollToMonth(month: YearMonth)**: Scroll to a month on the calendar. Use `smoothScrollToMonth()` to get a smooth scrolling animation. + +- **scrollToYear(year: Year)**: Scroll to a year on the calendar. Use `smoothScrollToYear()` to get a smooth scrolling animation. + +- **notifyDateChanged(date: LocalDate)**: Reload the view for the specified date. + +- **notifyMonthChanged(month: YearMonth)**: Reload the header, body and footer views for the specified month. + +- **notifyYearChanged(year: Year)**: Reload the header, body (all months in the year) and footer views for the specified year. + +- **notifyCalendarChanged()**: Reload the entire calendar. + +- **findFirstVisibleYear()** and **findLastVisibleYear()**: Find the first and last visible years on the calendar respectively. + +- **findFirstVisibleMonth()** and **findLastVisibleMonth()**: Find the first and last visible months on the calendar respectively. + +- **findFirstVisibleDay()** and **findLastVisibleDay()**: Find the first and last visible days on the calendar respectively. + +- **updateYearData()**: Update the calendar's start year or end year or the first day of week after the initial setup. The currently visible year is preserved. The calendar can handle really large date ranges so you may want to setup the calendar with a large date range instead of updating the range frequently. There's no need to list all available methods or repeat the documentation here. Please see -the [CalendarView](https://github.com/kizitonwose/Calendar/blob/main/view/src/main/java/com/kizitonwose/calendar/view/CalendarView.kt) -and [WeekCalendarView](https://github.com/kizitonwose/Calendar/blob/main/view/src/main/java/com/kizitonwose/calendar/view/WeekCalendarView.kt) +the [CalendarView](https://github.com/kizitonwose/Calendar/blob/main/view/src/main/java/com/kizitonwose/calendar/view/CalendarView.kt), [WeekCalendarView](https://github.com/kizitonwose/Calendar/blob/main/view/src/main/java/com/kizitonwose/calendar/view/WeekCalendarView.kt) and [YearCalendarView](https://github.com/kizitonwose/Calendar/blob/main/view/src/main/java/com/kizitonwose/calendar/view/YearCalendarView.kt) classes for all properties and methods available with proper documentation. ### Date clicks @@ -490,7 +579,7 @@ calendarView.dayBinder = object : MonthDayBinder { The library has no inbuilt concept of selected/unselected dates, this gives you the freedom to choose how best you would like to implement this use case. -Implementing date selection is as simple as showing a background on a specific date in the date binder. Remember that since CalendarView and WeekCalendarView extend from RecyclerView, you need to undo any special effects on dates where it is not needed. +Implementing date selection is as simple as showing a background on a specific date in the date binder. Remember that since CalendarView, WeekCalendarView and YearCalendarView all extend from RecyclerView, you need to undo any special effects on dates where it is not needed. For this example, I want only the last clicked date to be selected on the calendar. @@ -598,7 +687,7 @@ See the sample project for some complex implementations. ## Week view -As discussed previously, the library provides two classes `CalendarView` and `WeekCalendarView`. The `WeekCalendarView` class is a week-based calendar implementation. Almost all topics covered above for the month calendar will apply to the week calendar. The main difference is that the xml attributes and class properties/methods will have a slightly different name, typically with a `week` prefix/suffix instead of `month`. +The `WeekCalendarView` class is a week-based calendar implementation. Almost all topics covered above for the month calendar will apply to the week calendar. The main difference is that the xml attributes and class properties/methods will have a slightly different name, typically with a `week` prefix/suffix instead of `month`. For example: `monthHeaderResource` => `weekHeaderResource`, `scrollToMonth()` => `scrollToWeek()`, `findFirstVisibleMonth()` => `findFirstVisibleWeek()` and many others, but you get the idea. @@ -624,6 +713,28 @@ A week calendar implementation from the sample app: Week calendar +## Year view + +The `YearCalendarView` class is a year-based calendar implementation. All topics covered above for the month calendar will apply to the year calendar. The year calendar also has additional xml attributes and class properties/methods, typically with a `year` prefix/suffix. + +For example: `yearHeaderResource`, `scrollToYear()`, `findFirstVisibleYear()` and many others, but you get the idea. + +To show the year calendar in your layout, add the view: + +```xml + +``` + +Then follow the setup instructions above to provide a day resource/binder etc as you would do for the month calendar. + +A year calendar implementation from the sample app: + +Year calendar + Remember that all the screenshots shown so far are just examples of what you can achieve with the library and you can absolutely build your calendar to look however you want. **Made a cool calendar with this library? Share an image [here](https://github.com/kizitonwose/Calendar/issues/1).** @@ -632,7 +743,7 @@ Remember that all the screenshots shown so far are just examples of what you can **Q**: How do I use this library in a Java project? -**A**: It works out of the box, however, the `MonthScrollListener` is not an interface but a Kotlin function. To set the `MonthScrollListener` in a Java project see [this](https://github.com/kizitonwose/Calendar/issues/74). +**A**: It works out of the box, however, the `MonthScrollListener`, `WeekScrollListener` and `YearScrollListener` are not interfaces but Kotlin functions. To set the listener in a Java project see [this](https://github.com/kizitonwose/Calendar/issues/74). **Q**: How do I disable user scrolling on the calendar so I can only scroll programmatically? diff --git a/view/src/main/java/com/kizitonwose/calendar/view/CalendarView.kt b/view/src/main/java/com/kizitonwose/calendar/view/CalendarView.kt index e1186053..1810d1c7 100644 --- a/view/src/main/java/com/kizitonwose/calendar/view/CalendarView.kt +++ b/view/src/main/java/com/kizitonwose/calendar/view/CalendarView.kt @@ -22,6 +22,12 @@ import java.time.DayOfWeek import java.time.LocalDate import java.time.YearMonth +/** + * A month-based calendar view. + * + * @see WeekCalendarView + * @see YearCalendarView + */ public open class CalendarView : RecyclerView { /** * The [MonthDayBinder] instance used for managing day @@ -34,8 +40,8 @@ public open class CalendarView : RecyclerView { } /** - * The [MonthHeaderFooterBinder] instance used for managing header views. - * The header view is shown above each month on the Calendar. + * The [MonthHeaderFooterBinder] instance used for managing the + * header views shown above each month on the calendar. */ public var monthHeaderBinder: MonthHeaderFooterBinder<*>? = null set(value) { @@ -44,8 +50,8 @@ public open class CalendarView : RecyclerView { } /** - * The [MonthHeaderFooterBinder] instance used for managing footer views. - * The footer view is shown below each month on the Calendar. + * The [MonthHeaderFooterBinder] instance used for managing the + * footer views shown below each month on the calendar. */ public var monthFooterBinder: MonthHeaderFooterBinder<*>? = null set(value) { @@ -73,7 +79,7 @@ public open class CalendarView : RecyclerView { } /** - * The xml resource that is inflated and used as a header for every month. + * The xml resource that is inflated and used as a header for each month. * Set zero to disable. */ public var monthHeaderResource: Int = 0 @@ -85,7 +91,7 @@ public open class CalendarView : RecyclerView { } /** - * The xml resource that is inflated and used as a footer for every month. + * The xml resource that is inflated and used as a footer for each month. * Set zero to disable. */ public var monthFooterResource: Int = 0 @@ -97,7 +103,7 @@ public open class CalendarView : RecyclerView { } /** - * The fully qualified class name of a [ViewGroup] which is instantiated + * The fully qualified class name of a [ViewGroup] that is instantiated * and used as the container for each month. This class must have a * constructor which takes only a [Context]. * diff --git a/view/src/main/java/com/kizitonwose/calendar/view/DaySize.kt b/view/src/main/java/com/kizitonwose/calendar/view/DaySize.kt index ec51766b..21d65db8 100644 --- a/view/src/main/java/com/kizitonwose/calendar/view/DaySize.kt +++ b/view/src/main/java/com/kizitonwose/calendar/view/DaySize.kt @@ -4,17 +4,20 @@ import android.view.ViewGroup /** * Determines how the size of each day on the calendar is calculated. + * + * These values work independently in the [CalendarView] and [WeekCalendarView] classes. + * However, for the [YearCalendarView] class, these values work together with the [MonthHeight]. */ public enum class DaySize { /** * Each day will have both width and height matching - * the width of the calendar divided by 7. + * the width of the calendar month/week divided by 7. */ Square, /** * Each day will have its width matching the width of the - * calendar divided by 7, and its height matching the + * calendar month/week divided by 7, and its height matching the * height of the calendar divided by the number of weeks * in the index - could be 4, 5 or 6 for the month calendar, * and 1 for the week calendar. Use this if you want each @@ -22,10 +25,10 @@ public enum class DaySize { */ Rectangle, - /** TODO DOC + /** * Each day will have its width matching the width of - * the calendar divided by 7. This day is allowed to - * determine its height by setting a specific value + * the calendar month/week divided by 7. This day is allowed + * to determine its height by setting a specific value * or using [ViewGroup.LayoutParams.WRAP_CONTENT]. */ SeventhWidth, diff --git a/view/src/main/java/com/kizitonwose/calendar/view/MonthHeight.kt b/view/src/main/java/com/kizitonwose/calendar/view/MonthHeight.kt index 2968e9d0..50b12911 100644 --- a/view/src/main/java/com/kizitonwose/calendar/view/MonthHeight.kt +++ b/view/src/main/java/com/kizitonwose/calendar/view/MonthHeight.kt @@ -1,22 +1,33 @@ package com.kizitonwose.calendar.view -import android.view.ViewGroup - /** - * Determines how the height of each month row on the year-based calendar is calculated. + * Determines how the height of each month row on the year-based + * calendar is calculated. + * + * **This class is only relevant for [YearCalendarView].** */ public enum class MonthHeight { - /** TODO DOC - * Each day will have both width and height matching - * the width of the calendar divided by 7. + /** + * Each month row height is determined by the [DaySize] value set on the calendar. + * Effectively, this is `wrap-content` if the value is [DaySize.Square], + * [DaySize.SeventhWidth], or [DaySize.FreeForm], and will be equal to the calendar height + * divided by the number of rows if the value is [DaySize.Rectangle]. + * + * When used together with [DaySize.Rectangle], the calendar months and days will + * uniformly stretch to fill the parent's height. */ FollowDaySize, - /** TODO DOC - * Each day will have its width matching the width of - * the calendar divided by 7. This day is allowed to - * determine its height by setting a specific value - * or using [ViewGroup.LayoutParams.WRAP_CONTENT]. + /** + * Each month row height will be the calender height divided by the number + * of rows on the calendar. This means that the calendar months will be distributed + * uniformly to fill the parent's height. However, the day content height will + * independently determine its height. + * + * This allows you to spread the calendar months evenly across the screen while + * using a [DaySize] value of [DaySize.Square] if you want square day content + * or [DaySize.SeventhWidth] if you want to set a specific height value for + * the day content. */ Fill, diff --git a/view/src/main/java/com/kizitonwose/calendar/view/WeekCalendarView.kt b/view/src/main/java/com/kizitonwose/calendar/view/WeekCalendarView.kt index 21957512..578b5629 100644 --- a/view/src/main/java/com/kizitonwose/calendar/view/WeekCalendarView.kt +++ b/view/src/main/java/com/kizitonwose/calendar/view/WeekCalendarView.kt @@ -17,6 +17,12 @@ import com.kizitonwose.calendar.view.internal.weekcalendar.WeekCalendarLayoutMan import java.time.DayOfWeek import java.time.LocalDate +/** + * A week-based calendar view. + * + * @see CalendarView + * @see YearCalendarView + */ public open class WeekCalendarView : RecyclerView { /** * The [WeekDayBinder] instance used for managing day @@ -29,8 +35,8 @@ public open class WeekCalendarView : RecyclerView { } /** - * The [WeekHeaderFooterBinder] instance used for managing header views. - * The header view is shown above each week on the Calendar. + * The [WeekHeaderFooterBinder] instance used for managing the + * header views shown above each week on the calendar. */ public var weekHeaderBinder: WeekHeaderFooterBinder<*>? = null set(value) { @@ -39,8 +45,8 @@ public open class WeekCalendarView : RecyclerView { } /** - * The [WeekHeaderFooterBinder] instance used for managing footer views. - * The footer view is shown below each week on the Calendar. + * The [WeekHeaderFooterBinder] instance used for managing the + * footer views shown below each week on the calendar. */ public var weekFooterBinder: WeekHeaderFooterBinder<*>? = null set(value) { @@ -68,7 +74,7 @@ public open class WeekCalendarView : RecyclerView { } /** - * The xml resource that is inflated and used as a header for every week. + * The xml resource that is inflated and used as a header for each week. * Set zero to disable. */ public var weekHeaderResource: Int = 0 @@ -80,7 +86,7 @@ public open class WeekCalendarView : RecyclerView { } /** - * The xml resource that is inflated and used as a footer for every week. + * The xml resource that is inflated and used as a footer for each week. * Set zero to disable. */ public var weekFooterResource: Int = 0 @@ -92,7 +98,7 @@ public open class WeekCalendarView : RecyclerView { } /** - * The fully qualified class name of a [ViewGroup] which is instantiated + * The fully qualified class name of a [ViewGroup] that is instantiated * and used as the container for each week. This class must have a * constructor which takes only a [Context]. * diff --git a/view/src/main/java/com/kizitonwose/calendar/view/YearCalendarView.kt b/view/src/main/java/com/kizitonwose/calendar/view/YearCalendarView.kt index 89365163..a40f4588 100644 --- a/view/src/main/java/com/kizitonwose/calendar/view/YearCalendarView.kt +++ b/view/src/main/java/com/kizitonwose/calendar/view/YearCalendarView.kt @@ -26,6 +26,12 @@ import java.time.LocalDate import java.time.Year import java.time.YearMonth +/** + * A year-based calendar view. + * + * @see CalendarView + * @see WeekCalendarView + */ public open class YearCalendarView : RecyclerView { /** * The [MonthDayBinder] instance used for managing day @@ -39,7 +45,7 @@ public open class YearCalendarView : RecyclerView { /** * The [MonthHeaderFooterBinder] instance used for managing the - * header views shown above each month on the Calendar. + * header views shown above each month on the calendar. */ public var monthHeaderBinder: MonthHeaderFooterBinder<*>? = null set(value) { @@ -49,7 +55,7 @@ public open class YearCalendarView : RecyclerView { /** * The [MonthHeaderFooterBinder] instance used for managing the - * footer views shown below each month on the Calendar. + * footer views shown below each month on the calendar. */ public var monthFooterBinder: MonthHeaderFooterBinder<*>? = null set(value) { @@ -59,7 +65,7 @@ public open class YearCalendarView : RecyclerView { /** * The [YearHeaderFooterBinder] instance used for managing the - * header views shown above each year on the Calendar. + * header views shown above each year on the calendar. */ public var yearHeaderBinder: YearHeaderFooterBinder<*>? = null set(value) { @@ -69,7 +75,7 @@ public open class YearCalendarView : RecyclerView { /** * The [YearHeaderFooterBinder] instance used for managing the - * footer views shown below each year on the Calendar. + * footer views shown below each year on the calendar. */ public var yearFooterBinder: YearHeaderFooterBinder<*>? = null set(value) { @@ -97,7 +103,7 @@ public open class YearCalendarView : RecyclerView { } /** - * The xml resource that is inflated and used as a header for every month. + * The xml resource that is inflated and used as a header for each month. * Set zero to disable. */ public var monthHeaderResource: Int = 0 @@ -109,7 +115,7 @@ public open class YearCalendarView : RecyclerView { } /** - * The xml resource that is inflated and used as a footer for every month. + * The xml resource that is inflated and used as a footer for each month. * Set zero to disable. */ public var monthFooterResource: Int = 0 @@ -121,7 +127,7 @@ public open class YearCalendarView : RecyclerView { } /** - * The xml resource that is inflated and used as a header for every year. + * The xml resource that is inflated and used as a header for each year. * Set zero to disable. */ public var yearHeaderResource: Int = 0 @@ -133,7 +139,7 @@ public open class YearCalendarView : RecyclerView { } /** - * The xml resource that is inflated and used as a footer for every year. + * The xml resource that is inflated and used as a footer for each year. * Set zero to disable. */ public var yearFooterResource: Int = 0 @@ -145,7 +151,7 @@ public open class YearCalendarView : RecyclerView { } /** - * The fully qualified class name of a [ViewGroup] which is instantiated + * The fully qualified class name of a [ViewGroup] that is instantiated * and used as the container for each month. This class must have a * constructor which takes only a [Context]. * @@ -156,13 +162,12 @@ public open class YearCalendarView : RecyclerView { set(value) { if (field != value) { field = value - this.javaClass.simpleName invalidateViewHolders() } } /** - * The fully qualified class name of a [ViewGroup] which is instantiated + * The fully qualified class name of a [ViewGroup] that is instantiated * and used as the container for each year. This class must have a * constructor which takes only a [Context]. * diff --git a/view/src/main/res/values/attrs.xml b/view/src/main/res/values/attrs.xml index 5c7c65e8..b9f7094b 100644 --- a/view/src/main/res/values/attrs.xml +++ b/view/src/main/res/values/attrs.xml @@ -104,20 +104,35 @@ - + - + - + - - + + + +