Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/2307vivek/Seeker
A highly customizable seekbar/slider library for android with support for readahead indicator, segments and more. Made with Jetpack Compose ❤.
https://github.com/2307vivek/Seeker
android android-library jetpack-compose jetpack-compose-library kotlin kotlin-android seekbar seekbar-android slider
Last synced: 9 days ago
JSON representation
A highly customizable seekbar/slider library for android with support for readahead indicator, segments and more. Made with Jetpack Compose ❤.
- Host: GitHub
- URL: https://github.com/2307vivek/Seeker
- Owner: 2307vivek
- License: apache-2.0
- Created: 2023-01-30T12:40:47.000Z (almost 2 years ago)
- Default Branch: main
- Last Pushed: 2024-10-31T17:59:07.000Z (16 days ago)
- Last Synced: 2024-10-31T18:33:21.506Z (15 days ago)
- Topics: android, android-library, jetpack-compose, jetpack-compose-library, kotlin, kotlin-android, seekbar, seekbar-android, slider
- Language: Kotlin
- Homepage:
- Size: 391 KB
- Stars: 379
- Watchers: 5
- Forks: 14
- Open Issues: 16
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
- awesome-list - 2307vivek/Seeker - A highly customizable seekbar/slider library for android with support for readahead indicator, segments and more. Made with Jetpack Compose ❤. (Kotlin)
README
# Seeker
**Seeker** is a highly customizable seekbar/slider for Android with support for **readahead indicator** and **segments**. Made with Jetpack Compose ❤.
[](https://github.com/2307vivek/Seeker/actions)
[]((https://github.com/2307vivek/Seeker/actions))
## Including in your project
[](https://search.maven.org/search?q=g:io.github.2307vivek)
### Gradle
Add the dependency below to your **module**'s `build.gradle` file:
```gradle
dependencies {
implementation 'io.github.2307vivek:seeker:1.2.2'
}
```
## How to use
You can create a Seeker with the `Seeker` composable.
```kotlin
@Composable
fun Seeker(
modifier: Modifier = Modifier,
state: SeekerState = rememberSeekerState(),
value: Float,
range: ClosedFloatingPointRange = 0f..1f,
readAheadValue: Float = range.start,
onValueChange: (Float) -> Unit,
onValueChangeFinished: (() -> Unit)? = null,
segments: List = emptyList(),
enabled: Boolean = true,
colors: SeekerColors = SeekerDefaults.seekerColors(),
dimensions: SeekerDimensions = SeekerDefaults.seekerDimensions(),
interactionSource: MutableInteractionSource = remember { MutableInteractionSource() },
)
```
In its simplest form **seeker** can be used as a regular slider for selecting values from a range or showing progress in a range.
```kotlin
var value by remember { mutableStateOf(0f) }
Seeker(
value = value,
range = 1f..100f,
onValueChange = { value = it }
)
```
### Read Ahead indicator
A read-ahead indicator shows the amount of content that is already ready to use. It is particularly useful in media streaming apps where some media is downloaded ahead of time to avoid buffering. The `readAheadValue` property of the Seeker composable can be used to display the read ahead indicator.
```kotlin
var value by remember { mutableStateOf(0f) }
var readAheadValue by remember { mutableStateOf(0f) }
Seeker(
value = value,
readAheadValue = readAheadValue,
range = 1f..100f,
onValueChange = { value = it }
)
```
### Creating Segments
Seeker can break the track into different sections, which can be used to display different parts in the range. To create segments, a list of `Segment` needs to be passed in the `Seeker` composable.
```kotlin
val segments = listOf(
Segment(name = "Intro", start = 1f),
Segment(name = "Part 1", start = 40f),
Segment(name = "Part 2", start = 88f),
)
Seeker(
value = value,
readAheadValue = readAheadValue,
range = 1f..100f,
segments = segments,
onValueChange = { value = it }
)
```
The `Segment` takes the `name` and the `start` value form which the segments shlould start. You can also pass an optional color parameter to each segment.
The first segment in the list **must start from the start point of the range, and all the segments must lie in the range** of the seeker, otherwise an `IllegalArgumentException` will be thrown to avoid unexpected behavior.
**Segments** are by default separated by a gap in the track, which can be customized by passing a `dimensions` parameter in the composable.
```kotlin
Seeker(
value = value,
readAheadValue = readAheadValue,
range = 1f..100f,
segments = segments,
dimensions = SeekerDefaults.seekerDimensions(gap = 4.dp),
onValueChange = { value = it }
)
```
### Observing current segment
The current segment corresponding to the current seeker value can be observed by using the `currentSegment` property of the `SeekerState` which can be created by using `rememberSeekerState()`.
```kotlin
val segments = listOf(
Segment(name = "Intro", start = 1f),
Segment(name = "Part 1", start = 40f),
Segment(name = "Part 2", start = 88f),
)
val state = rememberSeekerState()
Seeker(
state = state,
value = value,
readAheadValue = readAheadValue,
range = 1f..100f,
segments = segments,
onValueChange = { value = it }
)
//Observing the current segment
Text(state.currentSegment.name)
```
## Customizing Seeker
Seeker is highly customizable in terms of its dimensions and colors. The `seekerColors()` and `seekerDimensions()` functions can be used to customise the colors and dimensions of the different parts of seeker.
The `seekerColors()` and `seekerDimensions()` functions are as follows:
```kotlin
@Composable
fun seekerColors(
progressColor: Color = MaterialTheme.colors.primary,
trackColor: Color = TrackColor,
disabledProgressColor: Color = MaterialTheme.colors.onSurface.copy(alpha = DisabledProgressAlpha),
disabledTrackColor: Color = disabledProgressColor.copy(alpha = DisabledTrackAlpha).compositeOver(MaterialTheme.colors.onSurface),
thumbColor: Color = MaterialTheme.colors.primary,
disabledThumbColor: Color = MaterialTheme.colors.onSurface.copy(alpha = ContentAlpha.disabled).compositeOver(MaterialTheme.colors.surface),
readAheadColor: Color = ReadAheadColor
): SeekerColors
@Composable
fun seekerDimensions(
trackHeight: Dp = TrackHeight,
progressHeight: Dp = trackHeight,
thumbRadius: Dp = ThumbRadius,
gap: Dp = Gap
): SeekerDimensions
```
The seeker composable has parameters `colors` and `dimensions` which can be used to customize the colors and dimensions of the seeker respectively.
```kotlin
Seeker(
value = value,
readAheadValue = readAheadValue,
range = 1f..100f,
segments = segments,
colors = SeekerDefaults.colors(trackColor = customColor, thumbColor = customThumbColor, ...)
dimensions = SeekerDefaults.seekerDimensions(gap = 4.dp, thumbRadius = 12.dp, ...),
onValueChange = { value = it }
)
```
> **Note**: As of the current version, unexpected behaviors are noted when colors with an alpha value less than 1f are used in the seeker. You shluld avoid using transparent colors in seeker. See issue [#12](https://github.com/2307vivek/Seeker/issues/12).
The above functions are `@Composables` which means it will be recomposed when the parameters change. It can be used to animate the colors and dimensions of seeker.
```kotlin
val interactionSource = remember { MutableInteractionSource() }
val isDragging by interactionSource.collectIsDraggedAsState()
val gap by animateDpAsState(if (isDragging) 2.dp else 0.dp)
val thumbRadius by animateDpAsState(if (isDragging) 10.dp else 0.dp)
Seeker(
value = value,
readAheadValue = readAheadValue,
range = 1f..100f,
segments = segments,
interactionSource = interactionSource,
colors = SeekerDefaults.colors(trackColor = customColor, thumbColor = customThumbColor)
dimensions = SeekerDefaults.seekerDimensions(gap = gap, thumbRadius = thumbRadius),
onValueChange = { value = it }
)
```
### Using different value for thumb
Seeker has the ability to provide a separate value for the thumb, which makes it possible to move the thumb independently of the progress.
```kotlin
var value by remember{ mutableStateOf(0f) }
var thumbPosition by remember{ mutableStateOf(0f) }
val isDragging by interactionSource.collectIsDraggedAsState()
Seeker(
value = value,
thumbValue = if (isDragging) thumbPosition else value,
onValueChange = { thumbPosition = it },
onValueChangeFinished = { value = thumbPosition },
readAheadValue = readAheadValue,
interactionSource = interactionSource,
range = 1f..100f,
...
)
```
### Making two-way Seeker
You can also make a two-way slider by providing the start position as a fraction of the track width using the `progressStartPosition` parameter.
```kotlin
var value by remember { mutableStateOf(0f) }
Seeker(
value = value,
progressStartPosition = 0.3f,
range = 1f..100f,
onValueChange = { value = it }
)
```
## Find this library useful? :heart:
Support it by joining __[stargazers](https://github.com/2307vivek/seeker/stargazers)__ for this repository. :star:
Also, follow me on __[github](https://github.com/2307vivek)__ and __[twitter](https://twitter.com/2307vivek)__ to stay updated with my creations! 🤩
# License
```xml
Copyright 2023 Vivek Singh
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
```