Update docs

kizitonwose · Aug 2, 2024 · 030d4cc · 030d4cc
1 parent 7a3ca08
commit 030d4cc
Show file tree

Hide file tree

Showing 8 changed files with 257 additions and 71 deletions.
diff --git 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
diff --git 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
@@ -4,28 +4,31 @@ 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
      * month or week to fill the parent's width and height.
      */
     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
@@ -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
@@ -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
@@ -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
@@ -104,20 +104,35 @@
 
         <attr name="cv_monthViewClass" />
 
-        <!-- TODO - doc-->
+        <!-- The number of month columns in each year. Must be from 1 to 12. -->
         <attr name="cv_monthColumns" format="integer" />
 
-        <!-- TODO - doc-->
+        <!-- The horizontal spacing between month columns in each year. -->
         <attr name="cv_monthHorizontalSpacing" format="dimension" />
 
-        <!-- TODO - doc-->
+        <!-- The vertical spacing between month rows in each year. -->
         <attr name="cv_monthVerticalSpacing" format="dimension" />
 
-        <!-- TODO - doc-->
-        <!-- Determines how the size of each day on the calendar is calculated. -->
+        <!-- Determines how the height of each month row on the year-based calendar is calculated. -->
         <attr name="cv_monthHeight" format="enum">
+            <!-- Each month's 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. -->
             <enum name="followDaySize" value="0" />
+
+            <!-- Each month's 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. -->
             <enum name="fill" value="1" />
         </attr>