Seeker

Seeker is a highly customisable seekbar/slider for android with support for readahead indicator and segments. Made with Jetpack Compose ❤.

Including in your project

Gradle

Add the dependency below to your module's build.gradle file:

dependencies {
    implementation 'io.github.2307vivek:seeker:1.1.1'
}

How to use

You can create a Seeker with the Seeker composable.

@Composable
fun Seeker(
    modifier: Modifier = Modifier,
    state: SeekerState = rememberSeekerState(),
    value: Float,
    range: ClosedFloatingPointRange<Float> = 0f..1f,
    readAheadValue: Float = range.start,
    onValueChange: (Float) -> Unit,
    onValueChangeFinished: (() -> Unit)? = null,
    segments: List<Segment> = 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.

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 which is already ready to use. It is particularly useful in media streaming apps where some media is downloaded ahead of time to avoid bufferring. The readAheadValue property of the Seeker composable can be used to display the read ahead indicator.

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.

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 seperated by a gap in the track, which can be customized by passing a dimensions parameter in the composable.

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().

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:

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

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.

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.

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 seperate value for the thumb, which makes it possible to move the thumb independent of the progress.

val position by viewModel.position.collectAsState()
var thumbPosition by remember{ mutableStateOf(0f) }

val isDragging by interactionSource.collectIsDraggedAsState()

Seeker(
    value = value,
    thumbValue = if (isDragging) thumbPosition else position,
    onValueChange = { thumbPosition = it },
    onValueChangeFinished = { value = thumbPosition },
    readAheadValue = readAheadValue,
    interactionSource = interactionSource,
    range = 1f..100f,
    ...
)

Find this library useful? ❤️

Support it by joining stargazers for this repository. ⭐
Also, follow me on github and twitter to stay updated with my creations! 🤩

License

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.

2307vivek/Seeker

2307vivek

Reviews

Repository Details