📅 RangeCalendarView

A customizable, easy-to-use calendar with range selection

Screenshots

Getting started

This library is available on Maven Central, add the following dependency:

implementation 'io.github.pelmenstar1:rangeCalendar:0.9.2'

Define RangeCalendarView in your XML layout:

<io.github.pelmenstar1.RangeCalendarView 
        android:id="@+id/picker"
        android:layout_width="match_parent"
        android:layout_height="wrap_content" />

Get notified when the date or range are selected:
(In example, the methods return true to mark that selection is valid. More about it)

calendar.onSelectionListener = object : RangeCalendarView.OnSelectionListener {
    override fun onSelectionCleared() {
    }

    override fun onDaySelected(year: Int, month: Int, day: Int): Boolean {
        return true
    }

    override fun onWeekSelected(
        weekIndex: Int,
        startYear: Int,
        startMonth: Int,
        startDay: Int,
        endYear: Int,
        endMonth: Int,
        endDay: Int
    ): Boolean {
        return true
    }

    override fun onMonthSelected(year: Int, month: Int): Boolean {
        return true
    }

    override fun onCustomRangeSelected(
        startYear: Int,
        startMonth: Int,
        startDay: Int,
        endYear: Int,
        endMonth: Int,
        endDay: Int
    ): Boolean {
        return true
    }
}

Demo

Try it yourself

Selection view

It's a view that will be shown when user selects date or range.
Visual example:

To keep information on that view relevant, use getOnSelectionListener()/setOnSelectionListener()

• getSelectionView()/setSelectionView() to assign or get the view.
• getSelectionViewTransitionDuration()/setSelectionViewTransitionDuration() to assign or get duration (in milliseconds) of selection view show/hide animation
• getSelectionViewTransitionInterpolator()/setSelectionViewTransitionInterpolator() to assign or get time interpolator of selection show/hide animation
• getSelectionViewLayoutParams()/getSelectionViewLayoutParams() to assign or get layout params for the view
• hasSelectionViewClearButton()/setHasSelectionViewClearButton() to get or set whether on selection (if selection view is not null) 'next month' button wiil become 'clear selection' button.

Minimum and maximum dates

• getMinDateEpoch()/setMinDateEpoch() to get or set minimum date represented in epoch days (Amount of days since 1 January 1970)
• getMaxDateEpoch()/setMaxDateEpoch() to get or set maximum date represented in epoch days (Amount of days since 1 January 1970)
• getMinDate()/setMinDate() to get or set minimum date represented as LocalDate. Note that, it can be used from API 26+
• getMaxDate()/setMaxDate() to get or set maximum date represented as LocalDate. Note that, it can be used from API 26+
• getMinDate(Calendar)/getMaxDate(Calendar) to get minimum/maximum date. The date will be set to the given Calendar
• setMinDate(Calendar)/setMaxDate(Calendar) to set minimum/maximum date represented as Calendar.
• setMinDate(year, month, dayOfMonth)/setMaxDate(year, month, dayOfMonth) to set minimum/maximum date by raw values.
  • year should be in range of [1970; 32767]
  • month is 1-based (in range of [1; 12])
  • year is 1-based (in range of [1; days in month])

Listener

Use getOnSelectionListener()/setOnSelectionListener() to get or set the listener. In all methods, month and day of month are 1-based.

• onSelectionCleared() fires when selection is cleared.
• onDaySelected(year, month, day) fires when day is selected.
• onWeekSelected(weekIndex, startYear, startMonth, startDay, endYear, endMonth, endDay) fires when week is selected.
  • weekIndex - index of selected week, 0-based
• onMonthSelected(year, month) fires when month is selected.
• onCustomRangeSelected(startYear, startMonth, startDay, endYear, endMonth, endDay) fires when custom range is selected

The methods (except onSelectionCleared()) should return boolean that indicate whether the selection is valid or not.

Animations

They are enabled by default (currently they cannot be disabled).

• getCommonAnimationDuration()/setCommonAnimationDuration() to get or set duration (in milliseconds) of common animations
• getCommonAnimationInterpolator()/setCommonAnimationInterpolator() to get or set time interpolator of common animations. By default, it's linear.
• getHoverAnimationDuration()/setHoverAnimationDuration() to get or set duration (in milliseconds) of hover animation
• getHoverAnimationInterpolator()/setHoverAnimationInterpolator() to get or set time interpolator of hover animation. By default, it's linear.

Changing page of calendar

• moveToPreviousMonth(withAnimation=true) to slide to previous month (if it's possible) with animation or not (it's controlled by withAnimation flag)
• moveToNextMonth(withAnimation=true) to slide to next month (if it's possible) with animation or not (it's controlled by withAnimation flag)
• setYearAndMonth(year, month, withAnimation=true) to slide to given year & month with animation or not (it's controlled by withAnimation flag). If given page is out of enabled range, selected page will remain the same

Managing selection through the code

• selectDay(epochDay)/selectDay(LocalDate)/selectDay(Calendar) to select a day. If the day is out of enabled range, it won't be selected and listeners won't be fired.
• selectWeek(year, month, weekIndex) to select a week.
  • year should be in range of [1970; 32767]
  • month is 1-based
  • weekIndex is 0-based
• selectMonth(year, month) to select a month.
  • year should be in range of [1970; 32767]
  • month is 1-based
• selectCustom(startEpochDays, endEpochDays)/selectCustom(Calendar startDate, Calendar endDate)/selectCustom(LocalDate startDate, LocalDate endDate) to select custom range defined by epoch days/LocalDate/Calendar. The range should fit in single month, otherwise the exception will be thrown.
• clearSelection() to clear selection.

Movement

• Double-touch to select a week
• Long-press to start selecting a custom range.
• Click on month information view (on top center) to select month

Other

• allowedSelectionTypes() returns special object that manages allowed types of selection. Example:

  calendar.allowedSelectionTypes().month(false).customRange(true)

  By code above, we disabled month and custom range selection. If selection type become disabled, it'll be automatically cleared.

  • cell(boolean) sets whether cell can be selected
  • week(boolean) sets whether week can be selected
  • month(boolean) sets whether month can be selected
  • customRange(boolean) sets whether custom range can be selected

  By default all types of selection are allowed.

• getVibrateOnSelectingCustomRange()/setVibrateOnSelectingCustomRange() to get or set whether the device should vibrate on start of selecting custom range.

• getClickOnCellSelectionBehavior()/setClickOnCellSelectionBehavior() to get or set behaviour when user (note, not from code) clicks on already selected cell. Use constants from ClickOnCellSelectionBehavior:

  • NONE - nothing happens
  • CLEAR - selection clears

Style

License

MIT License

Copyright (c) 2022 Khmaruk Oleg

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.