⏰ 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

    

Getting started

This library is available on Maven Central, add the following dependency to your build.gradle:

implementation 'nl.joery.timerangepicker:timerangepicker:1.0.0'

Define TimeRangePicker in your XML layout with custom attributes. See the Configuration section for more information.

<nl.joery.timerangepicker.TimeRangePicker
    android:id="@+id/picker"
    android:layout_width="300dp"
    android:layout_height="wrap_content"
    app:trp_thumbIconEnd="@drawable/ic_alarm"
    app:trp_thumbIconStart="@drawable/ic_moon"
    app:trp_endTime="6:30"
    app:trp_startTime="22:00" />

Get notified when the time or duration changes:

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.

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

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

Slider

Thumb

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

Copyright (c) 2021 Joery Droppers (https://github.com/Droppers)

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.