📅 RangeCalendarView
A customizable, easy-to-use calendar with range selection
## Getting started
This library is available on Jitpack.
Add it in your root build.gradle:
```gradle
allprojects {
repositories {
...
maven { url 'https://jitpack.io' }
}
}
```
Add the dependency:
```gradle
implementation 'com.github.pelmenstar1:RangeCalendar:0.9.4'
```
Define `RangeCalendarView` in your XML layout:
```xml
```kotlin onSelectionListener = object : RangeCalendarView.OnSelectionListener { override fun onSelectionCleared() { } override fun onSelection( startYear: Int, startMonth: Int, startDay: Int, endYear: Int, endMonth: Int, endDay: Int ) { } } ``` ## Demo [Try it yourself](https://github.com/pelmenstar1/RangeCalendar/releases/download/0.9.4/demo.apk) ## 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 will become 'clear selection' button. ## Minimum and maximum dates - `getMinDate()/getMaxDate()` to get minimum and maximum dates respectively. - `setMinDate()/setMaxDate()` to set minimum and maximum dates respectively. ## 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. - `onSelection(startYear, startMonth, startDay, endYear, endMonth, endDay)` fires on selection. Start and end dates are inclusive. ## 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. - `getCellAnimationType()/setCellAnimationType()` to get or set type of animation for cells. See `CellAnimationType`. ## 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 ## Custom selection manager If you want to draw the selection in other way than the library does, you can implement `SelectionManager` on your own. There are two main abstractions in selection management: - 'selection state' - saves type of selection, its range (rangeStart and rangeEnd) and other data required to draw it on canvas. - 'selection manager' - responsible for creating selection state and transitions between them. The manager is expected to be stateless, except caching instances of `renderer` and `transitionController` - 'selection renderer' - responsible for rendering the selection state on `Canvas`. The implementation is not expected to be stateful, but it's acceptable to cache some information in order to make the rendering faster. - 'selection transition controller' - responsible for mutating `SelectionState.Transition` internal data to make a transition. There's a description of methods of `SelectionManager` and what they are expected to do: - `createState(rangeStart, rangeEnd, measureManager)` - creates a **new** selection state. Note that, rangeEnd is **inclusive**. measureManager can be used to determine bounds of a cell and other info. - `updateConfiguration(state, measureManager)` - updates internal measurements and computation based on measureManager results of both previousState and currentState. Change of measureManager result means that cells might be moved or resized. - `createTransition(previousState, currentState, measureManager, options)` - creates a transitive state between previousState and currentState Selection renderer is responsible for drawing simple selection state or transitive state, that is created to save information about transition between two selection states. When selection is to be drawn, the canvas' matrix is translated in such way that coordinates will be relative to the grid's leftmost point on top. To use the custom implementation of `SelectionManager` is the calendar view, use `RangeCalendarView.setSelectionManager()` To use default implementation, pass `null` to setSelectionManager(). There's also a `CellMeasureManager` class which returns position and size of specified cell. It's passed as an argument to some methods of `SelectionManager`. Although it's a public interface and it can be implemented on your own, you cannot use your implementation in a calendar view. It's implemented inside the library. ## Gestures The library allows to customize detecting gestures based on the `MotionEvent`s. You can do this by specifying custom implementation of `RangeCalendarGestureDetectorFactory` that creates your implementation of `RangeCalendarGestureDetector` ```kotlin class DetectorImpl : RangeCalendarGestureDetector() { override fun processEvent(event: MotionEvent): Boolean { // ... your code } } object DetectorImplFactory : RangeCalendarGestureDetectorFactory
Information about year and month of selected page is on that textview. The text can be changed by specifying custom `infoFormatter`:
```kotlin
rangeCalendar.infoFormatter = object : RangeCalendarView.InfoFormatter {
override fun format(year: Int, month: Int): CharSequence {
return "Year: $year Month: $month"
}
}
```
If your implementation depends on current configuration's locale, use `RangeCalendarView.LocalizedInfoFormatter`.
If you want to use default localized implementation with custom datetime pattern, use `infoPattern`. **Note**: by default, specified format will be additionally processed by `android.text.format.DateFormat.getBestDateTimePattern` to find most suitable pattern for current locale. If it's undesirable, set `useBestPatternForInfoPattern` to `false`.
`useBestPatternForInfoPattern` property depends on `android.text.format.DateFormat.getBestDateTimePattern` that is available from API level 18. On older versions, this property changes nothing.
You can directly access info textview via `infoTextView` property.
## Other
- `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
| Attribute | Description |
|-----------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| rangeCalendar_selectionColor | Color of background of selection shape |
| rangeCalendar_dayNumberTextSize | Text size of text in cells (day number) |
| rangeCalendar_inMonthDayNumberColor | Color of day number which is in selected month range |
| rangeCalendar_outMonthDayNumberColor | Color of day number which is out of selected month range |
| rangeCalendar_disabledMonthDayNumberColor | Color of day number which is out of enabled range |
| rangeCalendar_todayColor | Color of day number which represents today |
| rangeCalendar_weekdayColor | Color of text in weekday row (Mon, Tue, Wed...) |
| rangeCalendar_weekdayTextSize | Size of text in weekday row (Mon, Tue, Wed...) |
| rangeCalendar_hoverAlpha | Specifies alpha channel value of a black color that is drawn under the cell when the cell is in hovered state |
| rangeCalendar_cellSize | Size of cell |
| rangeCalendar_cellWidth | Width of cell. This value takes precedence over rangeCalendar_cellSize |
| rangeCalendar_cellHeight | Height of cell. This value takes precedence over rangeCalendar_cellSize |
| rangeCalendar_weekdayType | Type of weekday. |
| rangeCalendar_weekdays | Custom weekdays. The value should be a string array, whose length is 7. |
| rangeCalendar_clickOnCellSelectionBehavior | Specifies behaviour when **user** clicks on already selected cell. It can be one of these values: - none - nothing happens
- clear - selection is cleared
- grid - gradient distribution is limited to grid of the calendar.
- shape - gradient distribution is limited to selection shape.
- alpha - the cell gradually appears using color alpha animation
- bubble - the cell rises from the center as circle (or oval if width and height are different). Looks better when the cell is a circle.