Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/droppers/timerangepicker

A customizable, easy-to-use, and functional circular time range picker library for Android. Use this library to mimic Apple's iOS or Samsung's bedtime picker.
https://github.com/droppers/timerangepicker

android java kotlin picker range slider time-picker time-range

Last synced: 1 day ago
JSON representation

A customizable, easy-to-use, and functional circular time range picker library for Android. Use this library to mimic Apple's iOS or Samsung's bedtime picker.

Host: GitHub
URL: https://github.com/droppers/timerangepicker
Owner: Droppers
License: mit
Created: 2020-12-18T14:26:56.000Z (about 4 years ago)
Default Branch: main
Last Pushed: 2022-11-13T13:27:17.000Z (about 2 years ago)
Last Synced: 2025-01-13T22:15:11.689Z (9 days ago)
Topics: android, java, kotlin, picker, range, slider, time-picker, time-range
Language: Kotlin
Homepage:
Size: 5.71 MB
Stars: 305
Watchers: 4
Forks: 40
Open Issues: 6
Metadata Files:
- Readme: README.md
- License: LICENSE

Awesome Lists containing this project

README

⏰ TimeRangePicker

A customizable, easy-to-use, and functional circular time range picker library for Android. Use this library to mimic Apple's iOS or Samsung's bedtime picker.

  By Joery Droppers

## Screenshots

## Playground app

Download the playground app from Google Play, with this app you can try out all features and even generate XML with your selected configuration.

## Getting started
This library is available on Maven Central, add the following dependency to your build.gradle:
```gradle
implementation 'nl.joery.timerangepicker:timerangepicker:1.0.0'
```
Define `TimeRangePicker` in your XML layout with custom attributes. See the [Configuration](#configuration) section for more information.
```xml

```

Get notified when the time or duration changes:
```kotlin
picker.setOnTimeChangeListener(object : TimeRangePicker.OnTimeChangeListener {
override fun onStartTimeChange(startTime: TimeRangePicker.Time) {
Log.d("TimeRangePicker", "Start time: " + startTime)
}

override fun onEndTimeChange(endTime: TimeRangePicker.Time) {
Log.d("TimeRangePicker", "End time: " + endTime.hour)
}

override fun onDurationChange(duration: TimeRangePicker.TimeDuration) {
Log.d("TimeRangePicker", "Duration: " + duration.hour)
}
})
```

## Managing picker programmatically
### Managing time
Examples of how to set and retrieve start time programmatically, identical properties are available for the end time.

```kotlin
// Set new time with 'Time' object to 12:00
picker.startTime = TimeRangePicker.Time(12, 0)
// Set new time by minutes
picker.startTimeMinutes = 320
```

Time
When retrieving the start or end time, the library will provide a `TimeRangePicker.Time` object.
- Use `time.hour`, `time.minute` or `time.totalMinutes` to retrieve literal time.
- Use `time.calendar` to retrieve a `java.util.Calendar` object.
- Use `time.localTime` to retrieve a `java.time.LocalTime` object. (Available since API 26)

### Managing duration
When retrieving the duration between the start and end time, the library will provide a `TimeRangePicker.Duration` object.
- Use `duration.hour`, `duration.minute` or `duration.durationMinutes` to retrieve literal duration.
- Use `duration.classicDuration` to retrieve a `javax.xml.datatype.Duration` object. (Available since API 8)
- Use `duration.duration` to retrieve a `java.time.Duration` object. (Available since API 26)

### Listening for starting and stopping of dragging
This listener is called whenever a user starts or stops dragging. It will also provide which thumb the user was dragging: start, end, or both thumbs. You can return false in the `ònDragStart` method to prevent the user from dragging a thumb.

```kotlin
picker.setOnDragChangeListener(object : TimeRangePicker.OnDragChangeListener {
override fun onDragStart(thumb: TimeRangePicker.Thumb): Boolean {
// Do something on start dragging
return true // Return false to disallow the user from dragging a handle.
}

override fun onDragStop(thumb: TimeRangePicker.Thumb) {
// Do something on stop dragging
}
})
```

## Configuration
The attributes listed below can be used to configure the look and feel of the picker. Note that all of these values can also be set programmatically using the properties.
### Time

Attribute
Description
Default

trp_startTime
Set the start time by providing a time with format h:mm.
0:00

trp_startTimeMinutes
Set the start time by providing minutes between 0 and 1440 (24 hours).
0

trp_endTime
Set the end time by providing a time with format h:mm.
8:00

trp_endTimeMinutes
Set the end time by providing minutes between 0 and 1440 (24 hours).
480

trp_minDuration
Set the minimum selectable duration by providing a duration with format h:mm.

trp_maxDuration
Set the maximum selectable duration by providing a duration with format h:mm.

trp_maxDurationMinutes
Set the maximum selectable duration by providing minutes between 0 and 1440 (24 hours).
480

trp_minDurationMinutes
Set the minimum selectable duration by providing minutes between 0 and 1440 (24 hours).
0

trp_stepTimeMinutes
Determines at what interval the time should be rounded. Setting it to a less accurate number (e.g. 10 minutes) makes it easier for a user to select his desired time.
10

### Slider

Attribute
Description
Default

trp_sliderWidth
The width of the slider wheel.
8dp

trp_sliderColor
The background color of the slider wheel.
#E1E1E1

trp_sliderRangeColor
The color of the active part of the slider wheel.
?android:colorPrimary

trp_sliderRangeGradientStart
Set the starting gradient color of the active part of the slider wheel.

Please note that both trp_sliderRangeGradientStart and trp_sliderRangeGradientEnd need to be configured.

Tip: Set the thumbColor to transparent to mimic the Apple iOS slider.

trp_sliderRangeGradientStart
Optional for gradient: set the middle gradient color of the active part of the slider wheel.

trp_sliderRangeGradientEnd
Set the ending gradient color of the active part of the slider wheel.

Please note that both trp_sliderRangeGradientStart and trp_sliderRangeGradientEnd need to be configured.

### Thumb

Attribute
Description
Default

trp_thumbIconStart
Set the start thumb icon.

trp_thumbIconEnd
Set the end thumb icon.

trp_thumbSize
The size of both the starting and ending thumb.
28dp

trp_thumbSizeActiveGrow
The amount of growth of the size when a thumb is being dragged.
1.2

trp_thumbColor
The background color of the thumbs.
?android:colorPrimary

trp_thumbIconColor
The color (tint) of the icons inside the thumbs.
white

trp_thumbIconSize
The size of the thumb icons.
24dp

### Clock

Attribute
Description
Default

trp_clockVisible
Whether the clock face in the middle should be visible.
true

trp_clockFace
There a two different clock faces (appearance of the inner clock) you can use, both mimicking the Clock apps:

APPLE

SAMSUNG

APPLE

trp_clockLabelSize
The text size of the hour labels in the clock (1, 2, 3, etc.). This value is recommended to be set as scale-independent pixels (sp).
16sp

trp_clockLabelColor
Set the text color of the hour labels in the clock.
?android:textColorPrimary

trp_clockIndicatorColor
Set the color of the small time indicator lines in the clock.
?android:textColorPrimary

trp_clockRenderer

Set the clock renderer through passing the full class name (with packages).

Note that, you should add @Keep annotation to your custom renderer class.

The renderer class should have a public constructor with one parameter: TimeRangePicker.

Then renderer will be created through calling that constructor.

nl.joery.timerangepicker.DefaultClockRenderer

## Credits
- Samsung's and Apple's Clock app have been used for inspiration, as they both implement this picker differently.

## License
```
MIT License

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.
```