compose-audio-controls/org.androidaudioplugin.composeaudiocontrols/ImageStripKnob

ImageStripKnob

fun ImageStripKnob(modifier: Modifier = Modifier, @DrawableRes drawableResId: Int, value: Float = 0.0f, valueRange: ClosedFloatingPointRange<Float> = 0f..1f, explicitSizeInDp: Dp? = null, minSizeInDp: Dp = defaultKnobMinSizeInDp, fineModeDelayMs: Int = 1000, tooltipColor: Color = Color.Gray, tooltip: @Composable ImageStripKnobScope.() -> Unit = { // by default, show tooltip only when it is being dragged DefaultKnobTooltip( value = knobValue, showTooltip = knobIsBeingDragged, textColor = tooltipColor ) }, onValueChange: (value: Float) -> Unit = {})

Implements a knob control that is based on KnobMan image strip. See another ImageStripKnob() for more details.

This Android-only function overload takes a drawable resource ID (drawableResId) to ease image loading. (Since we use our own ScalingPainter, we cannot simply use painterResource() to this function.)

Parameters

modifier

A Modifier to be applied to this knob control.

drawableResId

The Android Resource Id for this knob.

value

The value that this knob should render for. It should be within the range between minValue and maxValue.

valueRange

The value range. It defaults to 0f..1f.

explicitSizeInDp

An optional size in Dp if you want an explicit rendered widget size instead of the sizes in image, in Dp.

minSizeInDp

The minimum rendered widget size in Dp. It defaults to 48.dp which is the minimum recommended widget size by Android Accessibility Help.

tooltipColor

The color of the default implementation of the value label tooltip.

tooltip

The tooltip Composable which may be rendered in response to user's drag action over this knob.

onValueChange

An event handler function that takes the changed value. See the documentation for ImageStripKnob function for details.

@Composable

fun ImageStripKnob(modifier: Modifier = Modifier, imageBitmap: ImageBitmap, value: Float = 0.0f, valueRange: ClosedFloatingPointRange<Float> = 0f..1f, explicitSizeInDp: Dp? = null, minSizeInDp: Dp = defaultKnobMinSizeInDp, fineModeDelayMs: Int = 1000, tooltipColor: Color = Color.Gray, tooltip: @Composable ImageStripKnobScope.() -> Unit = { // by default, show tooltip only when it is being dragged DefaultKnobTooltip( value = knobValue, showTooltip = knobIsBeingDragged, textColor = tooltipColor ) }, onValueChange: (value: Float) -> Unit = {})

Implements a knob control that is based on KnobMan image strip. If you are not familiar with KnobMan, see this KVR page.

Using ImageStripKnob

Start dragging vertically from the knob to change the value within the range between minValue and maxValue arguments. You only need one finger. No pinch required.

If you hold over the knob for 1000 milliseconds (by default), it will enter "fine mode" where the value change is multiplied by 0.1.

Value labels are rendered when it is dragged below the knob, by default.

The knob is designed to minimize the space but also usable with human fingertips, by default (48.dp minSizeInDp).

We currently do not assign anything for horizontal dragging by intention. It is preserved for users who want to move out their finger of the knob and tooltip label. Thus it is recommended to NOT assign another single-fingered drag operation over the knob.

The whole min-to-max value change height on screen is 160.dp which would be rational for most use cases. We may change this behavior in the future versions.

This function overload takes a ImageBitmap. For Android drawable resources, you can use another ImageStripKnob() overload that takes the resource ID.

value label tooltip

By default, it shows a value label tooltip when the knob is dragged.

It is possible to customize the label behavior by passing tooltip argument. It is a Composable rendered after the Image in a Column. You can use DefaultKnobTooltip to slightly modify the default behavior, namely:

always show label (even not on dragging): DefaultKnobTooltip(value, true)
customize text color: DefaultKnobTooltip(value, knobIsBeingDragged, yourPreferredColor)
move up, down, etc. : pass modifier to DefaultKnobTooltip that is applied to Text (visible) or Box (invisible space)

The knob state is provided as ImageStripKnobScope interface.

Usage example

Here is an example use of ImageStripKnob():

var paramValue by remember { mutableStateOf(0f) }
Text("Parameter $paramIndex: ")
ImageStripKnob(
    drawableResId = R.drawable.knob_image,
    value = paramValue,
    onValueChange = {v ->
        paramValue = v
        println("value at $paramIndex changed: $v")
        })