|
| 1 | +# TimeRangePicker |
| 2 | +[](https://maven-badges.herokuapp.com/maven-central/nl.joery.timerangepicker/timerangepicker) |
| 3 | +[](https://android-arsenal.com/api?level=14) |
| 4 | +[](https://opensource.org/licenses/MIT) |
| 5 | + |
| 6 | +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. |
| 7 | + |
| 8 | +## Examples |
| 9 | +<table> |
| 10 | + <tr> |
| 11 | + <td><img src="./art/example-animated.gif" width="300" /></td> |
| 12 | + <td><img src="./art/example-2.png" width="250" /><br><img src="./art/example-3.png" width="250" /></td> |
| 13 | + </tr> |
| 14 | +</table> |
| 15 | + |
| 16 | +## Playground app |
| 17 | +<img src="./art/playground-demo.png" width="400" /> |
| 18 | + |
| 19 | +Download the playground app: [demo.apk](./art/demo.apk). In this app, you can try out all features and even generate XML layouts. |
| 20 | + |
| 21 | +## Contents |
| 22 | +- [Getting started](#getting-started) |
| 23 | +- [Managing picker programmatically](#managing-picker-programmatically) |
| 24 | +- [Configuration](#configuration) |
| 25 | + |
| 26 | +## Getting started |
| 27 | +<img src="./art/getting-started.png?3" width="250" /> |
| 28 | + |
| 29 | +This library is available on Maven Central, add the following dependency to your <b>build.gradle</b>: |
| 30 | +```gradle |
| 31 | +implementation 'nl.joery.timerangepicker:timerangepicker:1.0.0' |
| 32 | +``` |
| 33 | +Define `TimeRangePicker` in your XML layout with custom attributes. See the [Configuration](#configuration) section for more information. |
| 34 | +```xml |
| 35 | +<nl.joery.timerangepicker.TimeRangePicker |
| 36 | + android:id="@+id/picker" |
| 37 | + android:layout_width="300dp" |
| 38 | + android:layout_height="wrap_content" |
| 39 | + app:trp_thumbIconEnd="@drawable/ic_alarm" |
| 40 | + app:trp_thumbIconStart="@drawable/ic_moon" |
| 41 | + app:trp_endTime="6:30" |
| 42 | + app:trp_startTime="22:00" /> |
| 43 | +``` |
| 44 | + |
| 45 | +Get notified when the time or duration changes: |
| 46 | +```kotlin |
| 47 | +picker.setOnTimeChangeListener(object : TimeRangePicker.OnTimeChangeListener { |
| 48 | + override fun onStartTimeChange(startTime: TimeRangePicker.Time) { |
| 49 | + Log.d("TimeRangePicker", "Start time: " + startTime) |
| 50 | + } |
| 51 | + |
| 52 | + override fun onEndTimeChange(endTime: TimeRangePicker.Time) { |
| 53 | + Log.d("TimeRangePicker", "End time: " + endTime.hour) |
| 54 | + } |
| 55 | + |
| 56 | + override fun onDurationChange(duration: TimeRangePicker.TimeDuration) { |
| 57 | + Log.d("TimeRangePicker", "Duration: " + duration.hour) |
| 58 | + } |
| 59 | +}) |
| 60 | +``` |
| 61 | + |
| 62 | +## Managing picker programmatically |
| 63 | +### Managing time |
| 64 | +Examples of how to set and retrieve start time programmatically, identical properties are available for the end time. |
| 65 | + |
| 66 | +```kotlin |
| 67 | +// Set new time with 'Time' object to 12:00 |
| 68 | +picker.startTime = TimeRangePicker.Time(12, 0) |
| 69 | +// Set new time by minutes |
| 70 | +picker.startTimeMinutes = 320 |
| 71 | +``` |
| 72 | + |
| 73 | +<b>Time</b> |
| 74 | +When retrieving the start or end time, the library will provide a `TimeRangePicker.Time` object. |
| 75 | +- Use `time.hour`, `time.minute` or `time.totalMinutes` to retrieve literal time. |
| 76 | +- Use `time.calendar` to retrieve a `java.util.Calendar` object. |
| 77 | +- Use `time.localTime` to retrieve a `java.time.LocalTime` object. (Available since API 26) |
| 78 | + |
| 79 | +### Managing duration |
| 80 | +When retrieving the duration between the start and end time, the library will provide a `TimeRangePicker.Duration` object. |
| 81 | +- Use `duration.hour`, `duration.minute` or `duration.durationMinutes` to retrieve literal duration. |
| 82 | +- Use `duration.classicDuration` to retrieve a `javax.xml.datatype.Duration` object. (Available since API 8) |
| 83 | +- Use `duration.duration` to retrieve a `java.time.Duration` object. (Available since API 26) |
| 84 | + |
| 85 | +### Listening for starting and stopping of dragging |
| 86 | +This listener is called whenever a user starts or stops dragging. It will also provide which thumb the user was dragging: <i>start, end, or both thumbs</i>. You can return false in the `ònDragStart` method to prevent the user from dragging a thumb. |
| 87 | + |
| 88 | +```kotlin |
| 89 | +picker.setOnDragChangeListener(object : TimeRangePicker.OnDragChangeListener { |
| 90 | + override fun onDragStart(thumb: TimeRangePicker.Thumb): Boolean { |
| 91 | + // Do something on start dragging |
| 92 | + return true // Return false to disallow the user from dragging a handle. |
| 93 | + } |
| 94 | + |
| 95 | + override fun onDragStop(thumb: TimeRangePicker.Thumb) { |
| 96 | + // Do something on stop dragging |
| 97 | + } |
| 98 | +}) |
| 99 | +``` |
| 100 | + |
| 101 | +## Configuration |
| 102 | +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. |
| 103 | +### Time |
| 104 | +<table> |
| 105 | + <tr> |
| 106 | + <th>Attribute</th> |
| 107 | + <th>Description</th> |
| 108 | + <th>Default</th> |
| 109 | + </tr> |
| 110 | + <tr> |
| 111 | + <td><b>trp_startTime</b></td> |
| 112 | + <td>Set the start time by providing a time with format <i>h:mm</i>.</td> |
| 113 | + <td>0:00</td> |
| 114 | + </tr> |
| 115 | + <tr> |
| 116 | + <td><b>trp_startTimeMinutes</b></td> |
| 117 | + <td>Set the start time by providing minutes between 0 and 1440 (24 hours).</td> |
| 118 | + <td>0</td> |
| 119 | + </tr> |
| 120 | + <tr> |
| 121 | + <td><b>trp_endTime</b></td> |
| 122 | + <td>Set the end time by providing a time with format <i>h:mm</i>.</td> |
| 123 | + <td>8:00</td> |
| 124 | + </tr> |
| 125 | + <tr> |
| 126 | + <td><b>trp_endTimeMinutes</b></td> |
| 127 | + <td>Set the end time by providing minutes between 0 and 1440 (24 hours).</td> |
| 128 | + <td>480</td> |
| 129 | + </tr> |
| 130 | + <tr> |
| 131 | + <td><b>trp_minDuration</b></td> |
| 132 | + <td>Set the minimum selectable duration by providing a duration with format <i>h:mm</i>.</td> |
| 133 | + <td></td> |
| 134 | + </tr> |
| 135 | + <tr> |
| 136 | + <td><b>trp_maxDuration</b></td> |
| 137 | + <td>Set the maximum selectable duration by providing a duration with format <i>h:mm</i>.</td> |
| 138 | + <td></td> |
| 139 | + </tr> |
| 140 | + <tr> |
| 141 | + <td><b>trp_maxDurationMinutes</b></td> |
| 142 | + <td>Set the maximum selectable duration by providing minutes between 0 and 1440 (24 hours).</td> |
| 143 | + <td>480</td> |
| 144 | + </tr> |
| 145 | + <tr> |
| 146 | + <td><b>trp_minDurationMinutes</b></td> |
| 147 | + <td>Set the minimum selectable duration by providing minutes between 0 and 1440 (24 hours).</td> |
| 148 | + <td>0</td> |
| 149 | + </tr> |
| 150 | + <tr> |
| 151 | + <td><b>trp_stepTimeMinutes</b></td> |
| 152 | + <td>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.</td> |
| 153 | + <td>10</td> |
| 154 | + </tr> |
| 155 | +</table> |
| 156 | + |
| 157 | +### Slider |
| 158 | +<table> |
| 159 | + <tr> |
| 160 | + <th>Attribute</th> |
| 161 | + <th>Description</th> |
| 162 | + <th>Default</th> |
| 163 | + </tr> |
| 164 | + <tr> |
| 165 | + <td><b>trp_sliderWidth</b></td> |
| 166 | + <td>The width of the slider wheel.</td> |
| 167 | + <td>8dp</td> |
| 168 | + </tr> |
| 169 | + <tr> |
| 170 | + <td><b>trp_sliderColor</b></td> |
| 171 | + <td>The background color of the slider wheel.</td> |
| 172 | + <td>#E1E1E1</td> |
| 173 | + </tr> |
| 174 | + </tr> |
| 175 | + <tr> |
| 176 | + <td><b>trp_sliderRangeColor</b></td> |
| 177 | + <td>The color of the active part of the slider wheel.</td> |
| 178 | + <td>?android:colorPrimary</td> |
| 179 | + </tr> |
| 180 | + </tr> |
| 181 | + <tr> |
| 182 | + <td><b>trp_sliderRangeGradientStart</b></td> |
| 183 | + <td>Set the starting gradient color of the active part of the slider wheel.<br><br>Please note that both <i>trp_sliderRangeGradientStart</i> and <i>trp_sliderRangeGradientEnd</i> need to be configured.<br><br><b>Tip:</b> Set the <i>thumbColor</i> to transparent to mimic the Apple iOS slider.</td> |
| 184 | + <td></td> |
| 185 | + </tr> |
| 186 | + </tr> |
| 187 | + <tr> |
| 188 | + <td><b>trp_sliderRangeGradientStart</b></td> |
| 189 | + <td>Optional for gradient: set the middle gradient color of the active part of the slider wheel.</td> |
| 190 | + <td></td> |
| 191 | + </tr> |
| 192 | + </tr> |
| 193 | + <tr> |
| 194 | + <td><b>trp_sliderRangeGradientEnd</b></td> |
| 195 | + <td>Set the ending gradient color of the active part of the slider wheel.<br><br>Please note that both <i>trp_sliderRangeGradientStart</i> and <i>trp_sliderRangeGradientEnd</i> need to be configured.</td> |
| 196 | + <td></td> |
| 197 | + </tr> |
| 198 | +</table> |
| 199 | + |
| 200 | +### Thumb |
| 201 | +<table> |
| 202 | + <tr> |
| 203 | + <th>Attribute</th> |
| 204 | + <th>Description</th> |
| 205 | + <th>Default</th> |
| 206 | + </tr> |
| 207 | + <tr> |
| 208 | + <td><b>trp_thumbIconStart</b></td> |
| 209 | + <td>Set the start thumb icon.</td> |
| 210 | + <td></td> |
| 211 | + </tr> |
| 212 | + <tr> |
| 213 | + <td><b>trp_thumbIconEnd</b></td> |
| 214 | + <td>Set the end thumb icon.</td> |
| 215 | + <td></td> |
| 216 | + </tr> |
| 217 | + <tr> |
| 218 | + <td><b>trp_thumbSize</b></td> |
| 219 | + <td>The size of both the starting and ending thumb.</td> |
| 220 | + <td>28dp</td> |
| 221 | + </tr> |
| 222 | + <tr> |
| 223 | + <td><b>trp_thumbSizeActiveGrow</b></td> |
| 224 | + <td>The amount of growth of the size when a thumb is being dragged.</td> |
| 225 | + <td>1.2</td> |
| 226 | + </tr> |
| 227 | + <tr> |
| 228 | + <td><b>trp_thumbColor</b></td> |
| 229 | + <td>The background color of the thumbs.</td> |
| 230 | + <td>?android:colorPrimary</td> |
| 231 | + </tr> |
| 232 | + <tr> |
| 233 | + <td><b>trp_thumbIconColor</b></td> |
| 234 | + <td>The color (tint) of the icons inside the thumbs.</td> |
| 235 | + <td>white</td> |
| 236 | + </tr> |
| 237 | + <tr> |
| 238 | + <td><b>trp_thumbIconSize</b></td> |
| 239 | + <td>The size of the thumb icons.</td> |
| 240 | + <td>24dp</td> |
| 241 | + </tr> |
| 242 | +</table> |
| 243 | + |
| 244 | +### Clock |
| 245 | +<table> |
| 246 | + <tr> |
| 247 | + <th>Attribute</th> |
| 248 | + <th>Description</th> |
| 249 | + <th>Default</th> |
| 250 | + </tr> |
| 251 | + <tr> |
| 252 | + <td><b>trp_clockVisible</b></td> |
| 253 | + <td>Whether the clock face in the middle should be visible.</td> |
| 254 | + <td>true</td> |
| 255 | + </tr> |
| 256 | + <tr> |
| 257 | + <td><b>trp_clockFace</b></td> |
| 258 | + <td>There a two different clock faces (appearance of the inner clock) you can use, both mimicking the Clock apps:<br> |
| 259 | + <b>APPLE</b><br> |
| 260 | + <img src="./art/face-apple.png" width="200"><br> |
| 261 | + <b>SAMSUNG</b><br> |
| 262 | + <img src="./art/face-samsung.png" width="200"> |
| 263 | + </td> |
| 264 | + <td>APPLE</td> |
| 265 | + </tr> |
| 266 | + <tr> |
| 267 | + <td><b>trp_clockLabelSize</b></td> |
| 268 | + <td>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).</td> |
| 269 | + <td>16sp</td> |
| 270 | + </tr> |
| 271 | + <tr> |
| 272 | + <td><b>trp_clockLabelColor</b></td> |
| 273 | + <td>Set the text color of the hour labels in the clock.</td> |
| 274 | + <td>?android:textColorPrimary</td> |
| 275 | + </tr> |
| 276 | + <tr> |
| 277 | + <td><b>trp_clockIndicatorColor</b></td> |
| 278 | + <td>Set the color of the small time indicator lines in the clock.</td> |
| 279 | + <td>?android:textColorPrimary</td> |
| 280 | + </tr> |
| 281 | +</table> |
| 282 | + |
| 283 | +## Credits |
| 284 | +- Samsung's and Apple's Clock app have been used for inspiration, as they both implement this picker differently. |
| 285 | + |
| 286 | +## License |
| 287 | +``` |
| 288 | +MIT License |
| 289 | +
|
| 290 | +Copyright (c) 2021 Joery Droppers (https://github.com/Droppers) |
| 291 | +
|
| 292 | +Permission is hereby granted, free of charge, to any person obtaining a copy |
| 293 | +of this Software and associated documentation files (the "Software"), to deal |
| 294 | +in the Software without restriction, including without limitation the rights |
| 295 | +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell |
| 296 | +copies of the Software, and to permit persons to whom the Software is |
| 297 | +furnished to do so, subject to the following conditions: |
| 298 | +
|
| 299 | +The above copyright notice and this permission notice shall be included in all |
| 300 | +copies or substantial portions of the Software. |
| 301 | +
|
| 302 | +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR |
| 303 | +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, |
| 304 | +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE |
| 305 | +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER |
| 306 | +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, |
| 307 | +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE |
| 308 | +SOFTWARE. |
| 309 | +``` |
0 commit comments